net-imap 0.5.2 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d271261a2609a31b8c84ae74913bf57d5046e95318db7660b3230940bdbff447
-  data.tar.gz: 771baa4b8a6c3f83f6ef4f320dda8dc5ea9f2fa2ace15fd9b0c1c1b3a594363a
+  metadata.gz: cdbdda0ed73da899ec338f66022a16104562d3701c568b0a6d4897270a608ac5
+  data.tar.gz: b6a7ec70776b32f8eb57d01a0869503eb5d76f719ac091eb92e0206608e936e9
 SHA512:
-  metadata.gz: 230d40d8d183b1c69f63050990df140b49aa5731d0868713e44d2da68c2713ede4fd8d4b1aff60103c25ac6586076e220973b774a43cd5a7b3eaad4e49e7bf3b
-  data.tar.gz: 156e6c86f6fe39a76de89275bfcd3c57b5adcd375de6add45cd00a30bf92bbf04a2b475702db33cae0509fc0b7b3e015518d4991cd5c467f833cacb0f75d3ca6
+  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/README.md

@@ -1,7 +1,9 @@
 # Net::IMAP
 
 Net::IMAP implements Internet Message Access Protocol (IMAP) client
-functionality.  The protocol is described in [IMAP](https://tools.ietf.org/html/rfc3501).
+functionality.  The protocol is described in
+[RFC3501](https://www.rfc-editor.org/rfc/rfc3501),
+[RFC9051](https://www.rfc-editor.org/rfc/rfc9051) and various extensions.
 
 ## Installation
 

data/docs/styles.css

@@ -6,33 +6,38 @@
 
 main .method-detail {
   display: grid;
-  grid-template-areas:   "header         controls"
-                         "description description";
-  grid-template-columns: 1fr           min-content;
+  grid-template-columns: 1fr auto;
   justify-content: space-between;
 }
 
-main .method-header, main .method-controls {
+main .method-header,
+main .method-controls,
+.attribute-method-heading {
   padding: 0.5em;
   /* border: 1px solid var(--highlight-color); */
   background: var(--table-header-background-color);
   line-height: 1.6;
 }
 
+.attribute-method-heading .attribute-access-type {
+  float: right;
+}
+
 main .method-header {
-  grid-area: "header";
   border-right: none;
   border-radius: 4px 0 0 4px;
 }
 
+main .method-heading :any-link {
+  text-decoration: none;
+}
+
 main .method-controls {
-  grid-area: "controls";
   border-left: none;
   border-radius: 0 4px 4px 0;
 }
 
 main .method-description, main .aliases {
-  grid-area: "description";
   grid-column: 1 / span 2;
   padding-left: 1em;
 }

data/lib/net/imap/command_data.rb

@@ -153,6 +153,38 @@ module Net
       end
     end
 
+    class PartialRange < CommandData # :nodoc:
+      uint32_max = 2**32 - 1
+      POS_RANGE = 1..uint32_max
+      NEG_RANGE = -uint32_max..-1
+      Positive = ->{ (_1 in Range) and POS_RANGE.cover?(_1) }
+      Negative = ->{ (_1 in Range) and NEG_RANGE.cover?(_1) }
+
+      def initialize(data:)
+        min, max = case data
+        in Range
+          data.minmax.map { Integer _1 }
+        in ResponseParser::Patterns::PARTIAL_RANGE
+          data.split(":").map { Integer _1 }.minmax
+        else
+          raise ArgumentError, "invalid partial range input: %p" % [data]
+        end
+        data = min..max
+        unless data in Positive | Negative
+          raise ArgumentError, "invalid partial-range: %p" % [data]
+        end
+        super
+      rescue TypeError, RangeError
+        raise ArgumentError, "expected range min/max to be Integers"
+      end
+
+      def formatted = "%d:%d" % data.minmax
+
+      def send_data(imap, tag)
+        imap.__send__(:put_string, formatted)
+      end
+    end
+
     # *DEPRECATED*.  Replaced by SequenceSet.
     class MessageSet < CommandData # :nodoc:
       def send_data(imap, tag)

data/lib/net/imap/config.rb

@@ -75,7 +75,7 @@ module Net
     #
     #   client = Net::IMAP.new(hostname, config: :future)
     #   client.config.sasl_ir                  # => true
-    #   client.config.responses_without_block  # => :raise
+    #   client.config.responses_without_block  # => :frozen_dup
     #
     # The versioned default configs inherit certain specific config options from
     # Config.global, for example #debug:
@@ -109,9 +109,11 @@ module Net
     # [+:future+]
     #   The _planned_ eventual config for some future +x.y+ version.
     #
-    # For example, to raise exceptions for all current deprecations:
+    # For example, to disable all currently deprecated behavior:
     #   client = Net::IMAP.new(hostname, config: :future)
-    #   client.responses  # raises an ArgumentError
+    #   client.config.response_without_args     # => :frozen_dup
+    #   client.responses.frozen?                # => true
+    #   client.responses.values.all?(&:frozen?) # => true
     #
     # == Thread Safety
     #
@@ -285,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.
@@ -365,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
@@ -376,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]
@@ -384,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/data_lite.rb

@@ -29,7 +29,7 @@ module Net
   class IMAP
     data_or_object = RUBY_VERSION >= "3.2.0" ? ::Data : Object
     class DataLite < data_or_object
-      def encode_with(coder) coder.map = attributes.transform_keys(&:to_s) end
+      def encode_with(coder) coder.map = to_h.transform_keys(&:to_s)        end
       def init_with(coder) initialize(**coder.map.transform_keys(&:to_sym)) end
     end
 
@@ -159,28 +159,27 @@ module Net
 
       ##
       def members;     self.class.members                              end
-      def attributes;  Hash[members.map {|m| [m, send(m)] }]           end
-      def to_h(&block) attributes.to_h(&block)                         end
-      def hash;        [self.class, attributes].hash                   end
+      def to_h(&block) block ? __to_h__.to_h(&block) : __to_h__        end
+      def hash;        [self.class, __to_h__].hash                     end
       def ==(other)    self.class == other.class && to_h == other.to_h end
       def eql?(other)  self.class == other.class && hash == other.hash end
-      def deconstruct; attributes.values                               end
+      def deconstruct; __to_h__.values                                 end
 
       def deconstruct_keys(keys)
         raise TypeError unless keys.is_a?(Array) || keys.nil?
-        return attributes if keys&.first.nil?
-        attributes.slice(*keys)
+        return __to_h__ if keys&.first.nil?
+        __to_h__.slice(*keys)
       end
 
       def with(**kwargs)
         return self if kwargs.empty?
-        self.class.new(**attributes.merge(kwargs))
+        self.class.new(**__to_h__.merge(kwargs))
       end
 
       def inspect
         __inspect_guard__(self) do |seen|
           return "#<data #{self.class}:...>" if seen
-          attrs = attributes.map {|kv| "%s=%p" % kv }.join(", ")
+          attrs = __to_h__.map {|kv| "%s=%p" % kv }.join(", ")
           display = ["data", self.class.name, attrs].compact.join(" ")
           "#<#{display}>"
         end
@@ -190,7 +189,9 @@ module Net
       private
 
       def initialize_copy(source) super.freeze end
-      def marshal_dump; attributes end
+      def marshal_dump; __to_h__ end
+
+      def __to_h__; Hash[members.map {|m| [m, send(m)] }] end
 
       # Yields +true+ if +obj+ has been seen already, +false+ if it hasn't.
       # Marks +obj+ as seen inside the block, so circuler references don't

data/lib/net/imap/esearch_result.rb

@@ -35,16 +35,16 @@ module Net
 
       # :call-seq: to_a -> Array of integers
       #
-      # When #all contains a SequenceSet of message sequence
+      # When either #all or #partial contains a SequenceSet of message sequence
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
-      # When #all is +nil+, either because the server
-      # returned no results or because +ALL+ was not included in
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because +ALL+ and +PARTIAL+ were not included in
       # the IMAP#search +RETURN+ options, #to_a returns an empty array.
       #
       # Note that SearchResult also implements +to_a+, so it can be used without
       # checking if the server returned +SEARCH+ or +ESEARCH+ data.
-      def to_a; all&.numbers || [] end
+      def to_a; all&.numbers || partial&.to_a || [] end
 
       ##
       # attr_reader: tag
@@ -135,6 +135,46 @@ module Net
       # and +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.2].
       def modseq;     data.assoc("MODSEQ")&.last     end
 
+      # Returned by ESearchResult#partial.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      class PartialResult < Data.define(:range, :results)
+        def initialize(range:, results:)
+          range   => Range
+          results = SequenceSet[results] unless results.nil?
+          super
+        end
+
+        ##
+        # method: range
+        # :call-seq: range -> range
+
+        ##
+        # method: results
+        # :call-seq: results -> sequence set or nil
+
+        # Converts #results to an array of integers.
+        #
+        # See also: ESearchResult#to_a.
+        def to_a; results&.numbers || [] end
+      end
+
+      # :call-seq: partial -> PartialResult or nil
+      #
+      # A PartialResult containing a subset of the message sequence numbers or
+      # UIDs that satisfy the SEARCH criteria.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      def partial;    data.assoc("PARTIAL")&.last    end
+
     end
   end
 end