net-imap 0.4.16 → 0.5.0

data/lib/net/imap/sequence_set.rb

@@ -14,13 +14,6 @@ module Net
     # receive a SequenceSet as an argument, for example IMAP#search, IMAP#fetch,
     # and IMAP#store.
     #
-    # == EXPERIMENTAL API
-    #
-    # SequenceSet is currently experimental.  Only two methods, ::[] and
-    # #valid_string, are considered stable.  Although the API isn't expected to
-    # change much, any other methods may be removed or changed without
-    # deprecation.
-    #
     # == Creating sequence sets
     #
     # SequenceSet.new with no arguments creates an empty sequence set.  Note
@@ -37,7 +30,8 @@ module Net
     #
     # SequenceSet.new may receive a single optional argument: a non-zero 32 bit
     # unsigned integer, a range, a <tt>sequence-set</tt> formatted string,
-    # another sequence set, or an enumerable containing any of these.
+    # another sequence set, a Set (containing only numbers or <tt>*</tt>), or an
+    # Array containing any of these (array inputs may be nested).
     #
     #     set = Net::IMAP::SequenceSet.new(1)
     #     set.valid_string  #=> "1"
@@ -289,8 +283,7 @@ module Net
       private_constant :STAR_INT, :STARS
 
       COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      ENUMABLE  = ->{ _1.respond_to?(:each) && _1.respond_to?(:empty?) }
-      private_constant :COERCIBLE, :ENUMABLE
+      private_constant :COERCIBLE
 
       class << self
 
@@ -304,7 +297,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 +675,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
@@ -1271,7 +1265,8 @@ module Net
         when *STARS, Integer, Range then [input_to_tuple(obj)]
         when String      then str_to_tuples obj
         when SequenceSet then obj.tuples
-        when ENUMABLE    then obj.flat_map { input_to_tuples _1 }
+        when Set         then obj.map      { [to_tuple_int(_1)] * 2 }
+        when Array       then obj.flat_map { input_to_tuples _1 }
         when nil         then []
         else
           raise DataFormatError,
@@ -1284,8 +1279,7 @@ module Net
       # String, Set, Array, or... any type of object.
       def input_try_convert(input)
         SequenceSet.try_convert(input) ||
-          # Integer.try_convert(input) || # ruby 3.1+
-          input.respond_to?(:to_int) && Integer(input.to_int) ||
+          Integer.try_convert(input) ||
           String.try_convert(input) ||
           input
       end
@@ -1317,6 +1311,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 +1331,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 +1368,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.
@@ -1407,12 +1409,11 @@ module Net
       end
 
       def nz_number(num)
-        case num
-        when Integer, /\A[1-9]\d*\z/ then num = Integer(num)
-        else raise DataFormatError, "%p is not a valid nz-number" % [num]
-        end
-        NumValidator.ensure_nz_number(num)
-        num
+        String === num && !/\A[1-9]\d*\z/.match?(num) and
+          raise DataFormatError, "%p is not a valid nz-number" % [num]
+        NumValidator.ensure_nz_number Integer num
+      rescue TypeError # To catch errors from Integer()
+        raise DataFormatError, $!.message
       end
 
       # intentionally defined after the class implementation

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.5.0"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -944,9 +946,6 @@ module Net
       @sock = tcp_socket(@host, @port)
       start_tls_session if ssl_ctx
       start_imap_connection
-
-      # DEPRECATED: to remove in next version
-      @client_thread = Thread.current
     end
 
     # Returns true after the TLS negotiation has completed and the remote
@@ -954,11 +953,6 @@ module Net
     # but peer verification was disabled.
     def tls_verified?; @tls_verified end
 
-    def client_thread # :nodoc:
-      warn "Net::IMAP#client_thread is deprecated and will be removed soon."
-      @client_thread
-    end
-
     # Disconnects from the server.
     #
     # Related: #logout, #logout!
@@ -1242,6 +1236,9 @@ module Net
     # +SASL-IR+ capability, below).  Defaults to the #config value for
     # {sasl_ir}[rdoc-ref:Config#sasl_ir], which defaults to +true+.
     #
+    # The +registry+ kwarg can be used to select the mechanism implementation
+    # from a custom registry.  See SASL.authenticator and SASL::Authenticators.
+    #
     # All other arguments are forwarded to the registered SASL authenticator for
     # the requested mechanism.  <em>The documentation for each individual
     # mechanism must be consulted for its specific parameters.</em>
