net-imap 0.5.5 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9b92943c4c4d17210f7374b4f5577f95471038a987540a8cdad2088e6bec25d
-  data.tar.gz: 6a28ce5ca7778cbfa3de48c3451be4d17fe6298a01e2a946725caf022a34dd8c
+  metadata.gz: cdbdda0ed73da899ec338f66022a16104562d3701c568b0a6d4897270a608ac5
+  data.tar.gz: b6a7ec70776b32f8eb57d01a0869503eb5d76f719ac091eb92e0206608e936e9
 SHA512:
-  metadata.gz: 5a575e282b7cd6828d56360003b1de29e8ca0e3d55ce733c8de250f781413dc8e9e6a90549c14b9ed21bb46e0cdc88f3e75d92aeaed769d594f93056359ee40d
-  data.tar.gz: 87d57464c32eab235e241c74efea7953b9798b9c40a14f66170e751560943f728aabe852d38c746283cdcb4c03914ee375021c49fec67f653113d3330a6732d2
+  metadata.gz: 381bf2428719ed8decb5d241fda0e19f28031dd4a77980b3717bb29c37bed1c927f00e5b57862e209ecf24b2e9b38c01088d6e1a90fc4b4cc026cdd9e6611100
+  data.tar.gz: 513c6a77d46b6d2cf67aea4511023acc76c69940e3b1a0d0eae7223b53ff63bc8e6e009f51fef826b09f76f6ad1d92e84243e8457f59d3912db7e74bf69d3d1b

data/Gemfile

@@ -8,6 +8,7 @@ gem "digest"
 gem "strscan"
 gem "base64"
 
+gem "irb"
 gem "rake"
 gem "rdoc"
 gem "test-unit"

data/lib/net/imap/config.rb

@@ -287,6 +287,67 @@ module Net
       #
       # Alias for responses_without_block
 
+      # Whether ResponseParser should use the deprecated UIDPlusData or
+      # CopyUIDData for +COPYUID+ response codes, and UIDPlusData or
+      # AppendUIDData for +APPENDUID+ response codes.
+      #
+      # UIDPlusData stores its data in arrays of numbers, which is vulnerable to
+      # a memory exhaustion denial of service attack from an untrusted or
+      # compromised server.  Set this option to +false+ to completely block this
+      # vulnerability.  Otherwise, parser_max_deprecated_uidplus_data_size
+      # mitigates this vulnerability.
+      #
+      # AppendUIDData and CopyUIDData are _mostly_ backward-compatible with
+      # UIDPlusData.  Most applications should be able to upgrade with little
+      # or no changes.
+      #
+      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      #
+      # <em>(Config option added in +v0.4.19+ and +v0.5.6+.)</em>
+      #
+      # <em>UIDPlusData will be removed in +v0.6+ and this config setting will
+      # be ignored.</em>
+      #
+      # ==== Valid options
+      #
+      # [+true+ <em>(original default)</em>]
+      #    ResponseParser only uses UIDPlusData.
+      #
+      # [+:up_to_max_size+ <em>(default since +v0.5.6+)</em>]
+      #    ResponseParser uses UIDPlusData when the +uid-set+ size is below
+      #    parser_max_deprecated_uidplus_data_size.  Above that size,
+      #    ResponseParser uses AppendUIDData or CopyUIDData.
+      #
+      # [+false+ <em>(planned default for +v0.6+)</em>]
+      #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
+      attr_accessor :parser_use_deprecated_uidplus_data, type: [
+        true, :up_to_max_size, false
+      ]
+
+      # The maximum +uid-set+ size that ResponseParser will parse into
+      # deprecated UIDPlusData.  This limit only applies when
+      # parser_use_deprecated_uidplus_data is not +false+.
+      #
+      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      #
+      # <em>Support for limiting UIDPlusData to a maximum size was added in
+      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.</em>
+      #
+      # <em>UIDPlusData will be removed in +v0.6+.</em>
+      #
+      # ==== Versioned Defaults
+      #
+      # Because this limit guards against a remote server causing catastrophic
+      # memory exhaustion, the versioned default (used by #load_defaults) also
+      # applies to versions without the feature.
+      #
+      # * +0.3+ and prior: <tt>10,000</tt>
+      # * +0.4+: <tt>1,000</tt>
+      # * +0.5+: <tt>100</tt>
+      # * +0.6+: <tt>0</tt>
+      #
+      attr_accessor :parser_max_deprecated_uidplus_data_size, type: Integer
+
       # Creates a new config object and initialize its attribute with +attrs+.
       #
       # If +parent+ is not given, the global config is used by default.
@@ -367,6 +428,8 @@ module Net
         sasl_ir: true,
         enforce_logindisabled: true,
         responses_without_block: :warn,
+        parser_use_deprecated_uidplus_data: :up_to_max_size,
+        parser_max_deprecated_uidplus_data_size: 100,
       ).freeze
 
       @global = default.new
@@ -378,6 +441,8 @@ module Net
         sasl_ir: false,
         responses_without_block: :silence_deprecation_warning,
         enforce_logindisabled: false,
+        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]
@@ -386,12 +451,15 @@ module Net
 
       version_defaults[0.4] = Config[0.3].dup.update(
         sasl_ir: true,
+        parser_max_deprecated_uidplus_data_size: 1000,
       ).freeze
 
       version_defaults[0.5] = Config[:current]
 
       version_defaults[0.6] = Config[0.5].dup.update(
         responses_without_block: :frozen_dup,
+        parser_use_deprecated_uidplus_data: false,
+        parser_max_deprecated_uidplus_data_size: 0,
       ).freeze
       version_defaults[:next] = Config[0.6]
       version_defaults[:future] = Config[:next]

data/lib/net/imap/response_data.rb

@@ -7,6 +7,9 @@ module Net
     autoload :UIDFetchData,     "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
     autoload :SequenceSet,      "#{__dir__}/sequence_set"
+    autoload :UIDPlusData,      "#{__dir__}/uidplus_data"
+    autoload :AppendUIDData,    "#{__dir__}/uidplus_data"
+    autoload :CopyUIDData,      "#{__dir__}/uidplus_data"
     autoload :VanishedData,     "#{__dir__}/vanished_data"
 
     # Net::IMAP::ContinuationRequest represents command continuation requests.
@@ -344,55 +347,6 @@ module Net
       # code data can take.
     end
 
-    # UIDPlusData represents the ResponseCode#data that accompanies the
-    # +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode].
-    #
-    # A server that supports +UIDPLUS+ should send a UIDPlusData object inside
-    # every TaggedResponse returned by the append[rdoc-ref:Net::IMAP#append],
-    # copy[rdoc-ref:Net::IMAP#copy], move[rdoc-ref:Net::IMAP#move], {uid
-    # copy}[rdoc-ref:Net::IMAP#uid_copy], and {uid
-    # move}[rdoc-ref:Net::IMAP#uid_move] commands---unless the destination
-    # mailbox reports +UIDNOTSTICKY+.
-    #
-    # == Required capability
-    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
-    # or +IMAP4rev2+ capability.
-    #
-    class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids)
-      ##
-      # method: uidvalidity
-      # :call-seq: uidvalidity -> nonzero uint32
-      #
-      # The UIDVALIDITY of the destination mailbox.
-
-      ##
-      # method: source_uids
-      # :call-seq: source_uids -> nil or an array of nonzero uint32
-      #
-      # The UIDs of the copied or moved messages.
-      #
-      # Note:: Returns +nil+ for Net::IMAP#append.
-
-      ##
-      # method: assigned_uids
-      # :call-seq: assigned_uids -> an array of nonzero uint32
-      #
-      # The newly assigned UIDs of the copied, moved, or appended messages.
-      #
-      # Note:: This always returns an array, even when it contains only one UID.
-
-      ##
-      # :call-seq: uid_mapping -> nil or a hash
-      #
-      # Returns a hash mapping each source UID to the newly assigned destination
-      # UID.
-      #
-      # Note:: Returns +nil+ for Net::IMAP#append.
-      def uid_mapping
-        source_uids&.zip(assigned_uids)&.to_h
-      end
-    end
-
     # MailboxList represents the data of an untagged +LIST+ response, for a
     # _single_ mailbox path.  IMAP#list returns an array of MailboxList objects.
     #

data/lib/net/imap/response_parser.rb

@@ -13,13 +13,17 @@ module Net
 
       attr_reader :config
 
-      # :call-seq: Net::IMAP::ResponseParser.new -> Net::IMAP::ResponseParser
+      # Creates a new ResponseParser.
+      #
+      # When +config+ is frozen or global, the parser #config inherits from it.
+      # Otherwise, +config+ will be used directly.
       def initialize(config: Config.global)
         @str = nil
         @pos = nil
         @lex_state = nil
         @token = nil
         @config = Config[config]
+        @config = @config.new if @config == Config.global || @config.frozen?
       end
 
       # :call-seq:
@@ -1997,11 +2001,10 @@ module Net
       #
       # n.b, uniqueid ⊂ uid-set.  To avoid inconsistent return types, we always
       # match uid_set even if that returns a single-member array.
-      #
       def resp_code_apnd__data
         validity = number; SP!
         dst_uids = uid_set # uniqueid ⊂ uid-set
-        UIDPlusData.new(validity, nil, dst_uids)
+        AppendUID(validity, dst_uids)
       end
 
       # already matched:  "COPYUID"
@@ -2011,7 +2014,25 @@ module Net
         validity = number;  SP!
         src_uids = uid_set; SP!
         dst_uids = uid_set
-        UIDPlusData.new(validity, src_uids, dst_uids)
+        CopyUID(validity, src_uids, dst_uids)
+      end
+
+      def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
+      def CopyUID(...)   DeprecatedUIDPlus(...) || CopyUIDData.new(...)   end
+
+      # TODO: remove this code in the v0.6.0 release
+      def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
+        return unless config.parser_use_deprecated_uidplus_data
+        compact_uid_sets = [src_uids, dst_uids].compact
+        count = compact_uid_sets.map { _1.count_with_duplicates }.max
+        max   = config.parser_max_deprecated_uidplus_data_size
+        if count <= max
+          src_uids &&= src_uids.each_ordered_number.to_a
+          dst_uids   = dst_uids.each_ordered_number.to_a
+          UIDPlusData.new(validity, src_uids, dst_uids)
+        elsif config.parser_use_deprecated_uidplus_data != :up_to_max_size
+          parse_error("uid-set is too large: %d > %d", count, max)
+        end
       end
 
       ADDRESS_REGEXP = /\G
@@ -2137,15 +2158,9 @@ module Net
       #      uniqueid        = nz-number
       #                          ; Strictly ascending
       def uid_set
-        token = match(T_NUMBER, T_ATOM)
-        case token.symbol
-        when T_NUMBER then [Integer(token.value)]
-        when T_ATOM
-          token.value.split(",").flat_map {|range|
-            range = range.split(":").map {|uniqueid| Integer(uniqueid) }
-            range.size == 1 ? range : Range.new(range.min, range.max).to_a
-          }
-        end
+        set = sequence_set
+        parse_error("uid-set cannot contain '*'") if set.include_star?
+        set
       end
 
       def nil_atom

data/lib/net/imap/sequence_set.rb

@@ -56,18 +56,20 @@ module Net
     #     set = Net::IMAP::SequenceSet[1, 2, [3..7, 5], 6..10, 2048, 1024]
     #     set.valid_string  #=> "1:10,55,1024:2048"
     #
-    # == Normalized form
+    # == Ordered and Normalized sets
     #
-    # When a sequence set is created with a single String value, that #string
-    # representation is preserved.  SequenceSet's internal representation
-    # implicitly sorts all entries, de-duplicates numbers, and coalesces
-    # adjacent or overlapping ranges.  Most enumeration methods and offset-based
-    # methods use this normalized representation.  Most modification methods
-    # will convert #string to its normalized form.
+    # Sometimes the order of the set's members is significant, such as with the
+    # +ESORT+, <tt>CONTEXT=SORT</tt>, and +UIDPLUS+ extensions.  So, when a
+    # sequence set is created by the parser or with a single string value, that
+    # #string representation is preserved.
     #
-    # In some cases the order of the string representation is significant, such
-    # as the +ESORT+, <tt>CONTEXT=SORT</tt>, and +UIDPLUS+ extensions.  Use
-    # #entries or #each_entry to enumerate the set in its original order.  To
+    # Internally, SequenceSet stores a normalized representation which sorts all
+    # entries, de-duplicates numbers, and coalesces adjacent or overlapping
+    # ranges.  Most methods use this normalized representation to achieve
+    # <tt>O(lg n)</tt> porformance.  Use #entries or #each_entry to enumerate
+    # the set in its original order.
+    #
+    # Most modification methods convert #string to its normalized form.  To
     # preserve #string order while modifying a set, use #append, #string=, or
     # #replace.
     #
@@ -160,7 +162,7 @@ module Net
     # - #===:
     #   Returns whether a given object is fully contained within +self+, or
     #   +nil+ if the object cannot be converted to a compatible type.
-    # - #cover? (aliased as #===):
+    # - #cover?:
     #   Returns whether a given object is fully contained within +self+.
     # - #intersect? (aliased as #overlap?):
     #   Returns whether +self+ and a given object have any common elements.
@@ -181,30 +183,41 @@ module Net
     # - #max: Returns the maximum number in the set.
     # - #minmax: Returns the minimum and maximum numbers in the set.
     #
-    # <i>Accessing value by offset:</i>
+    # <i>Accessing value by offset in sorted set:</i>
     # - #[] (aliased as #slice): Returns the number or consecutive subset at a
-    #   given offset or range of offsets.
-    # - #at: Returns the number at a given offset.
-    # - #find_index: Returns the given number's offset in the set
+    #   given offset or range of offsets in the sorted set.
+    # - #at: Returns the number at a given offset in the sorted set.
+    # - #find_index: Returns the given number's offset in the sorted set.
+    #
+    # <i>Accessing value by offset in ordered entries</i>
+    # - #ordered_at: Returns the number at a given offset in the ordered entries.
+    # - #find_ordered_index: Returns the index of the given number's first
+    #   occurrence in entries.
     #
     # <i>Set cardinality:</i>
     # - #count (aliased as #size): Returns the count of numbers in the set.
+    #   Duplicated numbers are not counted.
     # - #empty?: Returns whether the set has no members.  \IMAP syntax does not
     #   allow empty sequence sets.
     # - #valid?: Returns whether the set has any members.
     # - #full?: Returns whether the set contains every possible value, including
     #   <tt>*</tt>.
     #
+    # <i>Denormalized properties:</i>
+    # - #has_duplicates?: Returns whether the ordered entries repeat any
+    #   numbers.
+    # - #count_duplicates: Returns the count of repeated numbers in the ordered
+    #   entries.
+    # - #count_with_duplicates: Returns the count of numbers in the ordered
+    #   entries, including any repeated numbers.
+    #
     # === Methods for Iterating
     #
+    # <i>Normalized (sorted and coalesced):</i>
     # - #each_element: Yields each number and range in the set, sorted and
     #   coalesced, and returns +self+.
     # - #elements (aliased as #to_a): Returns an Array of every number and range
     #   in the set, sorted and coalesced.
-    # - #each_entry: Yields each number and range in the set, unsorted and
-    #   without deduplicating numbers or coalescing ranges, and returns +self+.
-    # - #entries: Returns an Array of every number and range in the set,
-    #   unsorted and without deduplicating numbers or coalescing ranges.
     # - #each_range:
     #   Yields each element in the set as a Range and returns +self+.
     # - #ranges: Returns an Array of every element in the set, converting
@@ -214,6 +227,14 @@ module Net
     #   ranges into all of their contained numbers.
     # - #to_set: Returns a Set containing all of the #numbers in the set.
     #
+    # <i>Order preserving:</i>
+    # - #each_entry: Yields each number and range in the set, unsorted and
+    #   without deduplicating numbers or coalescing ranges, and returns +self+.
+    # - #entries: Returns an Array of every number and range in the set,
+    #   unsorted and without deduplicating numbers or coalescing ranges.
+    # - #each_ordered_number: Yields each number in the ordered entries and
+    #   returns +self+.
+    #
     # === Methods for \Set Operations
     # These methods do not modify +self+.
     #
@@ -233,19 +254,29 @@ module Net
     # === Methods for Assigning
     # These methods add or replace elements in +self+.
     #
+    # <i>Normalized (sorted and coalesced):</i>
+    #
+    # 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
     #   returns +self+; otherwise, returns +nil+.
     # - #merge: Merges multiple elements into the 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
     #   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
     #   of a given object.
-    # - #complement!: Replaces the contents of the set with its own #complement.
     #
     # === Methods for Deleting
-    # These methods remove elements from +self+.
+    # These methods remove elements from +self+, and update #string to be fully
+    # sorted and coalesced.
     #
     # - #clear: Removes all elements in the set; returns +self+.
     # - #delete: Removes a given object from the set; returns +self+.
@@ -681,8 +712,9 @@ module Net
         modifying!
         tuple = input_to_tuple object
         entry = tuple_to_str tuple
+        string unless empty? # write @string before tuple_add
         tuple_add tuple
-        @string = -(string ? "#{@string},#{entry}" : entry)
+        @string = -(@string ? "#{@string},#{entry}" : entry)
         self
       end
 
@@ -838,8 +870,8 @@ module Net
       # <tt>*</tt> translates to an endless range.  Use #limit to translate both
       # cases to a maximum value.
       #
-      # If the original input was unordered or contains overlapping ranges, the
-      # returned ranges will be ordered and coalesced.
+      # The returned elements will be sorted and coalesced, even when the input
+      # #string is not.  <tt>*</tt> will sort last.  See #normalize.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].elements
       #   #=> [2, 5..9, 11..12, :*]
@@ -857,7 +889,7 @@ module Net
       # translates to <tt>:*..</tt>.  Use #limit to set <tt>*</tt> to a maximum
       # value.
       #
-      # The returned ranges will be ordered and coalesced, even when the input
+      # The returned ranges will be sorted and coalesced, even when the input
       # #string is not.  <tt>*</tt> will sort last.  See #normalize.
       #
       #   Net::IMAP::SequenceSet["2,5:9,6,*,12:11"].ranges
@@ -906,9 +938,7 @@ module Net
       # Related: #entries, #each_element
       def each_entry(&block) # :yields: integer or range or :*
         return to_enum(__method__) unless block_given?
-        return each_element(&block) unless @string
-        @string.split(",").each do yield tuple_to_entry str_to_tuple _1 end
-        self
+        each_entry_tuple do yield tuple_to_entry _1 end
       end
 
       # Yields each number or range (or <tt>:*</tt>) in #elements to the block
@@ -926,6 +956,16 @@ module Net
 
       private
 
+      def each_entry_tuple(&block)
+        return to_enum(__method__) unless block_given?
+        if @string
+          @string.split(",") do block.call str_to_tuple _1 end
+        else
+          @tuples.each(&block)
+        end
+        self
+      end
+
       def tuple_to_entry((min, max))
         if    min == STAR_INT then :*
         elsif max == STAR_INT then min..
@@ -957,19 +997,36 @@ module Net
       # Returns an enumerator when called without a block (even if the set
       # contains <tt>*</tt>).
       #
-      # Related: #numbers
+      # Related: #numbers, #each_ordered_number
       def each_number(&block) # :yields: integer
         return to_enum(__method__) unless block_given?
         raise RangeError, '%s contains "*"' % [self.class] if include_star?
-        each_element do |elem|
-          case elem
-          when Range   then elem.each(&block)
-          when Integer then block.(elem)
-          end
-        end
+        @tuples.each do each_number_in_tuple _1, _2, &block end
         self
       end
 
+      # Yields each number in #entries to the block and returns self.
+      # If the set contains a <tt>*</tt>, RangeError will be raised.
+      #
+      # Returns an enumerator when called without a block (even if the set
+      # contains <tt>*</tt>).
+      #
+      # Related: #entries, #each_number
+      def each_ordered_number(&block)
+        return to_enum(__method__) unless block_given?
+        raise RangeError, '%s contains "*"' % [self.class] if include_star?
+        each_entry_tuple do each_number_in_tuple _1, _2, &block end
+      end
+
+      private def each_number_in_tuple(min, max, &block)
+        if    min == STAR_INT then yield :*
+        elsif min == max      then yield min
+        elsif max != STAR_INT then (min..max).each(&block)
+        else
+          raise RangeError, "#{SequenceSet} cannot enumerate range with '*'"
+        end
+      end
+
       # Returns a Set with all of the #numbers in the sequence set.
       #
       # If the set contains a <tt>*</tt>, RangeError will be raised.
@@ -981,8 +1038,10 @@ module Net
 
       # Returns the count of #numbers in the set.
       #
-      # If <tt>*</tt> and <tt>2**32 - 1</tt> (the maximum 32-bit unsigned
-      # integer value) are both in the set, they will only be counted once.
+      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
+      # unsigned integer value).
+      #
+      # Related: #count_with_duplicates
       def count
         @tuples.sum(@tuples.count) { _2 - _1 } +
           (include_star? && include?(UINT32_MAX) ? -1 : 0)
@@ -990,33 +1049,87 @@ module Net
 
       alias size count
 
-      # Returns the index of +number+ in the set, or +nil+ if +number+ isn't in
-      # the set.
+      # Returns the count of numbers in the ordered #entries, including any
+      # repeated numbers.
+      #
+      # <tt>*</tt> will be counted as <tt>2**32 - 1</tt> (the maximum 32-bit
+      # unsigned integer value).
+      #
+      # When #string is normalized, this behaves the same as #count.
       #
-      # Related: #[]
+      # Related: #entries, #count_duplicates, #has_duplicates?
+      def count_with_duplicates
+        return count unless @string
+        each_entry_tuple.sum {|min, max|
+          max - min + ((max == STAR_INT && min != STAR_INT) ? 0 : 1)
+        }
+      end
+
+      # Returns the count of repeated numbers in the ordered #entries, the
+      # difference between #count_with_duplicates and #count.
+      #
+      # When #string is normalized, this is zero.
+      #
+      # Related: #entries, #count_with_duplicates, #has_duplicates?
+      def count_duplicates
+        return 0 unless @string
+        count_with_duplicates - count
+      end
+
+      # :call-seq: has_duplicates? -> true | false
+      #
+      # Returns whether or not the ordered #entries repeat any numbers.
+      #
+      # Always returns +false+ when #string is normalized.
+      #
+      # Related: #entries, #count_with_duplicates, #count_duplicates?
+      def has_duplicates?
+        return false unless @string
+        count_with_duplicates != count
+      end
+
+      # Returns the (sorted and deduplicated) index of +number+ in the set, or
+      # +nil+ if +number+ isn't in the set.
+      #
+      # Related: #[], #at, #find_ordered_index
       def find_index(number)
         number = to_tuple_int number
-        each_tuple_with_index do |min, max, idx_min|
+        each_tuple_with_index(@tuples) do |min, max, idx_min|
           number <  min and return nil
           number <= max and return from_tuple_int(idx_min + (number - min))
         end
         nil
       end
 
+      # Returns the first index of +number+ in the ordered #entries, or
+      # +nil+ if +number+ isn't in the set.
+      #
+      # Related: #find_index
+      def find_ordered_index(number)
+        number = to_tuple_int number
+        each_tuple_with_index(each_entry_tuple) do |min, max, idx_min|
+          if min <= number && number <= max
+            return from_tuple_int(idx_min + (number - min))
+          end
+        end
+        nil
+      end
+
       private
 
-      def each_tuple_with_index
+      def each_tuple_with_index(tuples)
         idx_min = 0
-        @tuples.each do |min, max|
-          yield min, max, idx_min, (idx_max = idx_min + (max - min))
+        tuples.each do |min, max|
+          idx_max = idx_min + (max - min)
+          yield min, max, idx_min, idx_max
           idx_min = idx_max + 1
         end
         idx_min
       end
 
-      def reverse_each_tuple_with_index
+      def reverse_each_tuple_with_index(tuples)
         idx_max = -1
-        @tuples.reverse_each do |min, max|
+        tuples.reverse_each do |min, max|
           yield min, max, (idx_min = idx_max - (max - min)), idx_max
           idx_max = idx_min - 1
         end
@@ -1027,18 +1140,38 @@ module Net
 
       # :call-seq: at(index) -> integer or nil
       #
-      # Returns a number from +self+, without modifying the set.  Behaves the
-      # same as #[], except that #at only allows a single integer argument.
+      # Returns the number at the given +index+ in the sorted set, without
+      # modifying the set.
       #
-      # Related: #[], #slice
+      # +index+ is interpreted the same as in #[], except that #at only allows a
+      # single integer argument.
+      #
+      # Related: #[], #slice, #ordered_at
       def at(index)
+        lookup_number_by_tuple_index(tuples, index)
+      end
+
+      # :call-seq: ordered_at(index) -> integer or nil
+      #
+      # Returns the number at the given +index+ in the ordered #entries, without
+      # modifying the set.
+      #
+      # +index+ is interpreted the same as in #at (and #[]), except that
+      # #ordered_at applies to the ordered #entries, not the sorted set.
+      #
+      # Related: #[], #slice, #ordered_at
+      def ordered_at(index)
+        lookup_number_by_tuple_index(each_entry_tuple, index)
+      end
+
+      private def lookup_number_by_tuple_index(tuples, index)
         index = Integer(index.to_int)
         if index.negative?
-          reverse_each_tuple_with_index do |min, max, idx_min, idx_max|
+          reverse_each_tuple_with_index(tuples) do |min, max, idx_min, idx_max|
             idx_min <= index and return from_tuple_int(min + (index - idx_min))
           end
         else
-          each_tuple_with_index do |min, _, idx_min, idx_max|
+          each_tuple_with_index(tuples) do |min, _, idx_min, idx_max|
             index <= idx_max and return from_tuple_int(min + (index - idx_min))
           end
         end
@@ -1053,17 +1186,18 @@ module Net
       #    seqset[range]         -> sequence set or nil
       #    slice(range)          -> sequence set or nil
       #
-      # Returns a number or a subset from +self+, without modifying the set.
+      # Returns a number or a subset from the _sorted_ set, without modifying
+      # the set.
       #
       # When an Integer argument +index+ is given, the number at offset +index+
-      # is returned:
+      # in the sorted set is returned:
       #
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[0]   #=> 10
       #     set[5]   #=> 15
       #     set[10]  #=> 26
       #
-      # If +index+ is negative, it counts relative to the end of +self+:
+      # If +index+ is negative, it counts relative to the end of the sorted set:
       #     set = Net::IMAP::SequenceSet["10:15,20:23,26"]
       #     set[-1]  #=> 26
       #     set[-3]  #=> 22
@@ -1075,13 +1209,14 @@ module Net
       #     set[11]  #=> nil
       #     set[-12] #=> nil
       #
-      # The result is based on the normalized set—sorted and de-duplicated—not
-      # on the assigned value of #string.
+      # The result is based on the sorted and de-duplicated set, not on the
+      # ordered #entries in #string.
       #
       #     set = Net::IMAP::SequenceSet["12,20:23,11:16,21"]
       #     set[0]   #=> 11
       #     set[-1]  #=> 23
       #
+      # Related: #at
       def [](index, length = nil)
         if    length              then slice_length(index, length)
         elsif index.is_a?(Range)  then slice_range(index)
@@ -1337,8 +1472,8 @@ module Net
         modifying!
         min, max = tuple
         lower, lower_idx = tuple_gte_with_index(min - 1)
-        if    lower.nil?              then tuples << tuple
-        elsif (max + 1) < lower.first then tuples.insert(lower_idx, tuple)
+        if    lower.nil?              then tuples << [min, max]
+        elsif (max + 1) < lower.first then tuples.insert(lower_idx, [min, max])
         else  tuple_coalesce(lower, lower_idx, min, max)
         end
       end

