net-imap 0.4.17 → 0.5.2

data/lib/net/imap/esearch_result.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    # An "extended search" response (+ESEARCH+).  ESearchResult should be
+    # returned (instead of SearchResult) by IMAP#search, IMAP#uid_search,
+    # IMAP#sort, and IMAP#uid_sort under any of the following conditions:
+    #
+    # * Return options were specified for IMAP#search or IMAP#uid_search.
+    #   The server must support a search extension which allows
+    #   RFC4466[https://www.rfc-editor.org/rfc/rfc4466.html] +return+ options,
+    #   such as +ESEARCH+, +PARTIAL+, or +IMAP4rev2+.
+    # * Return options were specified for IMAP#sort or IMAP#uid_sort.
+    #   The server must support the +ESORT+ extension
+    #   {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html#section-3].
+    #
+    #   *NOTE:* IMAP#search and IMAP#uid_search do not support +ESORT+ yet.
+    # * The server supports +IMAP4rev2+ but _not_ +IMAP4rev1+, or +IMAP4rev2+
+    #   has been enabled.  +IMAP4rev2+ requires +ESEARCH+ results.
+    #
+    # Note that some servers may claim to support a search extension which
+    # requires an +ESEARCH+ result, such as +PARTIAL+, but still only return a
+    # +SEARCH+ result when +return+ options are specified.
+    #
+    # Some search extensions may result in the server sending ESearchResult
+    # responses after the initiating command has completed.  Use
+    # IMAP#add_response_handler to handle these responses.
+    class ESearchResult < Data.define(:tag, :uid, :data)
+      def initialize(tag: nil, uid: nil, data: nil)
+        tag  => String       | nil; tag = -tag if tag
+        uid  => true | false | nil; uid = !!uid
+        data => Array        | nil; data ||= []; data.freeze
+        super
+      end
+
+      # :call-seq: to_a -> Array of integers
+      #
+      # When #all contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_a+ returns that set as an array of integers.
+      #
+      # When #all is +nil+, either because the server
+      # returned no results or because +ALL+ was not included in
+      # the IMAP#search +RETURN+ options, #to_a returns an empty array.
+      #
+      # Note that SearchResult also implements +to_a+, so it can be used without
+      # checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      def to_a; all&.numbers || [] end
+
+      ##
+      # attr_reader: tag
+      #
+      # The tag string for the command that caused this response to be returned.
+      #
+      # When +nil+, this response was not caused by a particular command.
+
+      ##
+      # attr_reader: uid
+      #
+      # Indicates whether #data in this response refers to UIDs (when +true+) or
+      # to message sequence numbers (when +false+).
+
+      ##
+      alias uid? uid
+
+      ##
+      # attr_reader: data
+      #
+      # Search return data, as an array of <tt>[name, value]</tt> pairs.  Most
+      # return data corresponds to a search +return+ option with the same name.
+      #
+      # Note that some return data names may be used more than once per result.
+      #
+      # This data can be more simply retrieved by #min, #max, #all, #count,
+      # #modseq, and other methods.
+
+      # :call-seq: min -> integer or nil
+      #
+      # The lowest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MIN+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def min;        data.assoc("MIN")&.last        end
+
+      # :call-seq: max -> integer or nil
+      #
+      # The highest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MAX+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def max;        data.assoc("MAX")&.last        end
+
+      # :call-seq: all -> sequence set or nil
+      #
+      # A SequenceSet containing all message sequence numbers or UIDs that
+      # satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +ALL+ return option was not specified but other return options were.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      #
+      # See also: #to_a
+      def all;        data.assoc("ALL")&.last        end
+
+      # :call-seq: count -> integer or nil
+      #
+      # Returns the number of messages that satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +COUNT+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def count;      data.assoc("COUNT")&.last      end
+
+      # :call-seq: modseq -> integer or nil
+      #
+      # The highest +mod-sequence+ of all messages being returned.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MODSEQ+ search criterion wasn't specified.
+      #
+      # Note that there is no search +return+ option for +MODSEQ+.  It will be
+      # returned whenever the +CONDSTORE+ extension has been enabled.  Using the
+      # +MODSEQ+ search criteria will implicitly enable +CONDSTORE+.
+      #
+      # Requires +CONDSTORE+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]
+      # and +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.2].
+      def modseq;     data.assoc("MODSEQ")&.last     end
+
+    end
+  end
+end

data/lib/net/imap/response_data.rb

@@ -2,6 +2,7 @@
 
 module Net
   class IMAP < Protocol
+    autoload :ESearchResult,    "#{__dir__}/esearch_result"
     autoload :FetchData,        "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
     autoload :SequenceSet,      "#{__dir__}/sequence_set"
@@ -939,7 +940,8 @@ module Net
       # for something else?
       #++
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
@@ -984,7 +986,8 @@ module Net
       # generate a warning message to +stderr+, then return
       # the value of +subtype+.
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
@@ -1040,77 +1043,6 @@ module Net
       end
     end
 
-    # BodyTypeAttachment is not used and will be removed in an upcoming release.
-    #
-    # === Bug Analysis
-    #
-    # \IMAP body structures are parenthesized lists and assign their fields
-    # positionally, so missing fields change the interpretation of all
-    # following fields.  Additionally, different body types have a different
-    # number of required fields, followed by optional "extension" fields.
-    #
-    # BodyTypeAttachment was previously returned when a "message/rfc822" part,
-    # which should be sent as <tt>body-type-msg</tt> with ten required fields,
-    # was actually sent as a <tt>body-type-basic</tt> with _seven_ required
-    # fields.
-    #
-    #   basic => type, subtype, param, id, desc, enc, octets, md5=nil,  dsp=nil, lang=nil, loc=nil, *ext
-    #   msg   => type, subtype, param, id, desc, enc, octets, envelope, body,    lines,    md5=nil, ...
-    #
-    # Normally, +envelope+ and +md5+ are incompatible, but Net::IMAP leniently
-    # allowed buggy servers to send +NIL+ for +envelope+.  As a result, when a
-    # server sent a <tt>message/rfc822</tt> part with +NIL+ for +md5+ and a
-    # non-<tt>NIL</tt> +dsp+, Net::IMAP misinterpreted the
-    # <tt>Content-Disposition</tt> as if it were a strange body type.  In all
-    # reported cases, the <tt>Content-Disposition</tt> was "attachment", so
-    # BodyTypeAttachment was created as the workaround.
-    #
-    # === Current behavior
-    #
-    # When interpreted strictly, +envelope+ and +md5+ are incompatible.  So the
-    # current parsing algorithm peeks ahead after it has received the seventh
-    # body field.  If the next token is not the start of an +envelope+, we assume
-    # the server has incorrectly sent us a <tt>body-type-basic</tt> and return
-    # BodyTypeBasic.  As a result, what was previously BodyTypeMessage#body =>
-    # BodyTypeAttachment is now BodyTypeBasic#disposition => ContentDisposition.
-    #
-    class BodyTypeAttachment < Struct.new(:dsp_type, :_unused_, :param)
-      # *invalid for BodyTypeAttachment*
-      def media_type
-        warn(<<~WARN, uplevel: 1)
-          BodyTypeAttachment#media_type is obsolete.  Use dsp_type instead.
-        WARN
-        dsp_type
-      end
-
-      # *invalid for BodyTypeAttachment*
-      def subtype
-        warn("BodyTypeAttachment#subtype is obsolete.\n", uplevel: 1)
-        nil
-      end
-
-      ##
-      # method: dsp_type
-      # :call-seq: dsp_type -> string
-      #
-      # Returns the content disposition type, as defined by
-      # [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
-
-      ##
-      # method: param
-      # :call-seq: param -> hash
-      #
-      # Returns a hash representing parameters of the Content-Disposition
-      # field, as defined by [DISPOSITION[https://tools.ietf.org/html/rfc2183]].
-
-      ##
-      def multipart?
-        return false
-      end
-    end
-
-    deprecate_constant :BodyTypeAttachment
-
     # Net::IMAP::BodyTypeMultipart represents body structures of messages and
     # message parts, when <tt>Content-Type</tt> is <tt>multipart/*</tt>.
     class BodyTypeMultipart < Struct.new(:media_type, :subtype,
@@ -1182,29 +1114,11 @@ module Net
       # generate a warning message to +stderr+, then return
       # the value of +subtype+.
       def media_subtype
-        warn("media_subtype is obsolete, use subtype instead.\n", uplevel: 1)
+        warn("media_subtype is obsolete, use subtype instead.\n",
+             uplevel: 1, category: :deprecated)
         return subtype
       end
     end
 
-    # === Obsolete
-    # BodyTypeExtension is not used and will be removed in an upcoming release.
-    #
-    # >>>
-    #   BodyTypeExtension was (incorrectly) used for <tt>message/*</tt> parts
-    #   (besides <tt>message/rfc822</tt>, which correctly uses BodyTypeMessage).
-    #
-    #   Net::IMAP now (correctly) parses all message types (other than
-    #   <tt>message/rfc822</tt> or <tt>message/global</tt>) as BodyTypeBasic.
-    class BodyTypeExtension < Struct.new(:media_type, :subtype,
-                                         :params, :content_id,
-                                         :description, :encoding, :size)
-      def multipart?
-        return false
-      end
-    end
-
-    deprecate_constant :BodyTypeExtension
-
   end
 end

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

@@ -185,6 +185,11 @@ module Net
           @str[@pos, str.length] == str
         end
 
+        def peek_re?(re)
+          assert_no_lookahead if Net::IMAP.debug
+          re.match?(@str, @pos)
+        end
+
         def peek_re(re)
           assert_no_lookahead if config.debug?
           re.match(@str, @pos)

data/lib/net/imap/response_parser.rb

@@ -769,7 +769,6 @@ module Net
       def response_data__ignored; response_data__unhandled(IgnoredResponse) end
       alias response_data__noop     response_data__ignored
 
-      alias esearch_response        response_data__unhandled
       alias expunged_resp           response_data__unhandled
       alias uidfetch_resp           response_data__unhandled
       alias listrights_data         response_data__unhandled
@@ -1317,31 +1316,19 @@ module Net
       #   header-fld-name = astring
       #
       # NOTE: Previously, Net::IMAP recreated the raw original source string.
-      # Now, it grabs the raw encoded value using @str and @pos.  A future
-      # version may simply return the decoded astring value.  Although that is
-      # technically incompatible, it should almost never make a difference: all
-      # standard header field names are valid atoms:
+      # Now, it returns the decoded astring value.  Although this is technically
+      # incompatible, it should almost never make a difference: all standard
+      # header field names are valid atoms:
       #
       # https://www.iana.org/assignments/message-headers/message-headers.xhtml
       #
-      # Although RFC3501 allows any astring, RFC5322-valid header names are one
-      # or more of the printable US-ASCII characters, except SP and colon.  So
-      # empty string isn't valid, and literals aren't needed and should not be
-      # used.  This is explicitly unchanged by [I18N-HDRS] (RFC6532).
-      #
-      # RFC5233:
+      # See also RFC5233:
       #     optional-field  =   field-name ":" unstructured CRLF
       #     field-name      =   1*ftext
       #     ftext           =   %d33-57 /          ; Printable US-ASCII
       #                         %d59-126           ;  characters not including
       #                                            ;  ":".
-      def header_fld_name
-        assert_no_lookahead
-        start = @pos
-        astring
-        end_pos = @token ? @pos - 1 : @pos
-        @str[start...end_pos]
-      end
+      alias header_fld_name astring
 
       # mailbox-data    =  "FLAGS" SP flag-list / "LIST" SP mailbox-list /
       #                    "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) /
@@ -1480,6 +1467,78 @@ module Net
       end
       alias sort_data mailbox_data__search
 
+      # esearch-response  = "ESEARCH" [search-correlator] [SP "UID"]
+      #                      *(SP search-return-data)
+      #                    ;; Note that SEARCH and ESEARCH responses
+      #                    ;; SHOULD be mutually exclusive,
+      #                    ;; i.e., only one of the response types
+      #                    ;; should be
+      #                    ;; returned as a result of a command.
+      # esearch-response  = "ESEARCH" [search-correlator] [SP "UID"]
+      #                     *(SP search-return-data)
+      #                   ; ESEARCH response replaces SEARCH response
+      #                   ; from IMAP4rev1.
+      # search-correlator  = SP "(" "TAG" SP tag-string ")"
+      def esearch_response
+        name = label("ESEARCH")
+        tag  = search_correlator if peek_str?(" (")
+        uid  = peek_re?(/\G UID\b/i) && (SP!; label("UID"); true)
+        data = []
+        data << search_return_data while SP?
+        esearch = ESearchResult.new(tag, uid, data)
+        UntaggedResponse.new(name, esearch, @str)
+      end
+
+      # From RFC4731 (ESEARCH):
+      #   search-return-data    = "MIN" SP nz-number /
+      #                           "MAX" SP nz-number /
+      #                           "ALL" SP sequence-set /
+      #                           "COUNT" SP number /
+      #                           search-ret-data-ext
+      #                           ; All return data items conform to
+      #                           ; search-ret-data-ext syntax.
+      #   search-ret-data-ext   = search-modifier-name SP search-return-value
+      #   search-modifier-name  = tagged-ext-label
+      #   search-return-value   = tagged-ext-val
+      #
+      # From RFC4731 (ESEARCH):
+      #   search-return-data    =/ "MODSEQ" SP mod-sequence-value
+      #
+      def search_return_data
+        label = search_modifier_name; SP!
+        value =
+          case label
+          when "MIN"        then nz_number
+          when "MAX"        then nz_number
+          when "ALL"        then sequence_set
+          when "COUNT"      then number
+          when "MODSEQ"     then mod_sequence_value         # RFC7162: CONDSTORE
+          else search_return_value
+          end
+        [label, value]
+      end
+
+      # search-modifier-name = tagged-ext-label
+      alias search_modifier_name tagged_ext_label
+
+      # search-return-value = tagged-ext-val
+      #                     ; Data for the returned search option.
+      #                     ; A single "nz-number"/"number"/"number64" value
+      #                     ; can be returned as an atom (i.e., without
+      #                     ; quoting).  A sequence-set can be returned
+      #                     ; as an atom as well.
+      def search_return_value; ExtensionData.new(tagged_ext_val) end
+
+      # search-correlator  = SP "(" "TAG" SP tag-string ")"
+      def search_correlator
+        SP!; lpar; label("TAG"); SP!; tag = tag_string; rpar
+        tag
+      end
+
+      # tag-string      = astring
+      #                   ; <tag> represented as <astring>
+      alias tag_string astring
+
       # RFC5256: THREAD
       #   thread-data     = "THREAD" [SP 1*thread-list]
       def thread_data

data/lib/net/imap/sasl/authentication_exchange.rb

@@ -4,44 +4,76 @@ module Net
   class IMAP
     module SASL
 
-      # This API is *experimental*, and may change.
+      # AuthenticationExchange is used internally by Net::IMAP#authenticate.
+      # But the API is still *experimental*, and may change.
       #
       # TODO: catch exceptions in #process and send #cancel_response.
       # TODO: raise an error if the command succeeds after being canceled.
       # TODO: use with more clients, to verify the API can accommodate them.
+      # TODO: pass ClientAdapter#service to SASL.authenticator
       #
-      # Create an AuthenticationExchange from a client adapter and a mechanism
-      # authenticator:
-      #     def authenticate(mechanism, ...)
-      #       authenticator = SASL.authenticator(mechanism, ...)
-      #       SASL::AuthenticationExchange.new(
-      #         sasl_adapter, mechanism, authenticator
-      #       ).authenticate
-      #     end
-      #
-      #     private
+      # An AuthenticationExchange represents a single attempt to authenticate
+      # a SASL client to a SASL server.  It is created from a client adapter, a
+      # mechanism name, and a mechanism authenticator.  When #authenticate is
+      # called, it will send the appropriate authenticate command to the server,
+      # returning the client response on success and raising an exception on
+      # failure.
       #
-      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      # In most cases, the client will not need to use
+      # SASL::AuthenticationExchange directly at all.  Instead, use
+      # SASL::ClientAdapter#authenticate.  If customizations are needed, the
+      # custom client adapter is probably the best place for that code.
       #
-      # Or delegate creation of the authenticator to ::build:
       #     def authenticate(...)
-      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
-      #         .authenticate
+      #       MyClient::SASLAdapter.new(self).authenticate(...)
       #     end
       #
-      # As a convenience, ::authenticate combines ::build and #authenticate:
+      # SASL::ClientAdapter#authenticate delegates to ::authenticate, like so:
+      #
       #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
       #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
       #     end
       #
-      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
-      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      # ::authenticate simply delegates to ::build and #authenticate, like so:
+      #
+      #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       SASL::AuthenticationExchange
+      #         .build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # And ::build delegates to SASL.authenticator and ::new, like so:
+      #
+      #     def authenticate(mechanism, ...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange
+      #         .new(sasl_adapter, mechanism, authenticator)
+      #         .authenticate
+      #     end
       #
       class AuthenticationExchange
         # Convenience method for <tt>build(...).authenticate</tt>
+        #
+        # See also: SASL::ClientAdapter#authenticate
         def self.authenticate(...) build(...).authenticate end
 
-        # Use +registry+ to override the global Authenticators registry.
+        # Convenience method to combine the creation of a new authenticator and
+        # a new Authentication exchange.
+        #
+        # +client+ must be an instance of SASL::ClientAdapter.
+        #
+        # +mechanism+ must be a SASL mechanism name, as a string or symbol.
+        #
+        # +sasl_ir+ allows or disallows sending an "initial response", depending
+        # also on whether the server capabilities, mechanism authenticator, and
+        # client adapter all support it.  Defaults to +true+.
+        #
+        # +mechanism+, +args+, +kwargs+, and +block+ are all forwarded to
+        # SASL.authenticator.  Use the +registry+ kwarg to override the global
+        # SASL::Authenticators registry.
         def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
           authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
           new(client, mechanism, authenticator, sasl_ir: sasl_ir)
@@ -51,7 +83,7 @@ module Net
 
         def initialize(client, mechanism, authenticator, sasl_ir: true)
           @client = client
-          @mechanism = -mechanism.to_s.upcase.tr(?_, ?-)
+          @mechanism = Authenticators.normalize_name(mechanism)
           @authenticator = authenticator
           @sasl_ir = sasl_ir
           @processed = false

data/lib/net/imap/sasl/authenticators.rb

@@ -21,6 +21,10 @@ module Net::IMAP::SASL
   # ScramSHA1Authenticator for examples.
   class Authenticators
 
+    # Normalize the mechanism name as an uppercase string, with underscores
+    # converted to dashes.
+    def self.normalize_name(mechanism) -(mechanism.to_s.upcase.tr(?_, ?-)) end
+
     # Create a new Authenticators registry.
     #
     # This class is usually not instantiated directly.  Use SASL.authenticators
@@ -65,7 +69,6 @@ module Net::IMAP::SASL
     # lazily loaded from <tt>Net::IMAP::SASL::#{name}Authenticator</tt> (case is
     # preserved and non-alphanumeric characters are removed..
     def add_authenticator(name, authenticator = nil)
-      key = -name.to_s.upcase.tr(?_, ?-)
       authenticator ||= begin
         class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
         auth_class = nil
@@ -74,17 +77,18 @@ module Net::IMAP::SASL
           auth_class.new(*creds, **props, &block)
         }
       end
+      key = Authenticators.normalize_name(name)
       @authenticators[key] = authenticator
     end
 
     # Removes the authenticator registered for +name+
     def remove_authenticator(name)
-      key = -name.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(name)
       @authenticators.delete(key)
     end
 
     def mechanism?(name)
-      key = -name.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(name)
       @authenticators.key?(key)
     end
 
@@ -105,7 +109,7 @@ module Net::IMAP::SASL
     #   only.  Protocol client users should see refer to their client's
     #   documentation, e.g. Net::IMAP#authenticate.
     def authenticator(mechanism, ...)
-      key = -mechanism.to_s.upcase.tr(?_, ?-)
+      key = Authenticators.normalize_name(mechanism)
       auth = @authenticators.fetch(key) do
         raise ArgumentError, 'unknown auth type - "%s"' % key
       end