@@ -1336,29 +1333,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: config.sasl_ir,
-                     **props, &callback)
-      mechanism = mechanism.to_s.tr("_", "-").upcase
-      authenticator = SASL.authenticator(mechanism, *creds, **props, &callback)
-      cmdargs = ["AUTHENTICATE", mechanism]
-      if sasl_ir && capable?("SASL-IR") && auth_capable?(mechanism) &&
-          authenticator.respond_to?(:initial_response?) &&
-          authenticator.initial_response?
-        response = authenticator.process(nil)
-        cmdargs << (response.empty? ? "=" : [response].pack("m0"))
-      end
-      result = send_command_with_continuations(*cmdargs) {|data|
-        challenge = data.unpack1("m")
-        response  = authenticator.process challenge
-        [response].pack("m0")
-      }
-      if authenticator.respond_to?(:done?) && !authenticator.done?
-        logout!
-        raise SASL::AuthenticationIncomplete, result
-      end
-      @capabilities = capabilities_from_resp_code result
-      result
+    def authenticate(*args, sasl_ir: config.sasl_ir, **props, &callback)
+      sasl_adapter.authenticate(*args, sasl_ir: sasl_ir, **props, &callback)
+        .tap { @capabilities = capabilities_from_resp_code _1 }
     end
 
     # Sends a {LOGIN command [IMAP4rev1 §6.2.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.3]
@@ -1378,13 +1355,9 @@ module Net
     # ===== Capabilities
     #
     # An IMAP client MUST NOT call #login when the server advertises the
-    # +LOGINDISABLED+ capability.
-    #
-    #    if imap.capability? "LOGINDISABLED"
-    #      raise "Remote server has disabled the login command"
-    #    else
-    #      imap.login username, password
-    #    end
+    # +LOGINDISABLED+ capability.  By default, Net::IMAP will raise a
+    # LoginDisabledError when that capability is present.  See
+    # Config#enforce_logindisabled.
     #
     # Server capabilities may change after #starttls, #login, and #authenticate.
     # Cached capabilities _must_ be invalidated after this method completes.
@@ -1392,6 +1365,9 @@ module Net
     # ResponseCode.
     #
     def login(user, password)
+      if enforce_logindisabled? && capability?("LOGINDISABLED")
+        raise LoginDisabledError
+      end
       send_command("LOGIN", user, password)
         .tap { @capabilities = capabilities_from_resp_code _1 }
     end
@@ -1948,7 +1924,7 @@ module Net
     # [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
     def uid_expunge(uid_set)
       synchronize do
-        send_command("UID EXPUNGE", MessageSet.new(uid_set))
+        send_command("UID EXPUNGE", SequenceSet.new(uid_set))
         clear_responses("EXPUNGE")
       end
     end
@@ -2494,41 +2470,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 +2572,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, category: :deprecated)
+        when :frozen_dup
+          synchronize {
+            responses = @responses.transform_values(&:freeze)
+            responses.default_proc = nil
+            responses.default = [].freeze
+            return responses.freeze
+          }
         end
         @responses
       end
@@ -2567,7 +2605,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 +2619,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.
@@ -2869,6 +2931,14 @@ module Net
       end
     end
 
+    def enforce_logindisabled?
+      if config.enforce_logindisabled == :when_capabilities_cached
+        capabilities_cached?
+      else
+        config.enforce_logindisabled
+      end
+    end
+
     def search_internal(cmd, keys, charset)
       if keys.instance_of?(String)
         keys = [RawData.new(keys)]
@@ -2902,9 +2972,9 @@ module Net
       synchronize do
         clear_responses("FETCH")
         if mod
-          send_command(cmd, MessageSet.new(set), attr, mod)
+          send_command(cmd, SequenceSet.new(set), attr, mod)
         else
-          send_command(cmd, MessageSet.new(set), attr)
+          send_command(cmd, SequenceSet.new(set), attr)
         end
         clear_responses("FETCH")
       end
@@ -2912,7 +2982,7 @@ module Net
 
     def store_internal(cmd, set, attr, flags, unchangedsince: nil)
       attr = RawData.new(attr) if attr.instance_of?(String)
-      args = [MessageSet.new(set)]
+      args = [SequenceSet.new(set)]
       args << ["UNCHANGEDSINCE", Integer(unchangedsince)] if unchangedsince
       args << attr << flags
       synchronize do
@@ -2923,7 +2993,7 @@ module Net
     end
 
     def copy_internal(cmd, set, mailbox)
-      send_command(cmd, MessageSet.new(set), mailbox)
+      send_command(cmd, SequenceSet.new(set), mailbox)
     end
 
     def sort_internal(cmd, sort_keys, search_keys, charset)
@@ -2954,7 +3024,7 @@ module Net
       keys.collect! do |i|
         case i
         when -1, Range, Array
-          MessageSet.new(i)
+          SequenceSet.new(i)
         else
           i
         end

data/net-imap.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{Ruby client api for Internet Message Access Protocol}
   spec.description   = %q{Ruby client api for Internet Message Access Protocol}
   spec.homepage      = "https://github.com/ruby/net-imap"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.7.3")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.1.0")
   spec.licenses       = ["Ruby", "BSD-2-Clause"]
 
   spec.metadata["homepage_uri"] = spec.homepage

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.16
+  version: 0.5.0
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-04 00:00:00.000000000 Z
+date: 2024-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -118,14 +118,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.3
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.16
 signing_key: 
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol