net-imap 0.4.19 → 0.4.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d13d2ec5aeab6f5fce9d77841e77c690a2849d2d6393d4bac0847fcec6dcf2b
-  data.tar.gz: 2821ba41ca70465fdfc38005908ae2fa2828ecd5c3425bf407df27f2e949ea2b
+  metadata.gz: b965efa83b72d27d68fe55ce65f08ffeb696e4a4fb44219e6206a4b7dea4de91
+  data.tar.gz: 3554d7a749873b2eccec2470142315afddb4a6dd359a1d2cd6cfeacffa27d3f6
 SHA512:
-  metadata.gz: 45bb4a741d80d2097e487b3d1ca31196f97322d6104967c6cad6410d65321e372667a6ff5bbb5bf9aafbdddc7906c7fc05b88c2fff06984dc9efd8a309802ecc
-  data.tar.gz: '08acdba3fdc323f01bc593ac7fde03ed5e06f1265be821263213fd53714b647e81305713d6829b67adba55dfb541a231e8c0a2303ad83e3efada4088e10c8419'
+  metadata.gz: b97c154cfe1b5ce9020029908ec017f316ef36ec36a4948d637d54990ad422580c99bdb2090c4fac4533a503a9678474753d664a101896164ee729d3abaacf37
+  data.tar.gz: 518dc7c466a5200b5945f1b21b8e8bcb4523649a3ef5678811385613834f910f5be9a193fd80dee1a8a029882b62da61c265fd3c942a874bd5cdb43c59d5ccef

data/lib/net/imap/config/attr_type_coercion.rb

@@ -18,6 +18,8 @@ module Net
             super(attr)
             AttrTypeCoercion.attr_accessor(attr, type: type)
           end
+
+          module_function def Integer?; NilOrInteger end
         end
         private_constant :Macros
 
@@ -26,34 +28,36 @@ module Net
         end
         private_class_method :included
 
-        def self.attr_accessor(attr, type: nil)
-          return unless type
-          if    :boolean == type then boolean attr
-          elsif Integer  == type then integer attr
-          elsif Array   === type then enum    attr, type
-          else raise ArgumentError, "unknown type coercion %p" % [type]
-          end
+        if defined?(Ractor.make_shareable)
+          def self.safe(...) Ractor.make_shareable nil.instance_eval(...).freeze end
+        else
+          def self.safe(...) nil.instance_eval(...).freeze end
         end
+        private_class_method :safe
 
-        def self.boolean(attr)
-          define_method :"#{attr}=" do |val| super !!val end
-          define_method :"#{attr}?" do send attr end
+        Types = Hash.new do |h, type|
+          type.nil? || Proc === type or raise TypeError, "type not nil or Proc"
+          safe{type}
         end
+        Types[:boolean] = Boolean = safe{-> {!!_1}}
+        Types[Integer]  = safe{->{Integer(_1)}}
 
-        def self.integer(attr)
-          define_method :"#{attr}=" do |val| super Integer val end
+        def self.attr_accessor(attr, type: nil)
+          type = Types[type] or return
+          define_method :"#{attr}=" do |val| super type[val] end
+          define_method :"#{attr}?" do send attr end if type == Boolean
         end
 
-        def self.enum(attr, enum)
-          enum = enum.dup.freeze
+        NilOrInteger = safe{->val { Integer val unless val.nil? }}
+
+        Enum = ->(*enum) {
+          enum     = safe{enum}
           expected = -"one of #{enum.map(&:inspect).join(", ")}"
-          define_method :"#{attr}=" do |val|
-            unless enum.include?(val)
-              raise ArgumentError, "expected %s, got %p" % [expected, val]
-            end
-            super val
-          end
-        end
+          safe{->val {
+            return val if enum.include?(val)
+            raise ArgumentError, "expected %s, got %p" % [expected, val]
+          }}
+        }
 
       end
     end

data/lib/net/imap/config.rb

@@ -129,8 +129,25 @@ module Net
       def self.global; @global if defined?(@global) end
 
       # A hash of hard-coded configurations, indexed by version number or name.
+      # Values can be accessed with any object that responds to +to_sym+ or
+      # +to_r+/+to_f+ with a non-zero number.
+      #
+      # Config::[] gets named or numbered versions from this hash.
+      #
+      # For example:
+      #     Net::IMAP::Config.version_defaults[0.5] == Net::IMAP::Config[0.5]
+      #     Net::IMAP::Config[0.5]       == Net::IMAP::Config[0.5r]     # => true
+      #     Net::IMAP::Config["current"] == Net::IMAP::Config[:current] # => true
+      #     Net::IMAP::Config["0.5.6"]   == Net::IMAP::Config[0.5r]     # => true
       def self.version_defaults; @version_defaults end
