net-imap 0.4.12 → 0.4.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5147af8d1017e772136634ea2144c33a1666a00a25d03de20a6d89f9b026ecc
-  data.tar.gz: 66a41c1fcfc932da451f65074ae6659d872b85aeeef831208cf47178f944cd08
+  metadata.gz: 06be993e038a4432ec954b11701ce86f946c456f9125d2b539e6c21d05e728ab
+  data.tar.gz: 7807fb77537a843e9d9a2ad0ad892dc3e75af3a734f2c4c68a1e2cbae4d34ef1
 SHA512:
-  metadata.gz: 67a5545d46acd17051097ad3e10304817980fad7621ca0225c614f8bd49d62365d9b9d3305fa1ac3fbebd63bd1ba2155cb5a94d448ca6a6763655dd31cdb22a2
-  data.tar.gz: dbc107f94925486cbc3eb28a26c45560fce568f3836d65127628599fd7a117046d5cc0225f1999b387802316b781bce367da5b660da79200c7e576515669ca70
+  metadata.gz: 182edade4a45d1c6f4772332f2f9cd4704827895770764202aa843bfbb754defff11a8037c1955e352642201c57cea850ea51aa8e4fe6c1761b36c78562b1c5b
+  data.tar.gz: 2fff884a15a87ae7cb4a5ac422f743b5accd1ea98b34bf994cbb18238577cc259a1a672a04e5dac14864ad61bdafd90c43c160ede8ba369246fd3bb265e5cff2

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

@@ -0,0 +1,75 @@
+# 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.
+      #
+      # +attr_accessor+ values are stored in a struct rather than ivars, making
+      # it simpler to ensure that all config objects share a single object
+      # shape.  This also simplifies iteration over all defined attributes.
+      module AttrAccessors
+        module Macros # :nodoc: internal API
+          def attr_accessor(name) AttrAccessors.attr_accessor(name) end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        extend Forwardable
+
+        def self.attr_accessor(name) # :nodoc: internal API
+          name = name.to_sym
+          def_delegators :data, name, :"#{name}="
+        end
+
+        def self.attributes
+          instance_methods.grep(/=\z/).map { _1.to_s.delete_suffix("=").to_sym }
+        end
+        private_class_method :attributes
+
+        def self.struct # :nodoc: internal API
+          unless defined?(self::Struct)
+            const_set :Struct, Struct.new(*attributes)
+          end
+          self::Struct
+        end
+
+        def initialize # :notnew:
+          super()
+          @data = AttrAccessors.struct.new
+        end
+
+        # Freezes the internal attributes struct, in addition to +self+.
+        def freeze
+          data.freeze
+          super
+        end
+
+        protected
+
+        attr_reader :data # :nodoc: internal API
+
+        private
+
+        def initialize_clone(other)
+          super
+          @data = other.data.clone
+        end
+
+        def initialize_dup(other)
+          super
+          @data = other.data.dup
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* The public methods on this module are part of the stable
+      #   public API of Net::IMAP::Config.  But the module itself is an internal
+      #   implementation detail, with no guarantee of backward compatibility.
+      #
+      # +attr_accessor+ methods will delegate to their #parent when the local
+      # value does not contain an override.  Inheritance forms a singly linked
+      # list, so lookup will be <tt>O(n)</tt> on the number of ancestors.  In
+      # practice, the ancestor chain is not expected to be long.  Without
+      # customization, it is only three deep:
+      # >>>
+      #     IMAP#config → Config.global → Config.default
+      #
+      # When creating a client with the +config+ keyword, for example to use
+      # the appropriate defaults for an application or a library while still
+      # relying on global for configuration of +debug+ or +logger+, most likely
+      # the ancestor chain is still only four deep:
+      # >>>
+      #     IMAP#config → alternate defaults → Config.global → Config.default
+      module AttrInheritance
+        INHERITED = Module.new.freeze
+        private_constant :INHERITED
+
+        module Macros # :nodoc: internal API
+          def attr_accessor(name) super; AttrInheritance.attr_accessor(name) end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        def self.attr_accessor(name) # :nodoc: internal API
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}; (val = super) == INHERITED ? parent&.#{name} : val end
+          RUBY
+        end
+
+        # The parent Config object
+        attr_reader :parent
+
+        def initialize(parent = nil) # :notnew:
+          super()
+          @parent = Config[parent]
+          reset
+        end
+
+        # Creates a new config, which inherits from +self+.
+        def new(**attrs) self.class.new(self, **attrs) end
+
+        # Returns +true+ if +attr+ is inherited from #parent and not overridden
+        # by this config.
+        def inherited?(attr) data[attr] == INHERITED end
+
+        # :call-seq:
+        #   reset -> self
+        #   reset(attr) -> attribute value
+        #
+        # Resets an +attr+ to inherit from the #parent config.
+        #
+        # When +attr+ is nil or not given, all attributes are reset.
+        def reset(attr = nil)
+          if attr.nil?
+            data.members.each do |attr| data[attr] = INHERITED end
+            self
+          elsif inherited?(attr)
+            nil
+          else
+            old, data[attr] = data[attr], INHERITED
+            old
+          end
+        end
+
+        private
+
+        def initialize_copy(other)
+          super
+          @parent ||= other # only default has nil parent
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +type+ keyword parameter to +attr_accessor+, to enforce that
+      # config attributes have valid types, for example: boolean, numeric,
+      # enumeration, non-nullable, etc.
+      module AttrTypeCoercion
+        # :stopdoc: internal APIs only
+
+        module Macros # :nodoc: internal API
+          def attr_accessor(attr, type: nil)
+            super(attr)
+            AttrTypeCoercion.attr_accessor(attr, type: type)
+          end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        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.boolean(attr)
+          define_method :"#{attr}=" do |val| super !!val end
+          define_method :"#{attr}?" do send attr end
+        end
+
+        def self.integer(attr)
+          define_method :"#{attr}=" do |val| super Integer val end
+        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
+
+      end
+    end
+  end
+end

data/lib/net/imap/config.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require_relative "config/attr_accessors"
+require_relative "config/attr_inheritance"
+require_relative "config/attr_type_coercion"
+
+module Net
+  class IMAP
+
+    # Net::IMAP::Config stores configuration options for Net::IMAP clients.
+    # The global configuration can be seen at either Net::IMAP.config or
+    # Net::IMAP::Config.global, and the client-specific configuration can be
+    # seen at Net::IMAP#config.
+    #
+    # When creating a new client, all unhandled keyword arguments to
+    # Net::IMAP.new are delegated to Config.new.  Every client has its own
+    # config.
+    #
+    #   debug_client = Net::IMAP.new(hostname, debug: true)
+    #   quiet_client = Net::IMAP.new(hostname, debug: false)
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    # == Inheritance
+    #
+    # Configs have a parent[rdoc-ref:Config::AttrInheritance#parent] config, and
+    # any attributes which have not been set locally will inherit the parent's
+    # value.  Every client creates its own specific config.  By default, client
+    # configs inherit from Config.global.
+    #
+    #   plain_client = Net::IMAP.new(hostname)
+    #   debug_client = Net::IMAP.new(hostname, debug: true)
+    #   quiet_client = Net::IMAP.new(hostname, debug: false)
+    #
+    #   plain_client.config.inherited?(:debug)  # => true
+    #   debug_client.config.inherited?(:debug)  # => false
+    #   quiet_client.config.inherited?(:debug)  # => false
+    #
+    #   plain_client.config.debug?  # => false
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    #   # Net::IMAP.debug is delegated to Net::IMAP::Config.global.debug
+    #   Net::IMAP.debug = true
+    #   plain_client.config.debug?  # => true
+    #   debug_client.config.debug?  # => true
+    #   quiet_client.config.debug?  # => false
+    #
+    #   Net::IMAP.debug = false
+    #   plain_client.config.debug = true
+    #   plain_client.config.inherited?(:debug)  # => false
+    #   plain_client.config.debug?  # => true
+    #   plain_client.config.reset(:debug)
+    #   plain_client.config.inherited?(:debug)  # => true
+    #   plain_client.config.debug?  # => false
+    #
+    # == Versioned defaults
+    #
+    # The effective default configuration for a specific +x.y+ version of
+    # +net-imap+ can be loaded with the +config+ keyword argument to
+    # Net::IMAP.new.  Requesting default configurations for previous versions
+    # enables extra backward compatibility with those versions:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.3)
+    #   client.config.sasl_ir                  # => false
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.5)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :warn
+    #
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :raise
+    #
+    # The versioned default configs inherit certain specific config options from
+    # Config.global, for example #debug:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   Net::IMAP.debug = false
+    #   client.config.debug?  # => false
+    #
+    #   Net::IMAP.debug = true
+    #   client.config.debug?  # => true
+    #
+    # Use #load_defaults to globally behave like a specific version:
+    #   client = Net::IMAP.new(hostname)
+    #   client.config.sasl_ir              # => true
+    #   Net::IMAP.config.load_defaults 0.3
+    #   client.config.sasl_ir              # => false
+    #
+    # === Named defaults
+    # In addition to +x.y+ version numbers, the following aliases are supported:
+    #
+    # [+:default+]
+    #   An alias for +:current+.
+    #
+    #   >>>
+    #   *NOTE*: This is _not_ the same as Config.default.  It inherits some
+    #   attributes from Config.global, for example: #debug.
+    # [+:current+]
+    #   An alias for the current +x.y+ version's defaults.
+    # [+:next+]
+    #   The _planned_ config for the next +x.y+ version.
+    # [+:future+]
+    #   The _planned_ eventual config for some future +x.y+ version.
+    #
+    # For example, to raise exceptions for all current deprecations:
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.responses  # raises an ArgumentError
+    #
+    # == Thread Safety
+    #
+    # *NOTE:* Updates to config objects are not synchronized for thread-safety.
+    #
+    class Config
+      # Array of attribute names that are _not_ loaded by #load_defaults.
+      DEFAULT_TO_INHERIT = %i[debug].freeze
+      private_constant :DEFAULT_TO_INHERIT
+
+      # The default config, which is hardcoded and frozen.
+      def self.default; @default end
+
+      # The global config object.  Also available from Net::IMAP.config.
+      def self.global; @global if defined?(@global) end
+
+      # A hash of hard-coded configurations, indexed by version number.
+      def self.version_defaults; @version_defaults end
+      @version_defaults = {}
+
+      # :call-seq:
+      #  Net::IMAP::Config[number] -> versioned config
+      #  Net::IMAP::Config[symbol] -> named config
+      #  Net::IMAP::Config[hash]   -> new frozen config
+      #  Net::IMAP::Config[config] -> same config
+      #
+      # Given a version number, returns the default configuration for the target
+      # version.  See Config@Versioned+defaults.
+      #
+      # Given a version name, returns the default configuration for the target
+      # version.  See Config@Named+defaults.
+      #
+      # Given a Hash, creates a new _frozen_ config which inherits from
+      # Config.global.  Use Config.new for an unfrozen config.
+      #
+      # Given a config, returns that same config.
+      def self.[](config)
+        if    config.is_a?(Config)         then config
+        elsif config.nil? && global.nil?   then nil
+        elsif config.respond_to?(:to_hash) then new(global, **config).freeze
+        else
+          version_defaults.fetch(config) do
+            case config
+            when Numeric
+              raise RangeError, "unknown config version: %p" % [config]
+            when 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
+
+      # The debug mode (boolean)
+      #
+      # The default value is +false+.
+      attr_accessor :debug, type: :boolean
+
+      # method: debug?
+      # :call-seq: debug? -> boolean
+      #
+      # Alias for #debug
+
+      # Seconds to wait until a connection is opened.
+      #
+      # If the IMAP object cannot open a connection within this time,
+      # it raises a Net::OpenTimeout exception.
+      #
+      # See Net::IMAP.new.
+      #
+      # The default value is +30+ seconds.
+      attr_accessor :open_timeout, type: Integer
+
+      # Seconds to wait until an IDLE response is received, after
+      # the client asks to leave the IDLE state.
+      #
+      # See Net::IMAP#idle and Net::IMAP#idle_done.
+      #
+      # The default value is +5+ seconds.
+      attr_accessor :idle_response_timeout, type: Integer
+
+      # :markup: markdown
+      #
+      # Whether to use the +SASL-IR+ extension when the server and \SASL
+      # mechanism both support it.
+      #
+      # See Net::IMAP#authenticate.
+      #
+      # | Starting with version | The default value is                     |
+      # |-----------------------|------------------------------------------|
+      # | _original_            | +false+ <em>(extension unsupported)</em> |
+      # | v0.4                  | +true+  <em>(support added)</em>         |
+      attr_accessor :sasl_ir, type: :boolean
+
+      # :markup: markdown
+      #
+      # Controls the behavior of Net::IMAP#responses when called without a
+      # block.  Valid options are `:warn`, `:raise`, or
+      # `:silence_deprecation_warning`.
+      #
+      # | Starting with version   | The default value is           |
+      # |-------------------------|--------------------------------|
+      # | v0.4.13                 | +:silence_deprecation_warning+ |
+      # | v0.5 <em>(planned)</em> | +:warn+                        |
+      # | _eventually_            | +:raise+                       |
+      attr_accessor :responses_without_block, type: [
+        :silence_deprecation_warning, :warn, :raise,
+      ]
+
+      # Creates a new config object and initialize its attribute with +attrs+.
+      #
+      # If +parent+ is not given, the global config is used by default.
+      #
+      # If a block is given, the new config object is yielded to it.
+      def initialize(parent = Config.global, **attrs)
+        super(parent)
+        update(**attrs)
+        yield self if block_given?
+      end
+
+      # :call-seq: update(**attrs) -> self
+      #
+      # Assigns all of the provided +attrs+ to this config, and returns +self+.
+      #
+      # An ArgumentError is raised unless every key in +attrs+ matches an
+      # assignment method on Config.
+      #
+      # >>>
+      #   *NOTE:*  #update is not atomic.  If an exception is raised due to an
+      #   invalid attribute value, +attrs+ may be partially applied.
+      def update(**attrs)
+        unless (bad = attrs.keys.reject { respond_to?(:"#{_1}=") }).empty?
+          raise ArgumentError, "invalid config options: #{bad.join(", ")}"
+        end
+        attrs.each do send(:"#{_1}=", _2) end
+        self
+      end
+
+      # :call-seq:
+      #   with(**attrs) -> config
+      #   with(**attrs) {|config| } -> result
+      #
+      # Without a block, returns a new config which inherits from self.  With a
+      # block, yields the new config and returns the block's result.
+      #
+      # If no keyword arguments are given, an ArgumentError will be raised.
+      #
+      # If +self+ is frozen, the copy will also be frozen.
+      def with(**attrs)
+        attrs.empty? and
+          raise ArgumentError, "expected keyword arguments, none given"
+        copy = new(**attrs)
+        copy.freeze if frozen?
+        block_given? ? yield(copy) : copy
+      end
+
+      # :call-seq: load_defaults(version) -> self
+      #
+      # Resets the current config to behave like the versioned default
+      # configuration for +version+.  #parent will not be changed.
+      #
+      # Some config attributes default to inheriting from their #parent (which
+      # is usually Config.global) and are left unchanged, for example: #debug.
+      #
+      # See Config@Versioned+defaults and Config@Named+defaults.
+      def load_defaults(version)
+        [Numeric, Symbol, String].any? { _1 === version } or
+          raise ArgumentError, "expected number or symbol, got %p" % [version]
+        update(**Config[version].defaults_hash)
+      end
+
+      # :call-seq: to_h -> hash
+      #
+      # Returns all config attributes in a hash.
+      def to_h; data.members.to_h { [_1, send(_1)] } end
+
+      protected
+
+      def defaults_hash
+        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,
+        responses_without_block: :silence_deprecation_warning,
+      ).freeze
+
+      @global = default.new
+
+      version_defaults[0.4] = Config[default.send(:defaults_hash)]
+
+      version_defaults[0] = Config[0.4].dup.update(
+        sasl_ir: false,
+      ).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.5] = Config[0.4].dup.update(
+        responses_without_block: :warn,
+      ).freeze
+
+      version_defaults[:default] = Config[0.4]
+      version_defaults[:current] = Config[0.4]
+      version_defaults[:next]    = Config[0.5]
+
+      version_defaults[:future]  = Config[0.5].dup.update(
+        responses_without_block: :raise,
+      ).freeze
+
+      version_defaults.freeze
+    end
+  end
+end

data/lib/net/imap/deprecated_client_options.rb

@@ -16,8 +16,8 @@ module Net
       #
       # ==== Obsolete arguments
       #
-      # Using obsolete arguments does not a warning.  Obsolete arguments will be
-      # deprecated by a future release.
+      # Use of obsolete arguments does not print a warning.  Obsolete arguments
+      # will be deprecated by a future release.
       #
       # If a second positional argument is given and it is a hash (or is
       # convertible via +#to_hash+), it is converted to keyword arguments.

data/lib/net/imap/response_parser/parser_utils.rb

@@ -154,7 +154,7 @@ module Net
         end
 
         # To be used conditionally:
-        #   assert_no_lookahead if Net::IMAP.debug
+        #   assert_no_lookahead if config.debug?
         def assert_no_lookahead
           @token.nil? or
             parse_error("assertion failed: expected @token.nil?, actual %s: %p",
@@ -181,23 +181,23 @@ module Net
         end
 
         def peek_str?(str)
-          assert_no_lookahead if Net::IMAP.debug
+          assert_no_lookahead if config.debug?
           @str[@pos, str.length] == str
         end
 
         def peek_re(re)
-          assert_no_lookahead if Net::IMAP.debug
+          assert_no_lookahead if config.debug?
           re.match(@str, @pos)
         end
 
         def accept_re(re)
-          assert_no_lookahead if Net::IMAP.debug
+          assert_no_lookahead if config.debug?
           re.match(@str, @pos) and @pos = $~.end(0)
           $~
         end
 
         def match_re(re, name)
-          assert_no_lookahead if Net::IMAP.debug
+          assert_no_lookahead if config.debug?
           if re.match(@str, @pos)
             @pos = $~.end(0)
             $~
@@ -212,7 +212,7 @@ module Net
 
         def parse_error(fmt, *args)
           msg = format(fmt, *args)
-          if IMAP.debug
+          if config.debug?
             local_path = File.dirname(__dir__)
             tok = @token ? "%s: %p" % [@token.symbol, @token.value] : "nil"
             warn "%s %s: %s"        % [self.class, __method__, msg]

data/lib/net/imap/response_parser.rb

@@ -11,12 +11,15 @@ module Net
       include ParserUtils
       extend  ParserUtils::Generator
 
+      attr_reader :config
+
       # :call-seq: Net::IMAP::ResponseParser.new -> Net::IMAP::ResponseParser
-      def initialize
+      def initialize(config: Config.global)
         @str = nil
         @pos = nil
         @lex_state = nil
         @token = nil
+        @config = Config[config]
       end
 
       # :call-seq:

data/lib/net/imap.rb

@@ -717,7 +717,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.4.12"
+    VERSION = "0.4.14"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -735,14 +735,15 @@ module Net
       include SSL
     end
 
-    # Returns the debug mode.
-    def self.debug
-      return @@debug
-    end
+    # Returns the global Config object
+    def self.config; Config.global end
+
+    # Returns the global debug mode.
+    def self.debug; config.debug end
 
-    # Sets the debug mode.
+    # Sets the global debug mode.
     def self.debug=(val)
-      return @@debug = val
+      config.debug = val
     end
 
     # The default port for IMAP connections, port 143
@@ -764,13 +765,19 @@ module Net
     # Returns the initial greeting the server, an UntaggedResponse.
     attr_reader :greeting
 
+    # The client configuration.  See Net::IMAP::Config.
+    #
+    # By default, the client's local configuration inherits from the global
+    # Net::IMAP.config.
+    attr_reader :config
+
     # Seconds to wait until a connection is opened.
     # If the IMAP object cannot open a connection within this time,
     # it raises a Net::OpenTimeout exception. The default value is 30 seconds.
-    attr_reader :open_timeout
+    def open_timeout; config.open_timeout end
 
     # Seconds to wait until an IDLE response is received.
-    attr_reader :idle_response_timeout
+    def idle_response_timeout; config.idle_response_timeout end
 
     # The hostname this client connected to
     attr_reader :host
@@ -809,14 +816,40 @@ module Net
     #   If +ssl+ is a hash, it's passed to
     #   {OpenSSL::SSL::SSLContext#set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params];
     #   the keys are names of attribute assignment methods on
-    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].
+    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].  For example:
+    #
+    #   [{ca_file}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_file]]
+    #     The path to a file containing a PEM-format CA certificate.
+    #   [{ca_path}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_path]]
+    #     The path to a directory containing CA certificates in PEM format.
+    #   [{min_version}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-min_version-3D]]
+    #     Sets the lower bound on the supported SSL/TLS protocol version. Set to
+    #     an +OpenSSL+ constant such as +OpenSSL::SSL::TLS1_2_VERSION+,
+    #   [{verify_mode}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-verify_mode]]
+    #     SSL session verification mode.  Valid modes include
+    #     +OpenSSL::SSL::VERIFY_PEER+ and +OpenSSL::SSL::VERIFY_NONE+.
+    #
+    #   See {OpenSSL::SSL::SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html] for other valid SSL context params.
+    #
+    #   See DeprecatedClientOptions.new for deprecated SSL arguments.
     #
-    # [open_timeout]
-    #   Seconds to wait until a connection is opened
-    # [idle_response_timeout]
-    #   Seconds to wait until an IDLE response is received
+    # [config]
+    #   A Net::IMAP::Config object to use as the basis for #config.  By default,
+    #   the global Net::IMAP.config is used.
     #
-    # See DeprecatedClientOptions.new for deprecated arguments.
+    #   >>>
+    #     *NOTE:* +config+ does not set #config directly---it sets the _parent_
+    #     config for inheritance.  Every client creates its own unique #config.
+    #
+    #   All other keyword arguments are forwarded to Net::IMAP::Config.new, to
+    #   initialize the client's #config. For example:
+    #
+    #   [{open_timeout}[rdoc-ref:Config#open_timeout]]
+    #     Seconds to wait until a connection is opened
+    #   [{idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]]
+    #     Seconds to wait until an IDLE response is received
+    #
+    #   See Net::IMAP::Config for other valid options.
     #
     # ==== Examples
     #
@@ -872,13 +905,12 @@ module Net
     #   Connected to the host successfully, but it immediately said goodbye.
     #
     def initialize(host, port: nil, ssl:  nil,
-                   open_timeout: 30, idle_response_timeout: 5)
+                   config: Config.global, **config_options)
       super()
       # Config options
       @host = host
+      @config = Config.new(config, **config_options)
       @port = port || (ssl ? SSL_PORT : PORT)
-      @open_timeout = Integer(open_timeout)
-      @idle_response_timeout = Integer(idle_response_timeout)
       @ssl_ctx_params, @ssl_ctx = build_ssl_ctx(ssl)
 
       # Basic Client State
@@ -889,7 +921,7 @@ module Net
       @capabilities = nil
 
       # Client Protocol Receiver
-      @parser = ResponseParser.new
+      @parser = ResponseParser.new(config: @config)
       @responses = Hash.new {|h, k| h[k] = [] }
       @response_handlers = []
       @receiver_thread = nil
@@ -1198,7 +1230,7 @@ module Net
     end
 
     # :call-seq:
-    #   authenticate(mechanism, *, sasl_ir: true, registry: Net::IMAP::SASL.authenticators, **, &) -> ok_resp
+    #   authenticate(mechanism, *, sasl_ir: config.sasl_ir, registry: Net::IMAP::SASL.authenticators, **, &) -> ok_resp
     #
     # Sends an {AUTHENTICATE command [IMAP4rev1 §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]
     # to authenticate the client.  If successful, the connection enters the
@@ -1207,7 +1239,8 @@ module Net
     # +mechanism+ is the name of the \SASL authentication mechanism to be used.
     #
     # +sasl_ir+ allows or disallows sending an "initial response" (see the
-    # +SASL-IR+ capability, below).
+    # +SASL-IR+ capability, below).  Defaults to the #config value for
+    # {sasl_ir}[rdoc-ref:Config#sasl_ir], which defaults to +true+.
     #
     # All other arguments are forwarded to the registered SASL authenticator for
     # the requested mechanism.  <em>The documentation for each individual
@@ -1303,7 +1336,9 @@ module Net
     # Previously cached #capabilities will be cleared when this method
     # completes.  If the TaggedResponse to #authenticate includes updated
     # capabilities, they will be cached.
-    def authenticate(mechanism, *creds, sasl_ir: true, **props, &callback)
+    def authenticate(mechanism, *creds,
+                     sasl_ir: config.sasl_ir,
+                     **props, &callback)
       mechanism = mechanism.to_s.tr("_", "-").upcase
       authenticator = SASL.authenticator(mechanism, *creds, **props, &callback)
       cmdargs = ["AUTHENTICATE", mechanism]
@@ -2397,11 +2432,17 @@ module Net
     # checks the connection for each 60 seconds.
     #
     #   loop do
-    #     imap.idle(60) do |res|
-    #       ...
+    #     imap.idle(60) do |response|
+    #       do_something_with(response)
+    #       imap.idle_done if some_condition?(response)
     #     end
     #   end
     #
+    # Returns the server's response to indicate the IDLE state has ended.
+    # Returns +nil+ if the server does not respond to #idle_done within
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds.
+    #
     # Related: #idle_done, #noop, #check
     #
     # ===== Capabilities
@@ -2429,7 +2470,7 @@ module Net
           unless @receiver_thread_terminating
             remove_response_handler(response_handler)
             put_string("DONE#{CRLF}")
-            response = get_tagged_response(tag, "IDLE", @idle_response_timeout)
+            response = get_tagged_response(tag, "IDLE", idle_response_timeout)
           end
         end
       end
@@ -2437,7 +2478,11 @@ module Net
       return response
     end
 
-    # Leaves IDLE.
+    # Leaves IDLE, allowing #idle to return.
+    #
+    # If the server does not respond within
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds, #idle will return +nil+.
     #
     # Related: #idle
     def idle_done
@@ -2477,6 +2522,7 @@ module Net
     #
     #   Calling without a block is unsafe and deprecated.  Future releases will
     #   raise ArgumentError unless a block is given.
+    #   See Config#responses_without_block.
     #
     # Previously unhandled responses are automatically cleared before entering a
     # mailbox with #select or #examine.  Long-lived connections can receive many
@@ -2501,7 +2547,12 @@ module Net
       elsif type
         raise ArgumentError, "Pass a block or use #clear_responses"
       else
-        # warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        case config.responses_without_block
+        when :raise
+          raise ArgumentError, "Pass a block or use #clear_responses"
+        when :warn
+          warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        end
         @responses
       end
     end
@@ -2582,8 +2633,6 @@ module Net
     PORT = 143         # :nodoc:
     SSL_PORT = 993   # :nodoc:
 
-    @@debug = false
-
     def start_imap_connection
       @greeting        = get_server_greeting
       @capabilities    = capabilities_from_resp_code @greeting
@@ -2611,12 +2660,12 @@ module Net
     end
 
     def tcp_socket(host, port)
-      s = Socket.tcp(host, port, :connect_timeout => @open_timeout)
+      s = Socket.tcp(host, port, :connect_timeout => open_timeout)
       s.setsockopt(:SOL_SOCKET, :SO_KEEPALIVE, true)
       s
     rescue Errno::ETIMEDOUT
       raise Net::OpenTimeout, "Timeout to open TCP connection to " +
-        "#{host}:#{port} (exceeds #{@open_timeout} seconds)"
+        "#{host}:#{port} (exceeds #{open_timeout} seconds)"
     end
 
     def receive_responses
@@ -2728,7 +2777,7 @@ module Net
         end
       end
       return nil if buff.length == 0
-      if @@debug
+      if config.debug?
         $stderr.print(buff.gsub(/^/n, "S: "))
       end
       return @parser.parse(buff)
@@ -2807,7 +2856,7 @@ module Net
 
     def put_string(str)
       @sock.print(str)
-      if @@debug
+      if config.debug?
         if @debug_output_bol
           $stderr.print("C: ")
         end
@@ -2934,7 +2983,7 @@ module Net
       @sock = SSLSocket.new(@sock, ssl_ctx)
       @sock.sync_close = true
       @sock.hostname = @host if @sock.respond_to? :hostname=
-      ssl_socket_connect(@sock, @open_timeout)
+      ssl_socket_connect(@sock, open_timeout)
       if ssl_ctx.verify_mode != VERIFY_NONE
         @sock.post_connection_check(@host)
         @tls_verified = true
@@ -2959,6 +3008,7 @@ module Net
 end
 
 require_relative "imap/errors"
+require_relative "imap/config"
 require_relative "imap/command_data"
 require_relative "imap/data_encoding"
 require_relative "imap/flags"

data/net-imap.gemspec

@@ -25,9 +25,9 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files         = Dir.chdir(__dir__) do
     `git ls-files -z 2>/dev/null`.split("\x0")
-      .grep_v(%r{^(\.git|\.mailmap|bin|test|spec|benchmarks|features|rfcs)/})
+      .grep_v(%r{^(\.git(ignore)?|\.mailmap|(\.github|bin|test|spec|benchmarks|features|rfcs)/)})
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.12
+  version: 0.4.14
 platform: ruby
 authors:
 - Shugo Maeda
 - nicholas a. evans
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-01 00:00:00.000000000 Z
+date: 2024-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -46,12 +47,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/dependabot.yml"
-- ".github/workflows/pages.yml"
-- ".github/workflows/push_gem.yml"
-- ".github/workflows/test.yml"
-- ".gitignore"
-- ".mailmap"
 - BSDL
 - COPYING
 - Gemfile
@@ -62,6 +57,10 @@ files:
 - lib/net/imap.rb
 - lib/net/imap/authenticators.rb
 - lib/net/imap/command_data.rb
+- lib/net/imap/config.rb
+- lib/net/imap/config/attr_accessors.rb
+- lib/net/imap/config/attr_inheritance.rb
+- lib/net/imap/config/attr_type_coercion.rb
 - lib/net/imap/data_encoding.rb
 - lib/net/imap/deprecated_client_options.rb
 - lib/net/imap/errors.rb
@@ -111,6 +110,7 @@ metadata:
   homepage_uri: https://github.com/ruby/net-imap
   source_code_uri: https://github.com/ruby/net-imap
   changelog_uri: https://github.com/ruby/net-imap/releases
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -125,7 +125,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.0.dev
+rubygems_version: 3.5.9
+signing_key: 
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []

data/.github/dependabot.yml

@@ -1,6 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: 'github-actions'
-    directory: '/'
-    schedule:
-      interval: 'weekly'

data/.github/workflows/pages.yml

@@ -1,46 +0,0 @@
-name: Deploy RDoc site to Pages
-
-on:
-  push:
-    branches: [ 'master' ]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@250fcd6a742febb1123a77a841497ccaa8b9e939 # v1.152.0
-        with:
-          ruby-version: '3.2'
-          bundler-cache: true
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v5
-      - name: Build with RDoc
-        run: bundle exec rake rdoc
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with: { path: 'doc' }
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

data/.github/workflows/push_gem.yml

@@ -1,48 +0,0 @@
-name: Publish gem to rubygems.org
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  contents: read
-
-jobs:
-  push:
-    if: github.repository == 'ruby/net-imap'
-    runs-on: ubuntu-latest
-
-    environment:
-      name: rubygems.org
-      url: https://rubygems.org/gems/net-imap
-
-    permissions:
-      contents: write
-      id-token: write
-
-    steps:
-      # Set up
-      - name: Harden Runner
-        uses: step-security/harden-runner@f086349bfa2bd1361f7909c78558e816508cdc10 # v2.8.0
-        with:
-          egress-policy: audit
-
-      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@cacc9f1c0b3f4eb8a16a6bb0ed10897b43b9de49 # v1.176.0
-        with:
-          bundler-cache: true
-          ruby-version: ruby
-
-      # Release
-      - name: Publish to RubyGems
-        uses: rubygems/release-gem@612653d273a73bdae1df8453e090060bb4db5f31 # v1
-
-      - name: Create GitHub release
-        run: |
-          tag_name="$(git describe --tags --abbrev=0)"
-          gh release create "${tag_name}" --verify-tag --draft --generate-notes
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/test.yml

@@ -1,31 +0,0 @@
-name: Run tests
-
-on: [push, pull_request]
-
-jobs:
-  ruby-versions:
-    uses: ruby/actions/.github/workflows/ruby_versions.yml@master
-    with:
-      engine: cruby
-      min_version: 2.7
-
-  build:
-    needs: ruby-versions
-    name: build (${{ matrix.ruby }} / ${{ matrix.os }})
-    strategy:
-      matrix:
-        ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
-        os: [ ubuntu-latest, macos-latest ]
-        experimental: [false]
-    runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ matrix.experimental }}
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true
-        rubygems: 3.4.22
-    - name: Run test
-      run: bundle exec rake test

data/.gitignore

@@ -1,12 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/rfcs
-/spec/reports/
-/tmp/
-/Gemfile.lock
-/benchmarks/Gemfile*
-/benchmarks/parser.yml

data/.mailmap

@@ -1,13 +0,0 @@
-nicholas a. evans <nick@rubinick.dev>
-nicholas a. evans <nick@rubinick.dev> <nick@410labs.com>
-nicholas a. evans <nick@rubinick.dev> <nick@ekenosen.net>
-nicholas a. evans <nick@rubinick.dev> <nicholas.evans@gmail.com>
-
-Shugo Maeda <shugo@ruby-lang.org>
-Shugo Maeda <shugo@ruby-lang.org> <shugo@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
-
-Nobuyoshi Nakada <nobu@ruby-lang.org>
-Nobuyoshi Nakada <nobu@ruby-lang.org> <nobu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
-
-Hiroshi SHIBATA <hsbt@ruby-lang.org>
-Hiroshi SHIBATA <hsbt@ruby-lang.org> <hsbt@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>