net-imap 0.5.1 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf511b8683c6931cf9ec2d3aa4a55ef634a2cc0e670590a4142d9895594b9191
-  data.tar.gz: db4ca0b7230553258e0d81a8a5b5cbed4273e30245200db661145ba430af20d0
+  metadata.gz: ee48ac78f129043fd8ccb4f6e0b42535cc0ef3a6acd8ea1067cbd9b512815e49
+  data.tar.gz: 5bfae3bf0ee2e63c5b61c19d30187fe722adfe8018746e64d583124531de87a8
 SHA512:
-  metadata.gz: b61a04c6992df7d6ffcf0e5396723966c3f3a5a1c6a596caf413c63d355100c8d2c28096a2261045d52ada4d8e995bba1c4f12864bf65fe1355c331df236eb85
-  data.tar.gz: 0bc68ec15c5d53f0f437eab5318bf8cdd428dcdc650a98f66e961658ed361b125e866db2d41954e50ce66de5ec143d108e9135f554bd240ff0d7057724d16416
+  metadata.gz: f90a4500f3c218dd3a51cca84a76c620fa8f8488f2ca73486b538a43e67e21e0b897d23d957f490afe1590fd755c692f2e0dede562460ed2cfcd7f4d9bec3262
+  data.tar.gz: 22abb3cf5699bb715c33c69b596ead46ff400109925f58d633ecdc82797be9b80fbbd040c02aa7cd9286f3aa9c697e9fc426f1115b9019455b2ac4e6667cc236

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
 
@@ -50,12 +52,16 @@ end
 
 ```ruby
 imap.select('Mail/sent-mail')
-if not imap.list('Mail/', 'sent-apr03')
+if imap.list('Mail/', 'sent-apr03').empty?
   imap.create('Mail/sent-apr03')
 end
 imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id|
-  imap.copy(message_id, "Mail/sent-apr03")
-  imap.store(message_id, "+FLAGS", [:Deleted])
+  if imap.capable?(:move) || imap.capable?(:IMAP4rev2)
+    imap.move(message_id, "Mail/sent-apr03")
+  else
+    imap.copy(message_id, "Mail/sent-apr03")
+    imap.store(message_id, "+FLAGS", [:Deleted])
+  end
 end
 imap.expunge
 ```

data/docs/styles.css

@@ -1,24 +1,85 @@
 /* this is a work in progress. :) */
 
-main .method-header {
-  background: rgba(27,31,35,0.05);
-  border: 1px solid #6C8C22;
+/***********************************************
+ * Method descriptions
+ ***********************************************/
+
+main .method-detail {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  justify-content: space-between;
+}
+
+main .method-header,
+main .method-controls,
+.attribute-method-heading {
   padding: 0.5em;
-  border-radius: 4px;
-  /* padding: 0 0.5em; */
-  /* border-width: 0 1px; */
-  /* border-color: #6C8C22; */
-  /* border-style: solid; */
+  /* 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 {
+  border-right: none;
+  border-radius: 4px 0 0 4px;
+}
+
+main .method-heading :any-link {
+  text-decoration: none;
+}
+
+main .method-controls {
+  border-left: none;
+  border-radius: 0 4px 4px 0;
 }
 
 main .method-description, main .aliases {
+  grid-column: 1 / span 2;
   padding-left: 1em;
 }
 
-body {
-  /*
-   * The default (300) can be too low contrast.  Also, many fonts don't
-   * distinguish between 300->400, so <em>...</em> had no effect.
-   */
-  font-weight: 400;
+@media (max-width: 700px) {
+  main .method-header, main .method-controls, main .method-description {
+    grid-column: 1 / span 2;
+    margin: 0;
+  }
+  main .method-controls {
+    background: none;
+  }
+}
+
+/***********************************************
+ * Description lists
+ ***********************************************/
+
+main dt {
+  margin-bottom: 0; /* override rdoc 6.8 */
+  float: unset;     /* override rdoc 6.8 */
+  line-height: 1.5; /* matches `main p` */
+}
+
+main dl.note-list dt {
+  margin-right: 1em;
+  float: left;
+}
+
+main dl.note-list dt:has(+ dt) {
+  margin-right: 0.25em;
+}
+
+main dl.note-list dt:has(+ dt)::after {
+  content: ', ';
+  font-weight: normal;
+}
+
+main dd {
+  margin: 0 0 1em 1em;
+}
+
+main dd p:first-child {
+  margin-top: 0;
 }

data/lib/net/imap/command_data.rb

@@ -3,6 +3,7 @@
 require "date"
 
 require_relative "errors"
+require_relative "data_lite"
 
 module Net
   class IMAP < Protocol
@@ -119,80 +120,85 @@ module Net
       put_string("\\" + symbol.to_s)
     end
 
-    class RawData # :nodoc:
+    CommandData = Data.define(:data) do # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+        raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
 
       def validate
       end
-
-      private
-
-      def initialize(data)
-        @data = data
-      end
     end
 
-    class Atom # :nodoc:
+    class RawData < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
-      end
-
-      def validate
-      end
-
-      private
-
-      def initialize(data)
-        @data = data
+        imap.__send__(:put_string, data)
       end
     end
 
-    class QuotedString # :nodoc:
+    class Atom < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_quoted_string, @data)
-      end
-
-      def validate
+        imap.__send__(:put_string, data)
       end
+    end
 
-      private
-
-      def initialize(data)
-        @data = data
+    class QuotedString < CommandData # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:send_quoted_string, data)
       end
     end
 
-    class Literal # :nodoc:
+    class Literal < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_literal, @data, tag)
+        imap.__send__(:send_literal, data, tag)
       end
+    end
 
-      def validate
+    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
 
-      private
+      def formatted = "%d:%d" % data.minmax
 
-      def initialize(data)
-        @data = data
+      def send_data(imap, tag)
+        imap.__send__(:put_string, formatted)
       end
     end
 
     # *DEPRECATED*.  Replaced by SequenceSet.
-    class MessageSet # :nodoc:
+    class MessageSet < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, format_internal(@data))
+        imap.__send__(:put_string, format_internal(data))
       end
 
       def validate
-        validate_internal(@data)
+        validate_internal(data)
       end
 
       private
 
-      def initialize(data)
-        @data = data
+      def initialize(data:)
+        super
         warn("DEPRECATED: #{MessageSet} should be replaced with #{SequenceSet}.",
              uplevel: 1, category: :deprecated)
         begin
@@ -246,22 +252,18 @@ module Net
       end
     end
 
-    class ClientID # :nodoc:
+    class ClientID < CommandData # :nodoc:
 
       def send_data(imap, tag)
-        imap.__send__(:send_data, format_internal(@data), tag)
+        imap.__send__(:send_data, format_internal(data), tag)
       end
 
       def validate
-        validate_internal(@data)
+        validate_internal(data)
       end
 
       private
 
-      def initialize(data)
-        @data = data
-      end
-
       def validate_internal(client_id)
         client_id.to_h.each do |k,v|
           unless StringFormatter.valid_string?(k)

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
         private_constant :Macros
 
@@ -26,34 +28,29 @@ 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
-        end
+        def self.safe(...) = Ractor.make_shareable nil.instance_eval(...).freeze
+        private_class_method :safe
 
-        def self.boolean(attr)
-          define_method :"#{attr}=" do |val| super !!val end
-          define_method :"#{attr}?" do send attr end
-        end
+        Types = Hash.new do |h, type| type => Proc | nil; 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

@@ -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
     #
@@ -129,8 +131,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 +172,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 +209,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
@@ -243,10 +264,44 @@ module Net
       #   present.  When capabilities are unknown, Net::IMAP will automatically
       #   send a +CAPABILITY+ command first before sending +LOGIN+.
       #
-      attr_accessor :enforce_logindisabled, type: [
+      attr_accessor :enforce_logindisabled, type: Enum[
         false, :when_capabilities_cached, true
       ]
 
+      # 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.  A _much_ lower value should be used with
+      # untrusted servers (for example, when connecting to a user-provided
+      # hostname).  When using a lower limit, message bodies should be fetched
+      # in chunks rather than all at once.
+      #
+      # <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.
+      #
+      # 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+).
       #
@@ -273,7 +328,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,
       ]
 
@@ -285,6 +340,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: Enum[
+        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.
@@ -364,37 +480,73 @@ module Net
         idle_response_timeout: 5,
         sasl_ir: true,
         enforce_logindisabled: true,
+        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
 
       @global = default.new
 
       version_defaults[:default] = Config[default.send(:defaults_hash)]
-      version_defaults[:current] = Config[:default]
 
-      version_defaults[0] = Config[:current].dup.update(
+      version_defaults[0r] = Config[:default].dup.update(
         sasl_ir: false,
         responses_without_block: :silence_deprecation_warning,
         enforce_logindisabled: 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.4] = Config[0.3].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.5] = Config[:current]
+      version_defaults[0.5r] = Config[0.4r].dup.update(
+        enforce_logindisabled: true,
+        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[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[:next] = Config[0.6]
-      version_defaults[:future] = Config[:next]
+
+      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 in 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[current + 0.2r]
 
       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