net-imap 0.4.16 → 0.4.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb20811050c485f7fcde01bb24dbe455026b45cc463efe39353a3f186312a5d5
-  data.tar.gz: 1290933be2c606cb299c75acc7ba59aa3ecdbcad245e776981eb2eb49d3289f3
+  metadata.gz: aceea6e339f24fafdd1920f2b25d863b47823c5654528441e4c7d173e414f3c2
+  data.tar.gz: 6258659759ae4c6b7ea63f7dddf0fb4a7231c3242ebad72188ba43bb7a2f3165
 SHA512:
-  metadata.gz: 857dfd2863abedf53c6adf874a8d6883ea93de91cb01bd0c3ec60ca2279f86e1ae41ddedaccd1329490dddb6dabdce59cddf22699c0792085a5fba2a76184647
-  data.tar.gz: 0766bbf7514aa1c293b18575c47bf02f5eff1c62b69c8cda432aba35d72572607d60588e45ab78a25e5df7f8d7df2fe5c90d965f580c8178171554151ab0c4a0
+  metadata.gz: 003561bf18250b9237f10d5ba5ce20ea285dea1d0380f4612d08429fe31ceea14d84fef76dc4e6c5ba47ff2e798b20a7767d85f6cdeb79f7abfcdb25df39093f
+  data.tar.gz: 42702bd43a0f9e778c88017e1553a5ddd058c0b702f1c39843c845ef0fba935b2f3ee636dc10a700e23b89c3e9a9e5b9c80b8bff836e65985bc59ca73c2a6255

data/lib/net/imap/config.rb

@@ -7,10 +7,10 @@ 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.
+    # Net::IMAP::Config <em>(available since +v0.4.13+)</em> 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
@@ -128,7 +128,7 @@ module Net
       # 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.
+      # A hash of hard-coded configurations, indexed by version number or name.
       def self.version_defaults; @version_defaults end
       @version_defaults = {}
 
@@ -172,9 +172,16 @@ module Net
       include AttrInheritance
       include AttrTypeCoercion
 
-      # The debug mode (boolean)
+      # The debug mode (boolean).  The default value is +false+.
       #
-      # The default value is +false+.
+      # When #debug is +true+:
+      # * Data sent to and received from the server will be logged.
+      # * ResponseParser will print warnings with extra detail for parse
+      #   errors.  _This may include recoverable errors._
+      # * ResponseParser makes extra assertions.
+      #
+      # *NOTE:* Versioned default configs inherit #debug from Config.global, and
+      # #load_defaults will not override #debug.
       attr_accessor :debug, type: :boolean
 
       # method: debug?
@@ -200,34 +207,61 @@ module Net
       # 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.
+      # mechanism both support it.  Can be overridden by the +sasl_ir+ keyword
+      # parameter to Net::IMAP#authenticate.
+      #
+      # <em>(Support for +SASL-IR+ was added in +v0.4.0+.)</em>
+      #
+      # ==== Valid options
       #
-      # See Net::IMAP#authenticate.
+      # [+false+ <em>(original behavior, before support was added)</em>]
+      #   Do not use +SASL-IR+, even when it is supported by the server and the
+      #   mechanism.
       #
-      # | Starting with version | The default value is                     |
-      # |-----------------------|------------------------------------------|
-      # | _original_            | +false+ <em>(extension unsupported)</em> |
-      # | v0.4                  | +true+  <em>(support added)</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
 
-      # :markup: markdown
+
+      # Controls the behavior of Net::IMAP#responses when called without any
+      # arguments (+type+ or +block+).
+      #
+      # ==== Valid options
+      #
+      # [+:silence_deprecation_warning+ <em>(original behavior)</em>]
+      #   Returns the mutable responses hash (without any warnings).
+      #   <em>This is not thread-safe.</em>
       #
-      # Controls the behavior of Net::IMAP#responses when called without a
-      # block.  Valid options are `:warn`, `:raise`, or
-      # `:silence_deprecation_warning`.
+      # [+:warn+ <em>(default since +v0.5+)</em>]
+      #   Prints a warning and returns the mutable responses hash.
+      #   <em>This is not thread-safe.</em>
       #
-      # | Starting with version   | The default value is           |
-      # |-------------------------|--------------------------------|
-      # | v0.4.13                 | +:silence_deprecation_warning+ |
-      # | v0.5 <em>(planned)</em> | +:warn+                        |
-      # | _eventually_            | +:raise+                       |
+      # [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+      #   Returns a frozen copy of the unhandled responses hash, with frozen
+      #   array values.
+      #
+      #   Note that calling IMAP#responses with a +type+ and without a block is
+      #   not configurable and always behaves like +:frozen_dup+.
+      #
+      #   <em>(+:frozen_dup+ config option was added in +v0.4.17+)</em>
+      #
+      # [+:raise+]
+      #   Raise an ArgumentError with the deprecation warning.
+      #
+      # Note: #responses_without_args is an alias for #responses_without_block.
       attr_accessor :responses_without_block, type: [
-        :silence_deprecation_warning, :warn, :raise,
+        :silence_deprecation_warning, :warn, :frozen_dup, :raise,
       ]
 
+      alias responses_without_args  responses_without_block  # :nodoc:
+      alias responses_without_args= responses_without_block= # :nodoc:
+
+      ##
+      # :attr_accessor: responses_without_args
+      #
+      # Alias for responses_without_block
+
       # Creates a new config object and initialize its attribute with +attrs+.
       #
       # If +parent+ is not given, the global config is used by default.
@@ -329,9 +363,10 @@ module Net
       version_defaults[:current] = Config[0.4]
       version_defaults[:next]    = Config[0.5]
 
-      version_defaults[:future]  = Config[0.5].dup.update(
-        responses_without_block: :raise,
+      version_defaults[0.6]      = Config[0.5].dup.update(
+        responses_without_block: :frozen_dup,
       ).freeze
+      version_defaults[:future]  = Config[0.6]
 
       version_defaults.freeze
     end

data/lib/net/imap/sequence_set.rb

@@ -304,7 +304,7 @@ module Net
         # Use ::new to create a mutable or empty SequenceSet.
         def [](first, *rest)
           if rest.empty?
-            if first.is_a?(SequenceSet) && set.frozen? && set.valid?
+            if first.is_a?(SequenceSet) && first.frozen? && first.valid?
               first
             else
               new(first).validate.freeze
@@ -682,6 +682,7 @@ module Net
       # Unlike #add, #merge, or #union, the new value is appended to #string.
       # This may result in a #string which has duplicates or is out-of-order.
       def append(object)
+        modifying!
         tuple = input_to_tuple object
         entry = tuple_to_str tuple
         tuple_add tuple
@@ -1317,6 +1318,12 @@ module Net
           range.include?(min) || range.include?(max) || (min..max).cover?(range)
       end
 
+      def modifying!
+        if frozen?
+          raise FrozenError, "can't modify frozen #{self.class}: %p" % [self]
+        end
+      end
+
       def tuples_add(tuples)      tuples.each do tuple_add _1      end; self end
       def tuples_subtract(tuples) tuples.each do tuple_subtract _1 end; self end
 
@@ -1331,6 +1338,7 @@ module Net
       #   ---------??===lower==|--|==|----|===upper===|-- join until upper
       #   ---------??===lower==|--|==|--|=====upper===|-- join to upper
       def tuple_add(tuple)
+        modifying!
         min, max = tuple
         lower, lower_idx = tuple_gte_with_index(min - 1)
         if    lower.nil?              then tuples << tuple
@@ -1367,6 +1375,7 @@ module Net
       # -------??=====lower====|--|====|---|====upper====|-- 7. delete until
       # -------??=====lower====|--|====|--|=====upper====|-- 8. delete and trim
       def tuple_subtract(tuple)
+        modifying!
         min, max = tuple
         lower, idx = tuple_gte_with_index(min)
         if    lower.nil?        then nil # case 1.

data/lib/net/imap.rb

@@ -288,6 +288,8 @@ module Net
   #   pre-authenticated connection.
   # - #responses: Yields unhandled UntaggedResponse#data and <em>non-+nil+</em>
   #   ResponseCode#data.
+  # - #extract_responses: Removes and returns the responses for which the block
+  #   returns a true value.
   # - #clear_responses: Deletes unhandled data from #responses and returns it.
   # - #add_response_handler: Add a block to be called inside the receiver thread
   #   with every server response.
@@ -717,7 +719,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.16"
+    VERSION = "0.4.17"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -2494,41 +2496,98 @@ module Net
       end
     end
 
+    RESPONSES_DEPRECATION_MSG =
+      "Pass a type or block to #responses, " \
+      "set config.responses_without_block to :frozen_dup " \
+      "or :silence_deprecation_warning, " \
+      "or use #extract_responses or #clear_responses."
+    private_constant :RESPONSES_DEPRECATION_MSG
+
     # :call-seq:
+    #   responses       -> hash of {String => Array} (see config.responses_without_block)
+    #   responses(type) -> frozen array
     #   responses       {|hash|  ...} -> block result
     #   responses(type) {|array| ...} -> block result
     #
-    # Yields unhandled responses and returns the result of the block.
+    # Yields or returns unhandled server responses.  Unhandled responses are
+    # stored in a hash, with arrays of UntaggedResponse#data keyed by
+    # UntaggedResponse#name and <em>non-+nil+</em> untagged ResponseCode#data
+    # keyed by ResponseCode#name.
+    #
+    # When a block is given, yields unhandled responses and returns the block's
+    # result.  Without a block, returns the unhandled responses.
+    #
+    # [With +type+]
+    #   Yield or return only the array of responses for that +type+.
+    #   When no block is given, the returned array is a frozen copy.
+    # [Without +type+]
+    #   Yield or return the entire responses hash.
+    #
+    #   When no block is given, the behavior is determined by
+    #   Config#responses_without_block:
+    #   >>>
+    #     [+:silence_deprecation_warning+ <em>(original behavior)</em>]
+    #       Returns the mutable responses hash (without any warnings).
+    #       <em>This is not thread-safe.</em>
+    #
+    #     [+:warn+ <em>(default since +v0.5+)</em>]
+    #       Prints a warning and returns the mutable responses hash.
+    #       <em>This is not thread-safe.</em>
     #
-    # Unhandled responses are stored in a hash, with arrays of
-    # <em>non-+nil+</em> UntaggedResponse#data keyed by UntaggedResponse#name
-    # and ResponseCode#data keyed by ResponseCode#name.  Call without +type+ to
-    # yield the entire responses hash.  Call with +type+ to yield only the array
-    # of responses for that type.
+    #     [+:frozen_dup+ <em>(planned default for +v0.6+)</em>]
+    #       Returns a frozen copy of the unhandled responses hash, with frozen
+    #       array values.
+    #
+    #     [+:raise+]
+    #       Raise an +ArgumentError+ with the deprecation warning.
     #
     # For example:
     #
     #   imap.select("inbox")
-    #   p imap.responses("EXISTS", &:last)
+    #   p imap.responses("EXISTS").last
     #   #=> 2
+    #   p imap.responses("UIDNEXT", &:last)
+    #   #=> 123456
     #   p imap.responses("UIDVALIDITY", &:last)
     #   #=> 968263756
+    #   p imap.responses {|responses|
+    #     {
+    #       exists:      responses.delete("EXISTS").last,
+    #       uidnext:     responses.delete("UIDNEXT").last,
+    #       uidvalidity: responses.delete("UIDVALIDITY").last,
+    #     }
+    #   }
+    #   #=> {:exists=>2, :uidnext=>123456, :uidvalidity=>968263756}
+    #   # "EXISTS", "UIDNEXT", and "UIDVALIDITY" have been removed:
+    #   p imap.responses(&:keys)
+    #   #=> ["FLAGS", "OK", "PERMANENTFLAGS", "RECENT", "HIGHESTMODSEQ"]
+    #
+    # Related: #extract_responses, #clear_responses, #response_handlers, #greeting
     #
+    # ===== Thread safety
     # >>>
     #   *Note:* Access to the responses hash is synchronized for thread-safety.
     #   The receiver thread and response_handlers cannot process new responses
     #   until the block completes.  Accessing either the response hash or its
-    #   response type arrays outside of the block is unsafe.
+    #   response type arrays outside of the block is unsafe.  They can be safely
+    #   updated inside the block.  Consider using #clear_responses or
+    #   #extract_responses instead.
     #
-    #   Calling without a block is unsafe and deprecated.  Future releases will
-    #   raise ArgumentError unless a block is given.
-    #   See Config#responses_without_block.
+    #   Net::IMAP will add and remove responses from the responses hash and its
+    #   array values, in the calling threads for commands and in the receiver
+    #   thread, but will not modify any responses after adding them to the
+    #   responses hash.
+    #
+    # ===== Clearing responses
     #
     # Previously unhandled responses are automatically cleared before entering a
     # mailbox with #select or #examine.  Long-lived connections can receive many
     # unhandled server responses, which must be pruned or they will continually
     # consume more memory.  Update or clear the responses hash or arrays inside
-    # the block, or use #clear_responses.
+    # the block, or remove responses with #extract_responses, #clear_responses,
+    # or #add_response_handler.
+    #
+    # ===== Missing responses
     #
     # Only non-+nil+ data is stored.  Many important response codes have no data
     # of their own, but are used as "tags" on the ResponseText object they are
@@ -2539,19 +2598,24 @@ module Net
     # ResponseCode#data on tagged responses.  Although some command methods do
     # return the TaggedResponse directly, #add_response_handler must be used to
     # handle all response codes.
-    #
-    # Related: #clear_responses, #response_handlers, #greeting
     def responses(type = nil)
       if block_given?
         synchronize { yield(type ? @responses[type.to_s.upcase] : @responses) }
       elsif type
-        raise ArgumentError, "Pass a block or use #clear_responses"
+        synchronize { @responses[type.to_s.upcase].dup.freeze }
       else
         case config.responses_without_block
         when :raise
-          raise ArgumentError, "Pass a block or use #clear_responses"
+          raise ArgumentError, RESPONSES_DEPRECATION_MSG
         when :warn
-          warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+          warn(RESPONSES_DEPRECATION_MSG, uplevel: 1)
+        when :frozen_dup
+          synchronize {
+            responses = @responses.transform_values(&:freeze)
+            responses.default_proc = nil
+            responses.default = [].freeze
+            return responses.freeze
+          }
         end
         @responses
       end
@@ -2567,7 +2631,7 @@ module Net
     # Clearing responses is synchronized with other threads.  The lock is
     # released before returning.
     #
-    # Related: #responses, #response_handlers
+    # Related: #extract_responses, #responses, #response_handlers
     def clear_responses(type = nil)
       synchronize {
         if type
@@ -2581,6 +2645,30 @@ module Net
         .freeze
     end
 
+    # :call-seq:
+    #   extract_responses(type) {|response| ... } -> array
+    #
+    # Yields all of the unhandled #responses for a single response +type+.
+    # Removes and returns the responses for which the block returns a true
+    # value.
+    #
+    # Extracting responses is synchronized with other threads.  The lock is
+    # released before returning.
+    #
+    # Related: #responses, #clear_responses
+    def extract_responses(type)
+      type = String.try_convert(type) or
+        raise ArgumentError, "type must be a string"
+      raise ArgumentError, "must provide a block" unless block_given?
+      extracted = []
+      responses(type) do |all|
+        all.reject! do |response|
+          extracted << response if yield response
+        end
+      end
+      extracted
+    end
+
     # Returns all response handlers, including those that are added internally
     # by commands.  Each response handler will be called with every new
     # UntaggedResponse, TaggedResponse, and ContinuationRequest.

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.16
+  version: 0.4.17
 platform: ruby
 authors:
 - Shugo Maeda
 - nicholas a. evans
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-04 00:00:00.000000000 Z
+date: 2024-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -110,7 +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: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -125,8 +125,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key: 
+rubygems_version: 3.5.16
+signing_key:
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []