net-imap 0.5.6 → 0.5.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdbdda0ed73da899ec338f66022a16104562d3701c568b0a6d4897270a608ac5
-  data.tar.gz: b6a7ec70776b32f8eb57d01a0869503eb5d76f719ac091eb92e0206608e936e9
+  metadata.gz: 1da7db7eb1545ee4a81555ef7f46c65e82e48ad8e4b64a4112881698df4ebc5d
+  data.tar.gz: b3a668019d4d36c2a9cfc8d41c5e65d1054a630dc2c5cb8ea7050fbaaf264f6b
 SHA512:
-  metadata.gz: 381bf2428719ed8decb5d241fda0e19f28031dd4a77980b3717bb29c37bed1c927f00e5b57862e209ecf24b2e9b38c01088d6e1a90fc4b4cc026cdd9e6611100
-  data.tar.gz: 513c6a77d46b6d2cf67aea4511023acc76c69940e3b1a0d0eae7223b53ff63bc8e6e009f51fef826b09f76f6ad1d92e84243e8457f59d3912db7e74bf69d3d1b
+  metadata.gz: 731921ff022993cd51ada037fa764067d4da07e6a8119545f7b225354b32f19c3936a8c807c3badd3664dde424c924842ecb0ac9851d74bb9bf568ebbbb800e6
+  data.tar.gz: da993296fd57d59c56c483920d901c9b6b44329c0bb5812c495de2024f01e449b0117be5900013875902ff1101ac0dfeaf177f407ea34e69ae210bd87f91e86a

data/Gemfile

@@ -4,7 +4,7 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "digest"
+# gem "digest"  # not included as a workaround for #576
 gem "strscan"
 gem "base64"
 
@@ -14,10 +14,12 @@ gem "rdoc"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
+gem "benchmark", require: false
 gem "benchmark-driver", require: false
+gem "vernier", require: false, platform: :mri
 
 group :test do
-  gem "simplecov",        require: false
-  gem "simplecov-html",   require: false
-  gem "simplecov-json",   require: false
+  gem "simplecov",        require: false, platforms: %i[mri windows]
+  gem "simplecov-html",   require: false, platforms: %i[mri windows]
+  gem "simplecov-json",   require: false, platforms: %i[mri windows]
 end

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,45 @@ 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]
+        if defined?(Ractor.shareable_proc)
+          def self.safe(&b)
+            case obj = b.call
+            when Proc
+              Ractor.shareable_proc(&obj)
+            else
+              Ractor.make_shareable obj
+            end
           end
+        elsif defined?(Ractor.make_shareable)
+          def self.safe(&b)
+            obj = nil.instance_eval(&b).freeze
+            Ractor.make_shareable obj
+          end
+        else
+          def self.safe(&b) nil.instance_eval(&b).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
-        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
-          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
+        NilOrInteger = safe{->val { Integer val unless val.nil? }}
+
+        Enum = ->(*enum) {
+          safe_enum = safe{enum}
+          expected = -"one of #{safe_enum.map(&:inspect).join(", ")}"
+          safe{->val {
+            return val if safe_enum.include?(val)
+            raise ArgumentError, "expected %s, got %p" % [expected, val]
+          }}
+        }
 
       end
     end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +defaults+ parameter to +attr_accessor+, which is used to compile
+      # Config.version_defaults.
+      module AttrVersionDefaults
+        # The <tt>x.y</tt> part of Net::IMAP::VERSION, as a Rational number.
+        CURRENT_VERSION = VERSION.to_r
+
+        # The config version used for <tt>Config[:next]</tt>.
+        NEXT_VERSION    = CURRENT_VERSION + 0.1r
+
+        # The config version used for <tt>Config[:future]</tt>.
+        FUTURE_VERSION  = 1.0r
+
+        VERSIONS = ((0.0r..FUTURE_VERSION) % 0.1r).to_a.freeze
+
+        # See Config.version_defaults.
+        singleton_class.attr_accessor :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)
+        }
+
+        # :stopdoc: internal APIs only
+
+        def attr_accessor(name, defaults: nil, default: (unset = true), **kw)
+          unless unset
+            version  = DEFAULT_TO_INHERIT.include?(name) ? nil : 0.0r
+            defaults = { version => default }
+          end
+          defaults&.each_pair do |version, default|
+            AttrVersionDefaults.version_defaults[version] ||= {}
+            AttrVersionDefaults.version_defaults[version][name] = default
+          end
+          super(name, **kw)
+        end
+
+        def self.compile_default!
+          raise "Config.default already compiled" if Config.default
+          default = VERSIONS.select { _1 <= CURRENT_VERSION }
+            .filter_map { version_defaults[_1] }
+            .prepend(version_defaults.delete(nil))
+            .inject(&:merge)
+          Config.new(**default).freeze
+        end
+
+        def self.compile_version_defaults!
+          # Temporarily assign Config.default, enabling #load_defaults(:default)
+          version_defaults[:default] = Config.default
+          # Use #load_defaults so some attributes are inherited from global.
+          version_defaults[:default] = Config.new.load_defaults(:default).freeze
+          version_defaults[0.0r]     = Config[version_defaults.fetch(0.0r)]
+
+          VERSIONS.each_cons(2) do |prior, version|
+            updates = version_defaults[version]
+            version_defaults[version] = version_defaults[prior]
+              .then { updates ? _1.dup.update(**updates).freeze : _1 }
+          end
+
+          # 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
+
+          version_defaults[:original] = Config[0.0r]
+          version_defaults[:current]  = Config[CURRENT_VERSION]
+          version_defaults[:next]     = Config[NEXT_VERSION]
+          version_defaults[:future]   = Config[FUTURE_VERSION]
+
+          version_defaults.freeze
+        end
+
+      end
+    end
+  end
+end

data/lib/net/imap/config.rb

@@ -3,6 +3,7 @@
 require_relative "config/attr_accessors"
 require_relative "config/attr_inheritance"
 require_relative "config/attr_type_coercion"
+require_relative "config/attr_version_defaults"
 
 module Net
   class IMAP
@@ -131,8 +132,17 @@ module Net
       def self.global; @global if defined?(@global) end
 
       # A hash of hard-coded configurations, indexed by version number or name.
-      def self.version_defaults; @version_defaults end
-      @version_defaults = {}
+      # 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; AttrVersionDefaults.version_defaults end
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -155,24 +165,24 @@ 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
 
       include AttrAccessors
       include AttrInheritance
       include AttrTypeCoercion
+      extend  AttrVersionDefaults
 
       # The debug mode (boolean).  The default value is +false+.
       #
@@ -184,7 +194,7 @@ module Net
       #
       # *NOTE:* Versioned default configs inherit #debug from Config.global, and
       # #load_defaults will not override #debug.
-      attr_accessor :debug, type: :boolean
+      attr_accessor :debug, type: :boolean, default: false
 
       # method: debug?
       # :call-seq: debug? -> boolean
@@ -193,13 +203,16 @@ 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
+      attr_accessor :open_timeout, type: Integer, default: 30
 
       # Seconds to wait until an IDLE response is received, after
       # the client asks to leave the IDLE state.
@@ -207,7 +220,7 @@ module Net
       # See Net::IMAP#idle and Net::IMAP#idle_done.
       #
       # The default value is +5+ seconds.
-      attr_accessor :idle_response_timeout, type: Integer
+      attr_accessor :idle_response_timeout, type: Integer, default: 5
 
       # Whether to use the +SASL-IR+ extension when the server and \SASL
       # mechanism both support it.  Can be overridden by the +sasl_ir+ keyword
@@ -223,7 +236,10 @@ module Net
       #
       # [+true+ <em>(default since +v0.4+)</em>]
       #   Use +SASL-IR+ when it is supported by the server and the mechanism.
-      attr_accessor :sasl_ir, type: :boolean
+      attr_accessor :sasl_ir, type: :boolean, defaults: {
+        0.0r => false,
+        0.4r => true,
+      }
 
       # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
       # capability is present.  When enforced, Net::IMAP will raise a
@@ -245,9 +261,49 @@ 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
-      ]
+      ], defaults: {
+        0.0r => false,
+        0.5r => 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?, defaults: {
+        0.0r => nil,
+        0.5r => 512 << 20, # 512 MiB
+      }
 
       # Controls the behavior of Net::IMAP#responses when called without any
       # arguments (+type+ or +block+).
@@ -275,9 +331,13 @@ 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,
-      ]
+      ], defaults: {
+        0.0r => :silence_deprecation_warning,
+        0.5r => :warn,
+        0.6r => :frozen_dup,
+      }
 
       alias responses_without_args  responses_without_block  # :nodoc:
       alias responses_without_args= responses_without_block= # :nodoc:
@@ -320,9 +380,13 @@ 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
-      ]
+      ], defaults: {
+        0.0r => true,
+        0.5r => :up_to_max_size,
+        0.6r => false,
+      }
 
       # The maximum +uid-set+ size that ResponseParser will parse into
       # deprecated UIDPlusData.  This limit only applies when
@@ -346,7 +410,13 @@ module Net
       # * +0.5+: <tt>100</tt>
       # * +0.6+: <tt>0</tt>
       #
-      attr_accessor :parser_max_deprecated_uidplus_data_size, type: Integer
+      attr_accessor :parser_max_deprecated_uidplus_data_size, type: Integer,
+        defaults: {
+          0.0r => 10_000,
+          0.4r =>  1_000,
+          0.5r =>    100,
+          0.6r =>      0,
+        }
 
       # Creates a new config object and initialize its attribute with +attrs+.
       #
@@ -421,50 +491,10 @@ module Net
         to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end
 
-      @default = new(
-        debug: false,
-        open_timeout: 30,
-        idle_response_timeout: 5,
-        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
-
-      version_defaults[:default] = Config[default.send(:defaults_hash)]
-      version_defaults[:current] = Config[:default]
-
-      version_defaults[0] = Config[:current].dup.update(
-        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]
-      version_defaults[0.2] = Config[0]
-      version_defaults[0.3] = Config[0]
-
-      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]
+      @default = AttrVersionDefaults.compile_default!
+      @global  = default.new
+      AttrVersionDefaults.compile_version_defaults!
 
-      version_defaults.freeze
     end
   end
 end

data/lib/net/imap/connection_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class ConnectionState < Net::IMAP::Data # :nodoc:
+      def self.define(symbol, *attrs)
+        symbol => Symbol
+        state = super(*attrs)
+        state.const_set :NAME, symbol
+        state
+      end
+
+      def symbol; self.class::NAME      end
+      def name;   self.class::NAME.name end
+      alias to_sym symbol
+
+      def deconstruct; [symbol, *super] end
+
+      def deconstruct_keys(names)
+        hash = super
+        hash[:symbol] = symbol if names.nil? || names.include?(:symbol)
+        hash[:name]   = name   if names.nil? || names.include?(:name)
+        hash
+      end
+
+      def to_h(&block)
+        hash = deconstruct_keys(nil)
+        block ? hash.to_h(&block) : hash
+      end
+
+      def not_authenticated?; to_sym == :not_authenticated end
+      def authenticated?;     to_sym == :authenticated     end
+      def selected?;          to_sym == :selected          end
+      def logout?;            to_sym == :logout            end
+
+      NotAuthenticated = define(:not_authenticated)
+      Authenticated    = define(:authenticated)
+      Selected         = define(:selected)
+      Logout           = define(:logout)
+
+      class << self
+        undef :define
+      end
+      freeze
+    end
+
+  end
+end

data/lib/net/imap/errors.rb

@@ -17,6 +17,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/esearch_result.rb

@@ -39,12 +39,49 @@ module Net
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
       # 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.
+      # returned no results or because neither +ALL+ or +PARTIAL+ were 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 || partial&.to_a || [] end
+      #
+      # Related: #each, #to_sequence_set, #all, #partial
+      def to_a; to_sequence_set.numbers end
+
+      # :call-seq: to_sequence_set -> SequenceSet or nil
+      #
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_sequence_set+ returns that sequence set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_sequence_set returns
+      # SequenceSet.empty.
+      #
+      # Note that SearchResult also implements +to_sequence_set+, so it can be
+      # used without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #each, #to_a, #all, #partial
+      def to_sequence_set
+        all || partial&.to_sequence_set || SequenceSet.empty
+      end
+
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +each+ yields each integer in the set.
+      #
+      # 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, #each does not yield.
+      #
+      # Note that SearchResult also implements +#each+, so it can be used
+      # without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #to_sequence_set, #to_a, #all, #partial
+      def each(&)
+        return to_enum(__callee__) unless block_given?
+        to_sequence_set.each_number(&)
+        self
+      end
 
       ##
       # attr_reader: tag
@@ -161,6 +198,8 @@ module Net
         #
         # See also: ESearchResult#to_a.
         def to_a; results&.numbers || [] end
+
+        alias to_sequence_set results
       end
 
       # :call-seq: partial -> PartialResult or nil

data/lib/net/imap/flags.rb

@@ -173,7 +173,7 @@ module Net
     SUBSCRIBED = :Subscribed
 
     # The mailbox is a remote mailbox.
-    REMOTE = :Remove
+    REMOTE = :Remote
 
     # Alias for NO_INFERIORS, to match the \IMAP spelling.
     NOINFERIORS   = NO_INFERIORS

data/lib/net/imap/response_data.rb

@@ -6,7 +6,6 @@ module Net
     autoload :FetchData,        "#{__dir__}/fetch_data"
     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"