-      @version_defaults = {}
+      @version_defaults = Hash.new {|h, k|
+        # NOTE: String responds to both so the order is significant.
+        # And ignore non-numeric conversion to zero, because: "wat!?".to_r == 0
+        (h.fetch(k.to_r, nil) || h.fetch(k.to_f, nil) if k.is_a?(Numeric)) ||
+          (h.fetch(k.to_sym, nil) if k.respond_to?(:to_sym)) ||
+          (h.fetch(k.to_r,   nil) if k.respond_to?(:to_r) && k.to_r != 0r) ||
+          (h.fetch(k.to_f,   nil) if k.respond_to?(:to_f) && k.to_f != 0.0)
+      }
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -153,18 +170,17 @@ module Net
         elsif config.nil? && global.nil?   then nil
         elsif config.respond_to?(:to_hash) then new(global, **config).freeze
         else
-          version_defaults.fetch(config) do
+          version_defaults[config] or
             case config
             when Numeric
               raise RangeError, "unknown config version: %p" % [config]
-            when Symbol
+            when String, Symbol
               raise KeyError, "unknown config name: %p" % [config]
             else
               raise TypeError, "no implicit conversion of %s to %s" % [
                 config.class, Config
               ]
             end
-          end
         end
       end
 
@@ -191,10 +207,13 @@ module Net
 
       # Seconds to wait until a connection is opened.
       #
+      # Applied separately for establishing TCP connection and starting a TLS
+      # connection.
+      #
       # If the IMAP object cannot open a connection within this time,
       # it raises a Net::OpenTimeout exception.
       #
-      # See Net::IMAP.new.
+      # See Net::IMAP.new and Net::IMAP#starttls.
       #
       # The default value is +30+ seconds.
       attr_accessor :open_timeout, type: Integer
@@ -223,6 +242,40 @@ module Net
       #   Use +SASL-IR+ when it is supported by the server and the mechanism.
       attr_accessor :sasl_ir, type: :boolean
 
+      # The maximum allowed server response size.  When +nil+, there is no limit
+      # on response size.
+      #
+      # The default value (512 MiB, since +v0.5.7+) is <em>very high</em> and
+      # unlikely to be reached.  To use a lower limit, fetch message bodies in
+      # chunks rather than all at once.  A _much_ lower value should be used
+      # with untrusted servers (for example, when connecting to a user-provided
+      # hostname).
+      #
+      # <em>Please Note:</em> this only limits the size per response.  It does
+      # not prevent a flood of individual responses and it does not limit how
+      # many unhandled responses may be stored on the responses hash.  See
+      # Net::IMAP@Unbounded+memory+use.
+      #
+      # Socket reads are limited to the maximum remaining bytes for the current
+      # response: max_response_size minus the bytes that have already been read.
+      # When the limit is reached, or reading a +literal+ _would_ go over the
+      # limit, ResponseTooLargeError is raised and the connection is closed.
+      # See also #socket_read_limit.
+      #
+      # Note that changes will not take effect immediately, because the receiver
+      # thread may already be waiting for the next response using the previous
+      # value.  Net::IMAP#noop can force a response and enforce the new setting
+      # immediately.
+      #
+      # ==== Versioned Defaults
+      #
+      # Net::IMAP#max_response_size <em>was added in +v0.2.5+ and +v0.3.9+ as an
+      # attr_accessor, and in +v0.4.20+ and +v0.5.7+ as a delegator to this
+      # config attribute.</em>
+      #
+      # * original: +nil+ <em>(no limit)</em>
+      # * +0.5+: 512 MiB
+      attr_accessor :max_response_size, type: Integer?
 
       # Controls the behavior of Net::IMAP#responses when called without any
       # arguments (+type+ or +block+).
@@ -250,7 +303,7 @@ module Net
       #   Raise an ArgumentError with the deprecation warning.
       #
       # Note: #responses_without_args is an alias for #responses_without_block.
