net-imap 0.4.22 → 0.6.3

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
@@ -75,7 +76,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 +110,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
     #
@@ -139,15 +142,7 @@ module Net
       #     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 = 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)
-      }
+      def self.version_defaults; AttrVersionDefaults.version_defaults end
 
       # :call-seq:
       #  Net::IMAP::Config[number] -> versioned config
@@ -187,6 +182,7 @@ module Net
       include AttrAccessors
       include AttrInheritance
       include AttrTypeCoercion
+      extend  AttrVersionDefaults
 
       # The debug mode (boolean).  The default value is +false+.
       #
@@ -198,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
@@ -216,7 +212,7 @@ module Net
       # 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.
@@ -224,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
@@ -238,18 +234,61 @@ module Net
       #   Do not use +SASL-IR+, even when it is supported by the server and the
       #   mechanism.
       #
+      # [+:when_capabilities_cached+]
+      #   Use +SASL-IR+ when Net::IMAP#capabilities_cached? is +true+ and it is
+      #   supported by the server and the mechanism, but do not send a
+      #   +CAPABILITY+ command to discover the server capabilities.
+      #
+      #   <em>(+:when_capabilities_cached+ option was added by +v0.6.0+)</em>
+      #
       # [+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: Enum[
+        false, :when_capabilities_cached, true
+      ], defaults: {
+        0.0r => false,
+        0.4r => true,
+      }
+
+      # :stopdoc:
+      alias sasl_ir? sasl_ir
+      # :startdoc:
+
+      # Controls the behavior of Net::IMAP#login when the +LOGINDISABLED+
+      # capability is present.  When enforced, Net::IMAP will raise a
+      # LoginDisabledError when that capability is present.
+      #
+      # <em>(Support for +LOGINDISABLED+ was added in +v0.5.0+.)</em>
+      #
+      # ==== Valid options
+      #
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Send the +LOGIN+ command without checking for +LOGINDISABLED+.
+      #
+      # [+:when_capabilities_cached+]
+      #   Enforce the requirement when Net::IMAP#capabilities_cached? is true,
+      #   but do not send a +CAPABILITY+ command to discover the capabilities.
+      #
+      # [+true+ <em>(default since +v0.5+)</em>]
+      #   Only send the +LOGIN+ command if the +LOGINDISABLED+ capability is not
+      #   present.  When capabilities are unknown, Net::IMAP will automatically
+      #   send a +CAPABILITY+ command first before sending +LOGIN+.
+      #
+      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.  To use a lower limit, fetch message bodies in
-      # chunks rather than all at once.  A _much_ lower value should be used
-      # with untrusted servers (for example, when connecting to a user-provided
-      # hostname).
+      # 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
@@ -260,7 +299,6 @@ module Net
       # response: max_response_size minus the bytes that have already been read.
       # When the limit is reached, or reading a +literal+ _would_ go over the
       # limit, ResponseTooLargeError is raised and the connection is closed.
-      # See also #socket_read_limit.
       #
       # Note that changes will not take effect immediately, because the receiver
       # thread may already be waiting for the next response using the previous
@@ -275,7 +313,10 @@ module Net
       #
       # * original: +nil+ <em>(no limit)</em>
       # * +0.5+: 512 MiB
-      attr_accessor :max_response_size, type: Integer?
+      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+).
@@ -305,7 +346,11 @@ module Net
       # Note: #responses_without_args is an alias for #responses_without_block.
       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:
@@ -315,66 +360,69 @@ 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.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option only affects deprecation warnings.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # AppendUIDData and CopyUIDData are _mostly_ backward-compatible with
-      # UIDPlusData.  Most applications should be able to upgrade with little
-      # or no changes.
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>(Config option added in +v0.4.19+ and +v0.5.6+.)</em>
+      # Config option added in +v0.4.19+ and +v0.5.6+.
       #
-      # <em>UIDPlusData will be removed in +v0.6+ and this config setting will
-      # be ignored.</em>
+      # <em>UIDPlusData removed in +v0.6.0+.</em>
       #
-      # ==== Valid options
+      # ==== Options
       #
       # [+true+ <em>(original default)</em>]
-      #    ResponseParser only uses UIDPlusData.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
       # [+: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.
+      #    <em>Since v0.6.0:</em>
+      #    Prints a deprecation warning when parsing +COPYUID+ or +APPENDUID+.
       #
-      # [+false+ <em>(planned default for +v0.6+)</em>]
-      #    ResponseParser _only_ uses AppendUIDData and CopyUIDData.
+      # [+false+ <em>(default since +v0.6.0+)</em>]
+      #    This is the only supported option <em>(since v0.6.0)</em>.
       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
-      # parser_use_deprecated_uidplus_data is not +false+.
+      # **NOTE:** <em>+UIDPlusData+ has been removed since +v0.6.0+, and this
+      # config option is ignored.
+      # This config option will be **removed** in +v0.7.0+.</em>
       #
-      # <em>(Parser support for +UIDPLUS+ added in +v0.3.2+.)</em>
+      # ResponseParser always returns CopyUIDData for +COPYUID+ response codes,
+      # and AppendUIDData for +APPENDUID+ response codes.  Previously, this
+      # option determined when UIDPlusData would be returned instead.
       #
-      # <em>Support for limiting UIDPlusData to a maximum size was added in
-      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.</em>
+      # Parser support for +UIDPLUS+ added in +v0.3.2+.
       #
-      # <em>UIDPlusData will be removed in +v0.6+.</em>
+      # Support for limiting UIDPlusData to a maximum size was added in
+      # +v0.3.8+, +v0.4.19+, and +v0.5.6+.
       #
-      # ==== Versioned Defaults
+      # <em>UIDPlusData was removed in +v0.6.0+.</em>
       #
-      # 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.
+      # ==== Versioned Defaults
       #
       # * +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
+      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+.
       #
@@ -443,82 +491,150 @@ module Net
       # Returns all config attributes in a hash.
       def to_h; data.members.to_h { [_1, send(_1)] } end
 
+      # Returns a string representation of overriden config attributes and the
+      # inheritance chain.
+      #
+      # Attributes overridden by ancestors are also inspected, recursively.
+      # Attributes that are inherited from default configs are not shown (see
+      # Config@Versioned+defaults and Config@Named+defaults).
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     Net::IMAP::Config.new(0.4)
+      #       .new(open_timeout: 10, enforce_logindisabled: true)
+      #       .inspect
+      #     #=> "#<Net::IMAP::Config:0x0000745871125410 open_timeout=10 enforce_logindisabled=true
+      #     #      inherits from Net::IMAP::Config[0.4]
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Non-default attributes are listed after the ancestor config from which
+      # they are inherited.
+      #
+      #     # (Line breaks have been added to the example output for legibility.)
+      #
+      #     config = Net::IMAP::Config.global
+      #       .new(open_timeout: 10, idle_response_timeout: 2)
+      #       .new(enforce_logindisabled: :when_capabilities_cached, sasl_ir: false)
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      #     Net::IMAP.debug = true
+      #     config.inspect
+      #     #=> "#<Net::IMAP::Config:0x00007ce2a1e20e40 sasl_ir=false enforce_logindisabled=:when_capabilities_cached
+      #     #      inherits from Net::IMAP::Config:0x00007ce2a1e20f80 open_timeout=10 idle_response_timeout=2
+      #     #      inherits from Net::IMAP::Config.global debug=true
+      #     #      inherits from Net::IMAP::Config.default>"
+      #
+      # Use +pp+ (see #pretty_print) to inspect _all_ config attributes,
+      # including default values.
+      #
+      # Use #to_h to inspect all config attributes ignoring inheritance.
+      def inspect;
+        "#<#{inspect_recursive}>"
+      end
+      alias to_s inspect
+
+      # Used by PP[https://docs.ruby-lang.org/en/master/PP.html] to create a
+      # string representation of all config attributes and the inheritance
+      # chain.  Inherited attributes are listed with the ancestor config from
+      # which they are inherited.
+      #
+      #     pp Config.new[0.4].new(open_timeout: 10, idle_response_timeout: 10)
+      #     # #<Net::IMAP::Config:0x0000745871125410
+      #     #   open_timeout=10
+      #     #   idle_response_timeout=10
+      #     #   inherits from Net::IMAP::Config[0.4]
+      #     #     responses_without_block=:silence_deprecation_warning
+      #     #     max_response_size=nil
+      #     #     sasl_ir=true
+      #     #     enforce_logindisabled=false
+      #     #     parser_use_deprecated_uidplus_data=true
+      #     #     parser_max_deprecated_uidplus_data_size=1000
+      #     #     inherits from Net::IMAP::Config.global
+      #     #       inherits from Net::IMAP::Config.default
+      #     #         debug=false>
+      #
+      # Related: #inspect, #to_h.
+      def pretty_print(pp)
+        pp.group(2, "#<", ">") do
+          pretty_print_recursive(pp)
+        end
+      end
+
+      # :stopdoc:
+
       protected
 
-      def defaults_hash
-        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
+      def named_default?
+        equal?(Config.default) ||
+          AttrVersionDefaults::VERSIONS.any? { equal? Config[_1] }
       end
 
-      @default = new(
-        debug: false,
-        open_timeout: 30,
-        idle_response_timeout: 5,
-        sasl_ir: true,
-        max_response_size: nil,
-        responses_without_block: :silence_deprecation_warning,
-        parser_use_deprecated_uidplus_data: true,
-        parser_max_deprecated_uidplus_data_size: 1000,
-      ).freeze
-
-      @global = default.new
-
-      version_defaults[:default] = Config[default.send(:defaults_hash)]
-
-      version_defaults[0r] = Config[:default].dup.update(
-        sasl_ir: false,
-        max_response_size: nil,
-        parser_use_deprecated_uidplus_data: true,
-        parser_max_deprecated_uidplus_data_size: 10_000,
-      ).freeze
-      version_defaults[0.0r] = Config[0r]
-      version_defaults[0.1r] = Config[0r]
-      version_defaults[0.2r] = Config[0r]
-      version_defaults[0.3r] = Config[0r]
-
-      version_defaults[0.4r] = Config[0.3r].dup.update(
-        sasl_ir: true,
-        parser_max_deprecated_uidplus_data_size: 1000,
-      ).freeze
-
-      version_defaults[0.5r] = Config[0.4r].dup.update(
-        max_response_size: 512 << 20, # 512 MiB
-        responses_without_block: :warn,
-        parser_use_deprecated_uidplus_data: :up_to_max_size,
-        parser_max_deprecated_uidplus_data_size: 100,
-      ).freeze
-
-      version_defaults[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[0.7r] = Config[0.6r].dup.update(
-      ).freeze
-
-      # Safe conversions one way only:
-      #   0.6r.to_f == 0.6  # => true
-      #   0.6 .to_r == 0.6r # => false
-      version_defaults.to_a.each do |k, v|
-        next unless k.is_a? Rational
-        version_defaults[k.to_f] = v
+      def name
+        if    equal? Config.default   then "#{Config}.default"
+        elsif equal? Config.global    then "#{Config}.global"
+        elsif equal? Config[0.0r]     then "#{Config}[:original]"
+        elsif (v = AttrVersionDefaults::VERSIONS.find { equal? Config[_1] })
+          "%s[%0.1f]" % [Config, v]
+        else
+          Kernel.instance_method(:to_s).bind_call(self).delete("<#>")
+        end
       end
 
-      current = VERSION.to_r
-      version_defaults[:original] = Config[0]
-      version_defaults[:current]  = Config[current]
-      version_defaults[:next]     = Config[current + 0.1r]
+      def inspect_recursive(attrs = AttrAccessors.struct.members)
+        strings  = [name]
+        assigned = assigned_attrs_hash(attrs)
+        strings.concat assigned.map { "%s=%p" % _1 }
+        if parent
+          if parent.equal?(Config.default)
+            inherited_overrides = []
+          elsif parent
+            inherited_overrides = attrs - assigned.keys
+            inherited_overrides &= DEFAULT_TO_INHERIT if parent.named_default?
+          end
+          strings << "inherits from #{parent.inspect_recursive(inherited_overrides)}"
+        end
+        strings.join " "
+      end
 
-      version_defaults[:future]   = Config[0.7r]
+      def pretty_print_recursive(pp, attrs = AttrAccessors.struct.members)
+        pp.text name
+        assigned = assigned_attrs_hash(attrs)
+        pp.breakable
+        pp.seplist(assigned, ->{pp.breakable}) do |key, val|
+          pp.text key.to_s
+          pp.text "="
+          pp.pp val
+        end
+        if parent
+          pp.breakable if assigned.any?
+          pp.nest(2) do
+            pp.text "inherits from "
+            parent.pretty_print_recursive(pp, attrs - assigned.keys)
+          end
+        elsif assigned.empty?
+          pp.text "(overridden)"
+        end
+      end
 
-      version_defaults.freeze
+      def assigned_attrs_hash(attrs)
+        own_attrs = attrs.reject { inherited?(_1) }
+        own_attrs.to_h { [_1, data[_1]] }
+      end
 
-      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
-              ]
+      def defaults_hash
+        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
       end
+
+      Struct   = AttrAccessors.struct
+      @default = AttrVersionDefaults.compile_default!
+      @global  = default.new
+      AttrVersionDefaults.compile_version_defaults!
+
     end
   end
 end

data/lib/net/imap/connection_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class ConnectionState < 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