data/lib/net/imap/uidplus_data.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # *NOTE:* <em>UIDPlusData is deprecated and will be removed in the +0.6.0+
+    # release.</em>  To use AppendUIDData and CopyUIDData before +0.6.0+, set
+    # Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # UIDPlusData represents the ResponseCode#data that accompanies the
+    # +APPENDUID+ and +COPYUID+ {response codes}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ should send UIDPlusData in response to
+    # the append[rdoc-ref:Net::IMAP#append], copy[rdoc-ref:Net::IMAP#copy],
+    # move[rdoc-ref:Net::IMAP#move], {uid copy}[rdoc-ref:Net::IMAP#uid_copy],
+    # and {uid move}[rdoc-ref:Net::IMAP#uid_move] commands---unless the
+    # destination mailbox reports +UIDNOTSTICKY+.
+    #
+    # Note that append[rdoc-ref:Net::IMAP#append], copy[rdoc-ref:Net::IMAP#copy]
+    # and {uid_copy}[rdoc-ref:Net::IMAP#uid_copy] return UIDPlusData in their
+    # TaggedResponse.  But move[rdoc-ref:Net::IMAP#copy] and
+    # {uid_move}[rdoc-ref:Net::IMAP#uid_move] _should_ send UIDPlusData in an
+    # UntaggedResponse response before sending their TaggedResponse.  However
+    # some servers do send UIDPlusData in the TaggedResponse for +MOVE+
+    # commands---this complies with the older +UIDPLUS+ specification but is
+    # discouraged by the +MOVE+ extension and disallowed by +IMAP4rev2+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    #
+    class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids)
+      ##
+      # method: uidvalidity
+      # :call-seq: uidvalidity -> nonzero uint32
+      #
+      # The UIDVALIDITY of the destination mailbox.
+
+      ##
+      # method: source_uids
+      # :call-seq: source_uids -> nil or an array of nonzero uint32
+      #
+      # The UIDs of the copied or moved messages.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+
+      ##
+      # method: assigned_uids
+      # :call-seq: assigned_uids -> an array of nonzero uint32
+      #
+      # The newly assigned UIDs of the copied, moved, or appended messages.
+      #
+      # Note:: This always returns an array, even when it contains only one UID.
+
+      ##
+      # :call-seq: uid_mapping -> nil or a hash
+      #
+      # Returns a hash mapping each source UID to the newly assigned destination
+      # UID.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+      def uid_mapping
+        source_uids&.zip(assigned_uids)&.to_h
+      end
+    end
+
+    # >>>
+    #   *NOTE:* <em>AppendUIDData will replace UIDPlusData for +APPENDUID+ in the
+    #   +0.6.0+ release.</em>  To use AppendUIDData before +0.6.0+, set
+    #   Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # AppendUIDData represents the ResponseCode#data that accompanies the
+    # +APPENDUID+ {response code}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ (or +IMAP4rev2+) should send
+    # AppendUIDData inside every TaggedResponse returned by the
+    # append[rdoc-ref:Net::IMAP#append] command---unless the target mailbox
+    # reports +UIDNOTSTICKY+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    class AppendUIDData < Data.define(:uidvalidity, :assigned_uids)
+      def initialize(uidvalidity:, assigned_uids:)
+        uidvalidity   = Integer(uidvalidity)
+        assigned_uids = SequenceSet[assigned_uids]
+        NumValidator.ensure_nz_number(uidvalidity)
+        if assigned_uids.include_star?
+          raise DataFormatError, "uid-set cannot contain '*'"
+        end
+        super
+      end
+
+      ##
+      # attr_reader: uidvalidity
+      # :call-seq: uidvalidity -> nonzero uint32
+      #
+      # The UIDVALIDITY of the destination mailbox.
+
+      ##
+      # attr_reader: assigned_uids
+      #
+      # A SequenceSet with the newly assigned UIDs of the appended messages.
+
+      # Returns the number of messages that have been appended.
+      def size
+        assigned_uids.count_with_duplicates
+      end
+    end
+
+    # >>>
+    #   *NOTE:* <em>CopyUIDData will replace UIDPlusData for +COPYUID+ in the
+    #   +0.6.0+ release.</em>  To use CopyUIDData before +0.6.0+, set
+    #   Config#parser_use_deprecated_uidplus_data to +false+.
+    #
+    # CopyUIDData represents the ResponseCode#data that accompanies the
+    # +COPYUID+ {response code}[rdoc-ref:ResponseCode].
+    #
+    # A server that supports +UIDPLUS+ (or +IMAP4rev2+) should send CopyUIDData
+    # in response to
+    # copy[rdoc-ref:Net::IMAP#copy], {uid_copy}[rdoc-ref:Net::IMAP#uid_copy],
+    # move[rdoc-ref:Net::IMAP#copy], and {uid_move}[rdoc-ref:Net::IMAP#uid_move]
+    # commands---unless the destination mailbox reports +UIDNOTSTICKY+.
+    #
+    # Note that copy[rdoc-ref:Net::IMAP#copy] and
+    # {uid_copy}[rdoc-ref:Net::IMAP#uid_copy] return CopyUIDData in their
+    # TaggedResponse.  But move[rdoc-ref:Net::IMAP#copy] and
+    # {uid_move}[rdoc-ref:Net::IMAP#uid_move] _should_ send CopyUIDData in an
+    # UntaggedResponse response before sending their TaggedResponse.  However
+    # some servers do send CopyUIDData in the TaggedResponse for +MOVE+
+    # commands---this complies with the older +UIDPLUS+ specification but is
+    # discouraged by the +MOVE+ extension and disallowed by +IMAP4rev2+.
+    #
+    # == Required capability
+    # Requires either +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315]]
+    # or +IMAP4rev2+ capability.
+    class CopyUIDData < Data.define(:uidvalidity, :source_uids, :assigned_uids)
+      def initialize(uidvalidity:, source_uids:, assigned_uids:)
+        uidvalidity   = Integer(uidvalidity)
+        source_uids   = SequenceSet[source_uids]
+        assigned_uids = SequenceSet[assigned_uids]
+        NumValidator.ensure_nz_number(uidvalidity)
+        if source_uids.include_star? || assigned_uids.include_star?
+          raise DataFormatError, "uid-set cannot contain '*'"
+        elsif source_uids.count_with_duplicates != assigned_uids.count_with_duplicates
+          raise DataFormatError, "mismatched uid-set sizes for %s and %s" % [
+            source_uids, assigned_uids
+          ]
+        end
+        super
+      end
+
+      ##
+      # attr_reader: uidvalidity
+      #
+      # The +UIDVALIDITY+ of the destination mailbox (a nonzero unsigned 32 bit
+      # integer).
+
+      ##
+      # attr_reader: source_uids
+      #
+      # A SequenceSet with the original UIDs of the copied or moved messages.
+
+      ##
+      # attr_reader: assigned_uids
+      #
+      # A SequenceSet with the newly assigned UIDs of the copied or moved
+      # messages.
+
+      # Returns the number of messages that have been copied or moved.
+      # source_uids and the assigned_uids will both the same number of UIDs.
+      def size
+        assigned_uids.count_with_duplicates
+      end
+
+      # :call-seq:
+      #   assigned_uid_for(source_uid) -> uid
+      #   self[source_uid] -> uid
+      #
+      # Returns the UID in the destination mailbox for the message that was
+      # copied from +source_uid+ in the source mailbox.
+      #
+      # This is the reverse of #source_uid_for.
+      #
+      # Related: source_uid_for, each_uid_pair, uid_mapping
+      def assigned_uid_for(source_uid)
+        idx = source_uids.find_ordered_index(source_uid) and
+          assigned_uids.ordered_at(idx)
+      end
+      alias :[] :assigned_uid_for
+
+      # :call-seq:
+      #   source_uid_for(assigned_uid) -> uid
+      #
+      # Returns the UID in the source mailbox for the message that was copied to
+      # +assigned_uid+ in the source mailbox.
+      #
+      # This is the reverse of #assigned_uid_for.
+      #
+      # Related: assigned_uid_for, each_uid_pair, uid_mapping
+      def source_uid_for(assigned_uid)
+        idx = assigned_uids.find_ordered_index(assigned_uid) and
+          source_uids.ordered_at(idx)
+      end
+
+      # Yields a pair of UIDs for each copied message.  The first is the
+      # message's UID in the source mailbox and the second is the UID in the
+      # destination mailbox.
+      #
+      # Returns an enumerator when no block is given.
+      #
+      # Please note the warning on uid_mapping before calling methods like
+      # +to_h+ or +to_a+ on the returned enumerator.
+      #
+      # Related: uid_mapping, assigned_uid_for, source_uid_for
+      def each_uid_pair
+        return enum_for(__method__) unless block_given?
+        source_uids.each_ordered_number.lazy
+          .zip(assigned_uids.each_ordered_number.lazy) do
+            |source_uid, assigned_uid|
+            yield source_uid, assigned_uid
+          end
+      end
+      alias each_pair each_uid_pair
+      alias each      each_uid_pair
+
+      # :call-seq: uid_mapping -> hash
+      #
+      # Returns a hash mapping each source UID to the newly assigned destination
+      # UID.
+      #
+      # <em>*Warning:*</em> The hash that is created may consume _much_ more
+      # memory than the data used to create it.  When handling responses from an
+      # untrusted server, check #size before calling this method.
+      #
+      # Related: each_uid_pair, assigned_uid_for, source_uid_for
+      def uid_mapping
+        each_uid_pair.to_h
+      end
+
+    end
+
+  end
+end

data/lib/net/imap.rb

@@ -744,7 +744,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.5.5"
+    VERSION = "0.5.6"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1239,13 +1239,21 @@ module Net
     #
     def starttls(**options)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(options)
-      send_command("STARTTLS") do |resp|
+      error = nil
+      ok = send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
           clear_cached_capabilities
           clear_responses
           start_tls_session
         end
+      rescue Exception => error
+        raise # note that the error backtrace is in the receiver_thread
       end
+      if error
+        disconnect
+        raise error
+      end
+      ok
     end
 
     # :call-seq:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.5
+  version: 0.5.6
 platform: ruby
 authors:
 - Shugo Maeda
 - nicholas a. evans
 bindir: exe
 cert_chain: []
-date: 2025-01-04 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -96,6 +96,7 @@ files:
 - lib/net/imap/stringprep/saslprep_tables.rb
 - lib/net/imap/stringprep/tables.rb
 - lib/net/imap/stringprep/trace.rb
+- lib/net/imap/uidplus_data.rb
 - lib/net/imap/vanished_data.rb
 - net-imap.gemspec
 - rakelib/benchmarks.rake