net-imap 0.6.3 → 0.6.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4249dc5d175bd3ae3a3b3b79e0f368e674ec96045510a8b504e829feefb54f3d
-  data.tar.gz: 6adbee15b0303b36ec1c574991d4bdbf518bcd5621c6b668f05df0bc201ba50a
+  metadata.gz: 032600f694434b77edab2496c4bff9a7adc5c912301c0a7b386706dfccdc2345
+  data.tar.gz: 69dd23250cda6c1eb7a9bbeabe10969389c10047f12610d6bec3407d23e16854
 SHA512:
-  metadata.gz: a20c230ac3977d9acc09bc964badc60acbedaca84246d1ce67787c78443cdea350ade6907e58b61a5c9f09bf3b12e5e57cd319ef82a096c3780f97dc7017ed31
-  data.tar.gz: 68ab8b48664998bbf05d5367fea4e5b06e3ba3b2d4e48ba8ae026069060b23f7dafaf7ecf2681fc5aa4ff0f134e55d9399ca51456ff3a7ec718ba829629866b7
+  metadata.gz: 98ede1ee28c608ceea04bd5a00a114029da96eae454dc222cb046308c625241df423ceac7811322e6f641f3899ba1ca7a7d3f1bbfbf839632d2cf1a01c963c59
+  data.tar.gz: 810b3514de99b738216d7d49c917a05ee0c73211530bd81fe55540d158736dd7ba84f841d13f6d959b3dca01c3e32d792e500e7ee8f8eb5a2ab6899a53bf095e

data/.document

@@ -0,0 +1,3 @@
+*.rdoc
+*.md
+lib

data/.rdoc_options

@@ -0,0 +1,7 @@
+---
+charset: UTF-8
+main_page: README.md
+markup: rdoc
+title: net-imap # rake task override's title to add the version number
+op_dir: doc
+# vim:ft=yaml

data/Gemfile

@@ -11,7 +11,7 @@ gem "psych", ">= 5.3.0" # 5.2.5 for Data serialization, 5.3.0 for TruffleRuby
 
 gem "irb"
 gem "rake"
-gem "rdoc"
+gem "rdoc", ">= 7.2.0"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 

data/README.md

@@ -61,9 +61,9 @@ imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_i
   else
     imap.copy(message_id, "Mail/sent-apr03")
     imap.store(message_id, "+FLAGS", [:Deleted])
+    imap.expunge
   end
 end
-imap.expunge
 ```
 
 ## Development

data/lib/net/imap/command_data.rb

@@ -4,6 +4,8 @@ require "date"
 
 require_relative "errors"
 
+# :enddoc:
+
 module Net
   class IMAP < Protocol
 
@@ -14,17 +16,19 @@ module Net
       when nil
       when String
       when Integer
-        NumValidator.ensure_number(data)
+        # Covers modseq-valzer, which is the largest valid IMAP integer
+        if data.negative?
+          raise DataFormatError, "Integer argument must be unsigned: #{data}"
+        elsif 0xffff_ffff_ffff_ffff < data
+          raise DataFormatError, "Integer argument must fit in 64 bits: #{data}"
+        end
       when Array
-        if data[0] == 'CHANGEDSINCE'
-          NumValidator.ensure_mod_sequence_value(data[1])
-        else
-          data.each do |i|
-            validate_data(i)
-          end
+        data.each do |i|
+          validate_data(i)
         end
       when Time, Date, DateTime
       when Symbol
+        Flag.validate(data)
       else
         data.validate
       end
@@ -45,7 +49,7 @@ module Net
       when Date
         send_date_data(data)
       when Symbol
-        send_symbol_data(data)
+        Flag[data].send_data(self, tag)
       else
         data.send_data(self, tag)
       end
@@ -73,13 +77,33 @@ module Net
       end
     end
 
-    def send_quoted_string(str)
-      put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
-    end
+    def send_quoted_string(str) = QuotedString.new(data: str).send_data(self)
 
-    def send_literal(str, tag = nil)
+    def send_binary_literal(*, **) = send_literal(*, **, binary: true)
+
+    # `non_sync` is an optional tri-state flag:
+    # * `true`  -> Force non-synchronizing `LITERAL+`/`LITERAL-` behavior.
+    #   NOTE: raises DataFormatError when server doesn't support
+    #   non-synchronizing literal, or literal is too large for LITERAL-.
+    # * `false` -> Force normal synchronizing literal behavior.
+    # * `nil`   -> (default) Currently behaves like `false` (will be dynamic).
+    def send_literal(str, tag = nil, binary: false, non_sync: nil)
+      bytesize = str.bytesize
       synchronize do
-        put_string("{" + str.bytesize.to_s + "}" + CRLF)
+        if non_sync && !non_sync_literal_allowed?(bytesize)
+          # TODO: check in Printer, so we don't need to close the connection.
+          @sock.close
+          raise DataFormatError, "Connection closed: " \
+            "Cannot send non-synchronizing literal without known server support"
+        end
+        non_sync = non_sync_literal?(bytesize) if non_sync.nil?
+        prefix = "~" if binary
+        plus = "+" if non_sync
+        put_string("#{prefix}{#{bytesize}#{plus}}\r\n")
+        if non_sync
+          put_string(str)
+          return
+        end
         @continued_command_tag = tag
         @continuation_request_exception = nil
         begin
@@ -94,8 +118,23 @@ module Net
       end
     end
 
+    def non_sync_literal?(bytesize)
+      bytesize <= config.max_non_synchronizing_literal \
+        && non_sync_literal_allowed?(bytesize)
+    end
+
+    def non_sync_literal_allowed?(bytesize)
+      return unless capabilities_cached?
+      return "+" if capable?("LITERAL+")
+      return "-" if capable_literal_minus? && bytesize <= 4096
+      false
+    end
+
+    def capable_literal_minus? = capable?("LITERAL-") || capable?("IMAP4rev2")
+
+    # NOTE: +num+ should already be an Integer
     def send_number_data(num)
-      put_string(num.to_s)
+      put_string(Integer(num).to_s)
     end
 
     def send_list_data(list, tag = nil)
@@ -115,11 +154,13 @@ module Net
     def send_date_data(date) put_string Net::IMAP.encode_date(date) end
     def send_time_data(time) put_string Net::IMAP.encode_time(time) end
 
-    def send_symbol_data(symbol)
-      put_string("\\" + symbol.to_s)
-    end
-
     CommandData = Data.define(:data) do # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
       def send_data(imap, tag)
         raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
@@ -128,27 +169,176 @@ module Net
       end
     end
 
+    # Represents IMAP +text+ or +quoted+ data, which share the same
+    # validations of decoded #data, and differ only in how they are formatted.
+    #
+    # +data+ may contain any 7-bit ASCII character except +NULL+, +CR+, or +LF+.
+    # Any multibyte +UTF-8+ character is also allowed when the connection
+    # supports UTF8: either +UTF8=ACCEPT+ or +IMAP4rev2+ have been enabled, or
+    # the server supports only +IMAP4rev2+ and not earlier IMAP revisions, or
+    # the server advertises +UTF8=ONLY+.
+    #
+    # NOTE: This does not verify whether the connection supports UTF-8, but that
+    # may change in future versions.
+    #
+    # The string's bytes must be valid ASCII or valid UTF-8.  The string's
+    # reported encoding is ignored, but the string is _not_ transcoded.
+    class ValidNonLiteralData < CommandData
+      def initialize(data:)
+        data = String(data.to_str)
+        unless data.encoding in Encoding::ASCII | Encoding::UTF_8
+          data = data.dup.force_encoding(data.ascii_only? ? "ASCII" : "UTF-8")
+        end
+        data = -data
+        super
+        validate
+      end
+
+      def validate
+        if !(data.encoding in Encoding::ASCII | Encoding::UTF_8)
+          raise DataFormatError, "must use ASCII or UTF-8 encoding"
+        elsif !data.valid_encoding?
+          raise DataFormatError, "invalid UTF-8 must be literal encoded"
+        elsif data.include?("\0")
+          raise DataFormatError, "NULL byte must be binary literal encoded"
+        elsif /[\r\n]/.match?(data)
+          raise DataFormatError, "CR and LF bytes must be literal encoded"
+        end
+      end
+
+      def ascii_only? = data.ascii_only?
+
+      def send_data(imap, tag = nil) = imap.__send__(:put_string, formatted)
+    end
+
+    # Represents IMAP +text+ data, which covers everything in the IMAP grammar,
+    # except for +literal+, +literal8+, and the concluding +CRLF+.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class RawText < ValidNonLiteralData # :nodoc:
+      # raw: no formatting necessary
+      alias formatted data
+    end
+
     class RawData < CommandData # :nodoc:
-      def send_data(imap, tag)
-        imap.__send__(:put_string, data)
+      def initialize(data:)
+        case data
+        in String then data = self.class.split(data)
+        in Array  if   data.all? { _1 in RawText | Literal }
+        else
+          raise TypeError, "expected String or Array[#{RawText} | #{Literal}]"
+        end
+        super
+        validate
       end
+
+      def send_data(imap, tag) = data.each do _1.send_data(imap, tag) end
+
+      def validate
+        return unless data.last in RawText(data: text)
+        if text.rindex(/\{\d+\+?\}\z/n)
+          raise DataFormatError, "RawData cannot end with literal continuation"
+        end
+      end
+
+      # Splits an input +string+ into an array of RawText and Literal/Literal8.
+      #
+      # NOTE: unlike RawData#validate, this does not prevent the final RawText
+      # from ending with a literal prefix.
+      def self.split(data)
+        data = data.b # dups and ensures BINARY encoding
+        parts = []
+        while data.match(/(~)?\{(0|[1-9]\d*)(\+)?\}\r\n/n)
+          text, binary, bytesize, non_sync, data = $`, !!$1, $2, !!$3, $'
+          bytesize = NumValidator.coerce_number64 bytesize
+          parts << RawText[text] unless text.empty?
+          parts << extract_literal(data, binary:, bytesize:, non_sync:)
+          data.bytesplice(0, bytesize, "")
+        end
+        parts << RawText[data] unless data.empty?
+        parts
+      end
+
+      def self.extract_literal(data, binary:, bytesize:, non_sync:)
+        if data.bytesize < bytesize
+          raise DataFormatError, "Too few bytes in string for literal, " \
+            "expected: %s, remaining: %s" % [bytesize, data.bytesize]
+        end
+        literal = data.byteslice(0, bytesize)
+        (binary ? Literal8 : Literal).new(data: literal, non_sync:)
+      end
+      private_class_method :extract_literal
     end
 
     class Atom < CommandData # :nodoc:
+      def initialize(**)
+        super
+        validate
+      end
+
+      def validate
+        data.to_s.ascii_only? \
+          or raise DataFormatError, "#{self.class} must be ASCII only"
+        data.match?(ResponseParser::Patterns::ATOM_SPECIALS) \
+          and raise DataFormatError, "#{self.class} must not contain atom-specials"
+        data.empty? \
+          and raise DataFormatError, "#{self.class} must not be empty"
+      end
+
       def send_data(imap, tag)
-        imap.__send__(:put_string, data)
+        imap.__send__(:put_string, data.to_s)
       end
     end
 
-    class QuotedString < CommandData # :nodoc:
+    class Flag < Atom # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_quoted_string, data)
+        imap.__send__(:put_string, "\\#{data}")
       end
     end
 
-    class Literal < CommandData # :nodoc:
+    # Represents a IMAP +quoted+ string, which can encode any valid ASCII or
+    # UTF-8 string, unless it contains any +CR+, +LF+, or +NULL+ bytes.
+    #
+    # NOTE: The current implementation does not verify that the connection
+    # supports UTF-8.  Future versions may validate this.
+    class QuotedString < ValidNonLiteralData # :nodoc:
+      def formatted = %("#{data.gsub(/["\\]/, "\\\\\\&")}")
+    end
+
+    class Literal < Data.define(:data, :non_sync) # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
+      end
+
+      def initialize(data:, non_sync: nil)
+        data = -String(data.to_str).b or
+          raise DataFormatError, "#{self.class} expects string input"
+        super
+        validate
+      end
+
+      def bytesize = data.bytesize
+
+      def validate
+        if data.include?("\0")
+          raise DataFormatError, "NULL byte not allowed in #{self.class}.  " \
+            "Use #{Literal8} or a null-safe encoding."
+        end
+      end
+
       def send_data(imap, tag)
-        imap.__send__(:send_literal, data, tag)
+        imap.__send__(:send_literal, data, tag, non_sync:)
+      end
+    end
+
+    class Literal8 < Literal # :nodoc:
+      def validate = nil # all bytes are okay
+
+      def send_data(imap, tag)
+        imap.__send__(:send_binary_literal, data, tag, non_sync:)
       end
     end
 
@@ -221,6 +411,14 @@ module Net
 
       module_function
 
+      def literal_or_literal8(input, name: "argument")
+        return input if input in Literal | Literal8
+        data = String.try_convert(input) \
+          or raise TypeError, "expected #{name} to be String, got #{input.class}"
+        type = data.include?("\0") ? Literal8 : Literal
+        type.new(data:)
+      end
+
       # Allows symbols in addition to strings
       def valid_string?(str)
         str.is_a?(Symbol) || str.respond_to?(:to_str)

data/lib/net/imap/config.rb

@@ -281,6 +281,40 @@ module Net
         0.5r => true,
       }
 
+      # The maximum bytesize for sending non-synchronizing literals, when the
+      # server supports them.  To disable non-synchronizing literals, set the
+      # value to +-1+.
+      #
+      # Non-synchronizing literals are only sent when the server's
+      # capabilities[rdoc-ref:IMAP#capabilities] have been
+      # cached[rdoc-ref:IMAP#capabilities_cached?] and include either
+      # <tt>LITERAL+</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]],
+      # <tt>LITERAL-</tt> [RFC7888[https://www.rfc-editor.org/rfc/rfc7888]], or
+      # +IMAP4rev2+ [RFC9051[https://www.rfc-editor.org/rfc/rfc9051]].
+      #
+      # For <tt>LITERAL+</tt>, this value is the only limit on whether a literal
+      # value is sent as non-synchronizing literals.  For <tt>LITERAL-</tt> and
+      # <tt>IMAP4rev2</tt>, non-synchronizing literals must also be smaller than
+      # +4096+ bytes.
+      #
+      # Non-synchronizing literals avoid the latency of waiting for the server
+      # to allow continuation.  However, if a client sends a non-synchronizing
+      # literal that is too large for the server, the server may need to close
+      # the connection.  Because <tt>LITERAL+</tt> does not directly indicate
+      # the server's limits, it's best to avoid sending very large
+      # non-synchronized literals.
+      #
+      # ==== Versioned Defaults
+      #
+      # max_non_synchronizing_literal <em>was added in +v0.6.4+.</em>
+      #
+      # * original: +-1+ (_never_ send non-synchronizing literals)
+      # * +0.6+: 16 KiB
+      attr_accessor :max_non_synchronizing_literal, type: Integer, defaults: {
+        0.0r => -1,
+        0.6r => 16 << 16, # 16 KiB
+      }
+
       # The maximum allowed server response size.  When +nil+, there is no limit
       # on response size.
       #

data/lib/net/imap/data_encoding.rb

@@ -155,7 +155,8 @@ module Net
 
     # Common validators of number and nz_number types
     module NumValidator # :nodoc
-      NUMBER_RE = /\A(?:0|[1-9]\d*)\z/
+      NUMBER_RE = /\A\d+\z/
+      NZ_NUMBER_RE = /\A[1-9]\d*\z/
       module_function
 
       # Check if argument is a valid 'number' according to RFC 3501
@@ -174,6 +175,22 @@ module Net
         0 < num && num <= 0xffff_ffff
       end
 
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     number64        = 1*DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 <= n <= 9,223,372,036,854,775,807)
+      def valid_number64?(num)
+        0 <= num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
+      # Check if argument is a valid 'number64' according to RFC 9051
+      #     nz-number64     = digit-nz *DIGIT
+      #                        ; Unsigned 63-bit integer
+      #                        ; (0 < n <= 9,223,372,036,854,775,807)
+      def valid_nz_number64?(num)
+        0 < num && num <= 0x7fff_ffff_ffff_ffff
+      end
+
       # Check if argument is a valid 'mod-sequence-value' according to RFC 4551
       #     mod-sequence-value  = 1*DIGIT
       #                            ; Positive unsigned 64-bit integer
@@ -203,6 +220,20 @@ module Net
           "nz-number must be non-zero unsigned 32-bit integer: #{num}"
       end
 
+      # Ensure argument is 'number64' or raise DataFormatError
+      def ensure_number64(num)
+        return num if valid_number64?(num)
+        raise DataFormatError,
+          "number64 must be unsigned 63-bit integer: #{num}"
+      end
+
+      # Ensure argument is 'nz-number64' or raise DataFormatError
+      def ensure_nz_number64(num)
+        return num if valid_nz_number64?(num)
+        raise DataFormatError,
+          "nz-number64 must be non-zero unsigned 63-bit integer: #{num}"
+      end
+
       # Ensure argument is 'mod-sequence-value' or raise DataFormatError
       def ensure_mod_sequence_value(num)
         return num if valid_mod_sequence_value?(num)
@@ -221,7 +252,7 @@ module Net
       def coerce_number(num)
         case num
         when Integer   then ensure_number num
-        when NUMBER_RE then ensure_number Integer num
+        when NUMBER_RE then ensure_number num.to_i
         else
           raise DataFormatError, "%p is not a valid number" % [num]
         end
@@ -230,18 +261,38 @@ module Net
       # Like #ensure_nz_number, but usable with numeric String input.
       def coerce_nz_number(num)
         case num
-        when Integer   then ensure_nz_number num
-        when NUMBER_RE then ensure_nz_number Integer num
+        when Integer      then ensure_nz_number num
+        when NZ_NUMBER_RE then ensure_nz_number num.to_i
         else
           raise DataFormatError, "%p is not a valid nz-number" % [num]
         end
       end
 
+      # Like #ensure_number64, but usable with numeric String input.
+      def coerce_number64(num)
+        case num
+        when Integer   then ensure_number64 num
+        when NUMBER_RE then ensure_number64 num.to_i
+        else
+          raise DataFormatError, "%p is not a valid number64" % [num]
+        end
+      end
+
+      # Like #ensure_nz_number64, but usable with numeric String input.
+      def coerce_nz_number64(num)
+        case num
+        when Integer      then ensure_nz_number64 num
+        when NZ_NUMBER_RE then ensure_nz_number64 num.to_i
+        else
+          raise DataFormatError, "%p is not a valid nz-number64" % [num]
+        end
+      end
+
       # Like #ensure_mod_sequence_value, but usable with numeric String input.
       def coerce_mod_sequence_value(num)
         case num
         when Integer   then ensure_mod_sequence_value num
-        when NUMBER_RE then ensure_mod_sequence_value Integer num
+        when NUMBER_RE then ensure_mod_sequence_value num.to_i
         else
           raise DataFormatError, "%p is not a valid mod-sequence-value" % [num]
         end
@@ -251,7 +302,7 @@ module Net
       def coerce_mod_sequence_valzer(num)
         case num
         when Integer   then ensure_mod_sequence_valzer num
-        when NUMBER_RE then ensure_mod_sequence_valzer Integer num
+        when NUMBER_RE then ensure_mod_sequence_valzer num.to_i
         else
           raise DataFormatError, "%p is not a valid mod-sequence-valzer" % [num]
         end

data/lib/net/imap/errors.rb

@@ -172,18 +172,11 @@ module Net
           ]
         end
         if parser_backtrace
-          backtrace_locations&.each_with_index do |loc, idx|
-            next  if    loc.base_label.include? "parse_error"
-            break if    loc.base_label == "parse"
-            if loc.label.include?("#") # => Class#method, since ruby 3.4
-              next unless loc.label&.include?(parser_class.name)
-            else
-              next unless loc.path&.include?("net/imap/response_parser")
-            end
+          normalized_parser_backtrace.each do |idx, path, lineno, label, base_label|
             msg << "\n  %s: %s (%s:%d)" % [
               hl["%{key}caller[%{/key}%{idx}%%2d%{/idx}%{key}]%{/key}"] % idx,
-              hl["%{label}%%-30s%{/label}"] % loc.base_label,
-              File.basename(loc.path, ".rb"), loc.lineno
+              hl["%{label}%%-30s%{/label}"] % base_label,
+              File.basename(path, ".rb"), lineno
             ]
           end
         end
@@ -198,12 +191,56 @@ module Net
       def processed_string = string && pos && string[...pos]
       def remaining_string = string && pos && string[pos..]
 
+      # Returns true when all attributes are equal, except for #backtrace and
+      # #backtrace_locations which are replaced with #parser_methods.  This
+      # allows deserialized errors to be compared.
+      def ==(other)
+        return false if self.class != other.class
+        methods       = parser_methods
+        other_methods = other.parser_methods
+        message     == other.message &&
+          methods   == other_methods &&
+          string    == other.string &&
+          pos       == other.pos &&
+          lex_state == other.lex_state &&
+          token     == other.token
+      end
+
+      # Lists the methods (from #backtrace_locations or #backtrace) called on
+      # parser_class (since ruby 3.4) or which have "net/imap/response_parser"
+      # in the path (before ruby 3.4).  Most parser method names are based on
+      # rules in the IMAP grammar.
+      def parser_methods = normalized_parser_backtrace.map(&:last)
+
       private
 
+      def normalized_parser_backtrace
+        normalize_backtrace
+          .take_while {|_, _, _, _, base_label| base_label != "parse" }
+          .reject {|_, _, _, _, base_label| base_label.nil? }
+          .reject {|_, _, _, _, base_label| base_label.include? "parse_error" }
+          .select {|_, path, _, label, _|
+            if label.include?("#") # => Class#method, since ruby 3.4
+              label.include?(parser_class.name)
+            else
+              path.include?("net/imap/response_parser")
+            end
+          }
+      end
+
+      def normalize_backtrace
+        (backtrace_locations&.each_with_index&.map {|loc, idx|
+          [idx, loc.path, loc.lineno, loc.label, loc.base_label]
+        } || backtrace&.each_with_index&.map {|bt, idx|
+          [idx, *bt.match(/\A(\S+):(\d+):in [`'](.*?([\w]+[?!]?))'\z/)&.captures]
+        } || [])
+      end
+
       def default_highlight_from_env
         (ENV["FORCE_COLOR"] || "") !~ /\A(?:0|)\z/ ||
           (ENV["TERM"] || "") !~ /\A(?:dumb|unknown|)\z/i
       end
+
     end
 
     # Superclass of all errors used to encapsulate "fail" responses