-      attr_accessor :responses_without_block, type: [
+      attr_accessor :responses_without_block, type: Enum[
         :silence_deprecation_warning, :warn, :frozen_dup, :raise,
       ]
 
@@ -295,7 +348,7 @@ module Net
       #
       # [+false+ <em>(planned default for +v0.6+)</em>]
       #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
-      attr_accessor :parser_use_deprecated_uidplus_data, type: [
+      attr_accessor :parser_use_deprecated_uidplus_data, type: Enum[
         true, :up_to_max_size, false
       ]
 
@@ -401,6 +454,7 @@ module Net
         open_timeout: 30,
         idle_response_timeout: 5,
         sasl_ir: true,
+        max_response_size: nil,
         responses_without_block: :silence_deprecation_warning,
         parser_use_deprecated_uidplus_data: true,
         parser_max_deprecated_uidplus_data_size: 1000,
@@ -408,36 +462,63 @@ module Net
 
       @global = default.new
 
-      version_defaults[0.4] = Config[default.send(:defaults_hash)]
+      version_defaults[:default] = Config[default.send(:defaults_hash)]
 
-      version_defaults[0] = Config[0.4].dup.update(
+      version_defaults[0r] = Config[:default].dup.update(
         sasl_ir: false,
+        max_response_size: nil,
         parser_use_deprecated_uidplus_data: true,
         parser_max_deprecated_uidplus_data_size: 10_000,
       ).freeze
-      version_defaults[0.0] = Config[0]
-      version_defaults[0.1] = Config[0]
-      version_defaults[0.2] = Config[0]
-      version_defaults[0.3] = Config[0]
+      version_defaults[0.0r] = Config[0r]
+      version_defaults[0.1r] = Config[0r]
+      version_defaults[0.2r] = Config[0r]
+      version_defaults[0.3r] = Config[0r]
 
-      version_defaults[0.5] = Config[0.4].dup.update(
+      version_defaults[0.4r] = Config[0.3r].dup.update(
+        sasl_ir: true,
+        parser_max_deprecated_uidplus_data_size: 1000,
+      ).freeze
+
+      version_defaults[0.5r] = Config[0.4r].dup.update(
+        max_response_size: 512 << 20, # 512 MiB
         responses_without_block: :warn,
         parser_use_deprecated_uidplus_data: :up_to_max_size,
         parser_max_deprecated_uidplus_data_size: 100,
       ).freeze
 
-      version_defaults[:default] = Config[0.4]
-      version_defaults[:current] = Config[0.4]
-      version_defaults[:next]    = Config[0.5]
-
-      version_defaults[0.6]      = Config[0.5].dup.update(
+      version_defaults[0.6r] = Config[0.5r].dup.update(
         responses_without_block: :frozen_dup,
         parser_use_deprecated_uidplus_data: false,
         parser_max_deprecated_uidplus_data_size: 0,
       ).freeze
-      version_defaults[:future]  = Config[0.6]
+
+      version_defaults[0.7r] = Config[0.6r].dup.update(
+      ).freeze
+
+      # Safe conversions one way only:
+      #   0.6r.to_f == 0.6  # => true
+      #   0.6 .to_r == 0.6r # => false
+      version_defaults.to_a.each do |k, v|
+        next unless k.is_a? Rational
+        version_defaults[k.to_f] = v
+      end
+
+      current = VERSION.to_r
+      version_defaults[:original] = Config[0]
+      version_defaults[:current]  = Config[current]
+      version_defaults[:next]     = Config[current + 0.1r]
+
+      version_defaults[:future]   = Config[0.7r]
 
       version_defaults.freeze
+
+      if ($VERBOSE || $DEBUG) && self[:current].to_h != self[:default].to_h
+        warn "Misconfigured Net::IMAP::Config[:current] => %p,\n" \
+             " not equal to Net::IMAP::Config[:default] => %p" % [
+                self[:current].to_h, self[:default].to_h
+              ]
+      end
     end
   end
 end

data/lib/net/imap/errors.rb

@@ -11,6 +11,39 @@ module Net
     class DataFormatError < Error
     end
 
+    # Error raised when the socket cannot be read, due to a Config limit.
+    class ResponseReadError < Error
+    end
+
+    # Error raised when a response is larger than IMAP#max_response_size.
+    class ResponseTooLargeError < ResponseReadError
+      attr_reader :bytes_read, :literal_size
+      attr_reader :max_response_size
+
+      def initialize(msg = nil, *args,
+                     bytes_read:        nil,
+                     literal_size:      nil,
+                     max_response_size: nil,
+                     **kwargs)
+        @bytes_read        = bytes_read
+        @literal_size      = literal_size
+        @max_response_size = max_response_size
+        msg ||= [
+          "Response size", response_size_msg, "exceeds max_response_size",
+          max_response_size && "(#{max_response_size}B)",
+        ].compact.join(" ")
+        super(msg, *args, **kwargs)
+      end
+
+      private
+
+      def response_size_msg
+        if bytes_read && literal_size
+          "(#{bytes_read}B read + #{literal_size}B literal)"
+        end
+      end
+    end
+
     # Error raised when a response from the server is non-parsable.
     class ResponseParseError < Error
     end

data/lib/net/imap/response_reader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    # See https://www.rfc-editor.org/rfc/rfc9051#section-2.2.2
+    class ResponseReader # :nodoc:
+      attr_reader :client
+
+      def initialize(client, sock)
+        @client, @sock = client, sock
+      end
+
+      def read_response_buffer
+        @buff = String.new
+        catch :eof do
+          while true
+            read_line
+            break unless (@literal_size = get_literal_size)
+            read_literal
+          end
+        end
+        buff
+      ensure
+        @buff = nil
+      end
+
+      private
+
+      attr_reader :buff, :literal_size
+
+      def bytes_read;       buff.bytesize                         end
+      def empty?;           buff.empty?                           end
+      def done?;            line_done? && !get_literal_size       end
+      def line_done?;       buff.end_with?(CRLF)                  end
+      def get_literal_size; /\{(\d+)\}\r\n\z/n =~ buff && $1.to_i end
+
+      def read_line
+        buff << (@sock.gets(CRLF, read_limit) or throw :eof)
+        max_response_remaining! unless line_done?
+      end
+
+      def read_literal
+        # check before allocating memory for literal
+        max_response_remaining!
+        literal = String.new(capacity: literal_size)
+        buff << (@sock.read(read_limit(literal_size), literal) or throw :eof)
+      ensure
+        @literal_size = nil
+      end
+
+      def read_limit(limit = nil)
+        [limit, max_response_remaining!].compact.min
+      end
+
+      def max_response_size;      client.max_response_size                end
+      def max_response_remaining; max_response_size &.- bytes_read        end
+      def response_too_large?;    max_response_size &.< min_response_size end
+      def min_response_size;      bytes_read + min_response_remaining     end
+
+      def min_response_remaining
+        empty? ? 3 : done? ? 0 : (literal_size || 0) + 2
+      end
+
+      def max_response_remaining!
+        return max_response_remaining unless response_too_large?
+        raise ResponseTooLargeError.new(
+          max_response_size: max_response_size,
+          bytes_read:        bytes_read,
+          literal_size:      literal_size,
+        )
+      end
+
+    end
+  end
+end

data/lib/net/imap/sequence_set.rb

@@ -178,7 +178,7 @@ module Net
     #
     # <i>Set membership:</i>
     # - #include? (aliased as #member?):
-    #   Returns whether a given object (nz-number, range, or <tt>*</tt>) is
+    #   Returns whether a given element (nz-number, range, or <tt>*</tt>) is
     #   contained by the set.
     # - #include_star?: Returns whether the set contains <tt>*</tt>.
     #
@@ -243,13 +243,13 @@ module Net
     # These methods do not modify +self+.
     #
     # - #| (aliased as #union and #+): Returns a new set combining all members
-    #   from +self+ with all members from the other object.
+    #   from +self+ with all members from the other set.
     # - #& (aliased as #intersection): Returns a new set containing all members
-    #   common to +self+ and the other object.
+    #   common to +self+ and the other set.
     # - #- (aliased as #difference): Returns a copy of +self+ with all members
-    #   in the other object removed.
+    #   in the other set removed.
     # - #^ (aliased as #xor): Returns a new set containing all members from
-    #   +self+ and the other object except those common to both.
+    #   +self+ and the other set except those common to both.
     # - #~ (aliased as #complement): Returns a new set containing all members
     #   that are not in +self+
     # - #limit: Returns a copy of +self+ which has replaced <tt>*</tt> with a
@@ -262,17 +262,17 @@ module Net
     #
     # These methods always update #string to be fully sorted and coalesced.
     #
-    # - #add (aliased as #<<): Adds a given object to the set; returns +self+.
-    # - #add?: If the given object is not an element in the set, adds it and
+    # - #add (aliased as #<<): Adds a given element to the set; returns +self+.
+    # - #add?: If the given element is not fully included the set, adds it and
     #   returns +self+; otherwise, returns +nil+.
-    # - #merge: Merges multiple elements into the set; returns +self+.
+    # - #merge: Adds all members of the given sets into this set; returns +self+.
     # - #complement!: Replaces the contents of the set with its own #complement.
     #
     # <i>Order preserving:</i>
     #
     # These methods _may_ cause #string to not be sorted or coalesced.
     #
-    # - #append: Adds a given object to the set, appending it to the existing
+    # - #append: Adds the given entry to the set, appending it to the existing
     #   string, and returns +self+.
     # - #string=: Assigns a new #string value and replaces #elements to match.
     # - #replace: Replaces the contents of the set with the contents
@@ -283,13 +283,14 @@ module Net
     # sorted and coalesced.
     #
     # - #clear: Removes all elements in the set; returns +self+.
-    # - #delete: Removes a given object from the set; returns +self+.
-    # - #delete?: If the given object is an element in the set, removes it and
+    # - #delete: Removes a given element from the set; returns +self+.
+    # - #delete?: If the given element is included in the set, removes it and
     #   returns it; otherwise, returns +nil+.
     # - #delete_at: Removes the number at a given offset.
     # - #slice!: Removes the number or consecutive numbers at a given offset or
     #   range of offsets.
-    # - #subtract: Removes each given object from the set; returns +self+.
+    # - #subtract: Removes all members of the given sets from this set; returns
+    #   +self+.
     # - #limit!: Replaces <tt>*</tt> with a given maximum value and removes all
     #   members over that maximum; returns +self+.
     #
@@ -326,9 +327,12 @@ module Net
       class << self
 
         # :call-seq:
-        #   SequenceSet[*values] -> valid frozen sequence set
+        #   SequenceSet[*inputs] -> valid frozen sequence set
         #
-        # Returns a frozen SequenceSet, constructed from +values+.
+        # Returns a frozen SequenceSet, constructed from +inputs+.
+        #
+        # When only a single valid frozen SequenceSet is given, that same set is
+        # returned.
         #
         # An empty SequenceSet is invalid and will raise a DataFormatError.
         #
@@ -694,7 +698,7 @@ module Net
       alias complement :~
 
       # :call-seq:
-      #   add(object)   -> self
+      #   add(element)   -> self
       #   self << other -> self
       #
       # Adds a range or number to the set and returns +self+.
@@ -702,8 +706,8 @@ module Net
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
       # Related: #add?, #merge, #union
-      def add(object)
-        tuple_add input_to_tuple object
+      def add(element)
+        tuple_add input_to_tuple element
         normalize!
       end
       alias << add
@@ -712,9 +716,9 @@ module Net
       #
       # Unlike #add, #merge, or #union, the new value is appended to #string.
       # This may result in a #string which has duplicates or is out-of-order.
-      def append(object)
+      def append(entry)
         modifying!
-        tuple = input_to_tuple object
+        tuple = input_to_tuple entry
         entry = tuple_to_str tuple
         string unless empty? # write @string before tuple_add
         tuple_add tuple
@@ -722,19 +726,19 @@ module Net
         self
       end
 
-      # :call-seq: add?(object) -> self or nil
+      # :call-seq: add?(element) -> self or nil
       #
       # Adds a range or number to the set and returns +self+.  Returns +nil+
-      # when the object is already included in the set.
+      # when the element is already included in the set.
       #
       # #string will be regenerated.  Use #merge to add many elements at once.
       #
       # Related: #add, #merge, #union, #include?
-      def add?(object)
-        add object unless include? object
+      def add?(element)
+        add element unless include? element
       end
 
-      # :call-seq: delete(object) -> self
+      # :call-seq: delete(element) -> self
       #
       # Deletes the given range or number from the set and returns +self+.
       #
@@ -742,8 +746,8 @@ module Net
       # many elements at once.
       #
       # Related: #delete?, #delete_at, #subtract, #difference
-      def delete(object)
-        tuple_subtract input_to_tuple object
+      def delete(element)
+        tuple_subtract input_to_tuple element
         normalize!
       end
 
@@ -779,8 +783,8 @@ module Net
       # #string will be regenerated after deletion.
       #
       # Related: #delete, #delete_at, #subtract, #difference, #disjoint?
-      def delete?(object)
-        tuple = input_to_tuple object
+      def delete?(element)
+        tuple = input_to_tuple element
         if tuple.first == tuple.last
           return unless include_tuple? tuple
           tuple_subtract tuple
@@ -824,33 +828,31 @@ module Net
         deleted
       end
 
-      # Merges all of the elements that appear in any of the +inputs+ into the
+      # Merges all of the elements that appear in any of the +sets+ into the
       # set, and returns +self+.
       #
-      # The +inputs+ may be any objects that would be accepted by ::new:
-      # non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
-      # formatted strings, other sequence sets, or enumerables containing any of
-      # these.
+      # The +sets+ may be any objects that would be accepted by ::new: non-zero
+      # 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
+      # strings, other sequence sets, or enumerables containing any of these.
       #
-      # #string will be regenerated after all inputs have been merged.
+      # #string will be regenerated after all sets have been merged.
       #
       # Related: #add, #add?, #union
-      def merge(*inputs)
-        tuples_add input_to_tuples inputs
+      def merge(*sets)
+        tuples_add input_to_tuples sets
         normalize!
       end
 
-      # Removes all of the elements that appear in any of the given +objects+
-      # from the set, and returns +self+.
+      # Removes all of the elements that appear in any of the given +sets+ from
+      # the set, and returns +self+.
       #
-      # The +objects+ may be any objects that would be accepted by ::new:
-      # non-zero 32 bit unsigned integers, ranges, <tt>sequence-set</tt>
-      # formatted strings, other sequence sets, or enumerables containing any of
-      # these.
+      # The +sets+ may be any objects that would be accepted by ::new: non-zero
+      # 32 bit unsigned integers, ranges, <tt>sequence-set</tt> formatted
+      # strings, other sequence sets, or enumerables containing any of these.
       #
       # Related: #difference
-      def subtract(*objects)
-        tuples_subtract input_to_tuples objects
+      def subtract(*sets)
+        tuples_subtract input_to_tuples sets
         normalize!
       end
 
@@ -1390,29 +1392,29 @@ module Net
         super
       end
 
-      def input_to_tuple(obj)
-        obj = input_try_convert obj
-        case obj
-        when *STARS, Integer then [int = to_tuple_int(obj), int]
-        when Range           then range_to_tuple(obj)
-        when String          then str_to_tuple(obj)
+      def input_to_tuple(entry)
+        entry = input_try_convert entry
+        case entry
+        when *STARS, Integer then [int = to_tuple_int(entry), int]
+        when Range           then range_to_tuple(entry)
+        when String          then str_to_tuple(entry)
         else
-          raise DataFormatError, "expected number or range, got %p" % [obj]
+          raise DataFormatError, "expected number or range, got %p" % [entry]
         end
       end
 
-      def input_to_tuples(obj)
-        obj = input_try_convert obj
-        case obj
-        when *STARS, Integer, Range then [input_to_tuple(obj)]
-        when String      then str_to_tuples obj
-        when SequenceSet then obj.tuples
-        when ENUMABLE    then obj.flat_map { input_to_tuples _1 }
+      def input_to_tuples(set)
+        set = input_try_convert set
+        case set
+        when *STARS, Integer, Range then [input_to_tuple(set)]
+        when String      then str_to_tuples set
+        when SequenceSet then set.tuples
+        when ENUMABLE    then set.flat_map { input_to_tuples _1 }
         when nil         then []
         else
           raise DataFormatError,
                 "expected nz-number, range, string, or enumerable; " \
-                "got %p" % [obj]
+                "got %p" % [set]
         end
       end
 

data/lib/net/imap.rb

@@ -43,10 +43,16 @@ module Net
   # To work on the messages within a mailbox, the client must
   # first select that mailbox, using either #select or #examine
   # (for read-only access).  Once the client has successfully
-  # selected a mailbox, they enter the "_selected_" state, and that
+  # selected a mailbox, they enter the +selected+ state, and that
   # mailbox becomes the _current_ mailbox, on which mail-item
   # related commands implicitly operate.
   #
+  # === Connection state
+  #
+  # Once an IMAP connection is established, the connection is in one of four
+  # states: <tt>not authenticated</tt>, +authenticated+, +selected+, and
+  # +logout+.  Most commands are valid only in certain states.
+  #
   # === Sequence numbers and UIDs
   #
   # Messages have two sorts of identifiers: message sequence
@@ -199,6 +205,42 @@ module Net
   #
   # This script invokes the FETCH command and the SEARCH command concurrently.
   #
+  # When running multiple commands, care must be taken to avoid ambiguity.  For
+  # example, SEARCH responses are ambiguous about which command they are
+  # responding to, so search commands should not run simultaneously, unless the
+  # server supports +ESEARCH+ {[RFC4731]}[https://rfc-editor.org/rfc/rfc4731] or
+  # IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051].  See {RFC9051
+  # §5.5}[https://www.rfc-editor.org/rfc/rfc9051.html#section-5.5] for
+  # other examples of command sequences which should not be pipelined.
+  #
+  # == Unbounded memory use
+  #
+  # Net::IMAP reads server responses in a separate receiver thread per client.
+  # Unhandled response data is saved to #responses, and response_handlers run
+  # inside the receiver thread.  See the list of methods for {handling server
+  # responses}[rdoc-ref:Net::IMAP@Handling+server+responses], below.
+  #
+  # Because the receiver thread continuously reads and saves new responses, some
+  # scenarios must be careful to avoid unbounded memory use:
+  #
+  # * Commands such as #list or #fetch can have an enormous number of responses.
+  # * Commands such as #fetch can result in an enormous size per response.
+  # * Long-lived connections will gradually accumulate unsolicited server
+  #   responses, especially +EXISTS+, +FETCH+, and +EXPUNGE+ responses.
+  # * A buggy or untrusted server could send inappropriate responses, which
+  #   could be very numerous, very large, and very rapid.
+  #
+  # Use paginated or limited versions of commands whenever possible.
+  #
+  # Use Config#max_response_size to impose a limit on incoming server responses
+  # as they are being read.  <em>This is especially important for untrusted
+  # servers.</em>
+  #
+  # Use #add_response_handler to handle responses after each one is received.
+  # Use the +response_handlers+ argument to ::new to assign response handlers
+  # before the receiver thread is started.  Use #extract_responses,
+  # #clear_responses, or #responses (with a block) to prune responses.
+  #
   # == Errors
   #
   # An \IMAP server can send three different types of responses to indicate
@@ -260,8 +302,9 @@ module Net
   #
   # - Net::IMAP.new: Creates a new \IMAP client which connects immediately and
   #   waits for a successful server greeting before the method returns.
+  # - #connection_state: Returns the connection state.
   # - #starttls: Asks the server to upgrade a clear-text connection to use TLS.
-  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  # - #logout: Tells the server to end the session.  Enters the +logout+ state.
   # - #disconnect: Disconnects the connection (without sending #logout first).
   # - #disconnected?: True if the connection has been closed.
   #
@@ -317,37 +360,36 @@ module Net
   #   <em>In general, #capable? should be used rather than explicitly sending a
   #   +CAPABILITY+ command to the server.</em>
   # - #noop: Allows the server to send unsolicited untagged #responses.
-  # - #logout: Tells the server to end the session. Enters the "_logout_" state.
+  # - #logout: Tells the server to end the session. Enters the +logout+ state.
   #
   # ==== Not Authenticated state
   #
   # In addition to the commands for any state, the following commands are valid
-  # in the "<em>not authenticated</em>" state:
+  # in the +not_authenticated+ state:
   #
   # - #starttls: Upgrades a clear-text connection to use TLS.
   #
   #   <em>Requires the +STARTTLS+ capability.</em>
   # - #authenticate: Identifies the client to the server using the given
   #   {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  #   and credentials.  Enters the "_authenticated_" state.
+  #   and credentials.  Enters the +authenticated+ state.
   #
   #   <em>The server should list <tt>"AUTH=#{mechanism}"</tt> capabilities for
   #   supported mechanisms.</em>
   # - #login: Identifies the client to the server using a plain text password.
-  #   Using #authenticate is generally preferred.  Enters the "_authenticated_"
-  #   state.
+  #   Using #authenticate is preferred.  Enters the +authenticated+ state.
   #
   #   <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
   #
   # ==== Authenticated state
   #
   # In addition to the commands for any state, the following commands are valid
-  # in the "_authenticated_" state:
+  # in the +authenticated+ state:
   #
   # - #enable: Enables backwards incompatible server extensions.
   #   <em>Requires the +ENABLE+ or +IMAP4rev2+ capability.</em>
-  # - #select:  Open a mailbox and enter the "_selected_" state.
-  # - #examine: Open a mailbox read-only, and enter the "_selected_" state.
+  # - #select:  Open a mailbox and enter the +selected+ state.
+  # - #examine: Open a mailbox read-only, and enter the +selected+ state.
   # - #create: Creates a new mailbox.
   # - #delete: Permanently remove a mailbox.
   # - #rename: Change the name of a mailbox.
@@ -369,12 +411,12 @@ module Net
   #
   # ==== Selected state
   #
-  # In addition to the commands for any state and the "_authenticated_"
-  # commands, the following commands are valid in the "_selected_" state:
+  # In addition to the commands for any state and the +authenticated+
+  # commands, the following commands are valid in the +selected+ state:
   #
-  # - #close: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #close: Closes the mailbox and returns to the +authenticated+ state,
   #   expunging deleted messages, unless the mailbox was opened as read-only.
-  # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #unselect: Closes the mailbox and returns to the +authenticated+ state,
   #   without expunging any messages.
   #   <em>Requires the +UNSELECT+ or +IMAP4rev2+ capability.</em>
   # - #expunge: Permanently removes messages which have the Deleted flag set.
@@ -395,7 +437,7 @@ module Net
   #
   # ==== Logout state
   #
-  # No \IMAP commands are valid in the "_logout_" state.  If the socket is still
+  # No \IMAP commands are valid in the +logout+ state.  If the socket is still
   # open, Net::IMAP will close it after receiving server confirmation.
   # Exceptions will be raised by \IMAP commands that have already started and
   # are waiting for a response, as well as any that are called after logout.
@@ -449,7 +491,7 @@ module Net
   # ==== RFC3691: +UNSELECT+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
   # above with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
-  # - #unselect: Closes the mailbox and returns to the "_authenticated_" state,
+  # - #unselect: Closes the mailbox and returns to the +authenticated+ state,
   #   without expunging any messages.
   #
   # ==== RFC4314: +ACL+
@@ -719,7 +761,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.19"
+    VERSION = "0.4.20"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -727,6 +769,7 @@ module Net
       "UTF8=ONLY" => "UTF8=ACCEPT",
     }.freeze
 
+    autoload :ResponseReader, File.expand_path("imap/response_reader", __dir__)
     autoload :SASL,        File.expand_path("imap/sasl",         __dir__)
     autoload :SASLAdapter, File.expand_path("imap/sasl_adapter", __dir__)
     autoload :StringPrep,  File.expand_path("imap/stringprep",   __dir__)
@@ -741,9 +784,11 @@ module Net
     def self.config; Config.global end
 
     # Returns the global debug mode.
+    # Delegates to {Net::IMAP.config.debug}[rdoc-ref:Config#debug].
     def self.debug; config.debug end
 
     # Sets the global debug mode.
+    # Delegates to {Net::IMAP.config.debug=}[rdoc-ref:Config#debug=].
     def self.debug=(val)
       config.debug = val
     end
@@ -764,7 +809,7 @@ module Net
       alias default_ssl_port default_tls_port
     end
 
-    # Returns the initial greeting the server, an UntaggedResponse.
+    # Returns the initial greeting sent by the server, an UntaggedResponse.
     attr_reader :greeting
 
     # The client configuration.  See Net::IMAP::Config.
@@ -773,13 +818,28 @@ module Net
     # Net::IMAP.config.
     attr_reader :config
 
-    # Seconds to wait until a connection is opened.
-    # If the IMAP object cannot open a connection within this time,
-    # it raises a Net::OpenTimeout exception. The default value is 30 seconds.
-    def open_timeout; config.open_timeout end
+    ##
+    # :attr_reader: open_timeout
+    # Seconds to wait until a connection is opened.  Also used by #starttls.
+    # Delegates to {config.open_timeout}[rdoc-ref:Config#open_timeout].
 
+    ##
+    # :attr_reader: idle_response_timeout
     # Seconds to wait until an IDLE response is received.
-    def idle_response_timeout; config.idle_response_timeout end
+    # Delegates to {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout].
+
+    ##
+    # :attr_accessor: max_response_size
+    #
+    # The maximum allowed server response size, in bytes.
+    # Delegates to {config.max_response_size}[rdoc-ref:Config#max_response_size].
+
+    # :stopdoc:
+    def open_timeout;           config.open_timeout            end
+    def idle_response_timeout;  config.idle_response_timeout   end
+    def max_response_size;      config.max_response_size       end
+    def max_response_size=(val) config.max_response_size = val end
+    # :startdoc:
 
     # The hostname this client connected to
     attr_reader :host
@@ -835,6 +895,12 @@ module Net
     #
     #   See DeprecatedClientOptions.new for deprecated SSL arguments.
     #
+    # [response_handlers]
+    #   A list of response handlers to be added before the receiver thread is
+    #   started.  This ensures every server response is handled, including the
+    #   #greeting.  Note that the greeting is handled in the current thread, but
+    #   all other responses are handled in the receiver thread.
+    #
     # [config]
     #   A Net::IMAP::Config object to use as the basis for #config.  By default,
     #   the global Net::IMAP.config is used.
@@ -906,7 +972,7 @@ module Net
     # [Net::IMAP::ByeResponseError]
     #   Connected to the host successfully, but it immediately said goodbye.
     #
-    def initialize(host, port: nil, ssl:  nil,
+    def initialize(host, port: nil, ssl: nil, response_handlers: nil,
                    config: Config.global, **config_options)
       super()
       # Config options
@@ -929,6 +995,7 @@ module Net
       @receiver_thread = nil
       @receiver_thread_exception = nil
       @receiver_thread_terminating = false
+      response_handlers&.each do add_response_handler(_1) end
 
       # Client Protocol Sender (including state for currently running commands)
       @tag_prefix = "RUBY"
@@ -944,6 +1011,7 @@ module Net
       # Connection
       @tls_verified = false
       @sock = tcp_socket(@host, @port)
+      @reader = ResponseReader.new(self, @sock)
       start_tls_session if ssl_ctx
       start_imap_connection
 
@@ -1204,6 +1272,10 @@ module Net
     # both successful.  Any error indicates that the connection has not been
     # secured.
     #
+    # After the server agrees to start a TLS connection, this method waits up to
+    # {config.open_timeout}[rdoc-ref:Config#open_timeout] before raising
+    # +Net::OpenTimeout+.
+    #
     # *Note:*
     # >>>
     #   Any #response_handlers added before STARTTLS should be aware that the
@@ -2706,6 +2778,10 @@ module Net
     #     end
     #   }
     #
+    # Response handlers can also be added when the client is created before the
+    # receiver thread is started, by the +response_handlers+ argument to ::new.
+    # This ensures every server response is handled, including the #greeting.
+    #
     # Related: #remove_response_handler, #response_handlers
     def add_response_handler(handler = nil, &block)
       raise ArgumentError, "two Procs are passed" if handler && block
@@ -2732,6 +2808,7 @@ module Net
     def start_imap_connection
       @greeting        = get_server_greeting
       @capabilities    = capabilities_from_resp_code @greeting
+      @response_handlers.each do |handler| handler.call(@greeting) end
       @receiver_thread = start_receiver_thread
     rescue Exception
       @sock.close
@@ -2860,23 +2937,10 @@ module Net
     end
 
     def get_response
-      buff = String.new
-      while true
-        s = @sock.gets(CRLF)
-        break unless s
-        buff.concat(s)
-        if /\{(\d+)\}\r\n/n =~ s
-          s = @sock.read($1.to_i)
-          buff.concat(s)
-        else
-          break
-        end
-      end
+      buff = @reader.read_response_buffer
       return nil if buff.length == 0
-      if config.debug?
-        $stderr.print(buff.gsub(/^/n, "S: "))
-      end
-      return @parser.parse(buff)
+      $stderr.print(buff.gsub(/^/n, "S: ")) if config.debug?
+      @parser.parse(buff)
     end
 
     #############################
@@ -3077,6 +3141,7 @@ module Net
       raise "already using SSL" if @sock.kind_of?(OpenSSL::SSL::SSLSocket)
       raise "cannot start TLS without SSLContext" unless ssl_ctx
       @sock = SSLSocket.new(@sock, ssl_ctx)
+      @reader = ResponseReader.new(self, @sock)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
       ssl_socket_connect(@sock, open_timeout)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.19
+  version: 0.4.20
 platform: ruby
 authors:
 - Shugo Maeda
 - nicholas a. evans
 bindir: exe
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -68,6 +68,7 @@ files:
 - lib/net/imap/response_data.rb
 - lib/net/imap/response_parser.rb
 - lib/net/imap/response_parser/parser_utils.rb
+- lib/net/imap/response_reader.rb
 - lib/net/imap/sasl.rb
 - lib/net/imap/sasl/anonymous_authenticator.rb
 - lib/net/imap/sasl/authentication_exchange.rb
@@ -124,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []