net-imap 0.4.12 → 0.5.6

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,28 @@ 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)
+        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)
         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 +217,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,19 @@ module Net
       include ParserUtils
       extend  ParserUtils::Generator
 
-      # :call-seq: Net::IMAP::ResponseParser.new -> Net::IMAP::ResponseParser
-      def initialize
+      attr_reader :config
+
+      # Creates a new ResponseParser.
+      #
+      # When +config+ is frozen or global, the parser #config inherits from it.
+      # Otherwise, +config+ will be used directly.
+      def initialize(config: Config.global)
         @str = nil
         @pos = nil
         @lex_state = nil
         @token = nil
+        @config = Config[config]
+        @config = @config.new if @config == Config.global || @config.frozen?
       end
 
       # :call-seq:
@@ -318,6 +325,24 @@ module Net
         SEQUENCE_SET      = /#{SEQUENCE_SET_ITEM}(?:,#{SEQUENCE_SET_ITEM})*/n
         SEQUENCE_SET_STR  = /\A#{SEQUENCE_SET}\z/n
 
+        # partial-range-first = nz-number ":" nz-number
+        #     ;; Request to search from oldest (lowest UIDs) to
+        #     ;; more recent messages.
+        #     ;; A range 500:400 is the same as 400:500.
+        #     ;; This is similar to <seq-range> from [RFC3501]
+        #     ;; but cannot contain "*".
+        PARTIAL_RANGE_FIRST = /\A(#{NZ_NUMBER}):(#{NZ_NUMBER})\z/n
+
+        # partial-range-last  = MINUS nz-number ":" MINUS nz-number
+        #     ;; Request to search from newest (highest UIDs) to
+        #     ;; oldest messages.
+        #     ;; A range -500:-400 is the same as -400:-500.
+        PARTIAL_RANGE_LAST  = /\A(-#{NZ_NUMBER}):(-#{NZ_NUMBER})\z/n
+
+        # partial-range     = partial-range-first / partial-range-last
+        PARTIAL_RANGE       = Regexp.union(PARTIAL_RANGE_FIRST,
+                                           PARTIAL_RANGE_LAST)
+
         # RFC3501:
         #   literal          = "{" number "}" CRLF *CHAR8
         #                        ; Number represents the number of CHAR8s
@@ -713,7 +738,7 @@ module Net
         when "EXISTS"     then mailbox_data__exists      # RFC3501, RFC9051
         when "ESEARCH"    then esearch_response          # RFC4731, RFC9051, etc
         when "VANISHED"   then expunged_resp             # RFC7162
-        when "UIDFETCH"   then uidfetch_resp             # (draft) UIDONLY
+        when "UIDFETCH"   then uidfetch_resp             # RFC9586
         when "SEARCH"     then mailbox_data__search      # RFC3501 (obsolete)
         when "CAPABILITY" then capability_data__untagged # RFC3501, RFC9051
         when "FLAGS"      then mailbox_data__flags       # RFC3501, RFC9051
@@ -766,9 +791,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
       alias myrights_data           response_data__unhandled
       alias metadata_resp           response_data__unhandled
@@ -829,6 +851,14 @@ module Net
         UntaggedResponse.new(name, data, @str)
       end
 
+      #   uidfetch-resp = uniqueid SP "UIDFETCH" SP msg-att
+      def uidfetch_resp
+        uid  = uniqueid;         SP!
+        name = label "UIDFETCH"; SP!
+        data = UIDFetchData.new(uid, msg_att(uid))
+        UntaggedResponse.new(name, data, @str)
+      end
+
       def response_data__simple_numeric
         data = nz_number; SP!
         name = tagged_ext_label
@@ -839,6 +869,20 @@ module Net
       alias mailbox_data__exists  response_data__simple_numeric
       alias mailbox_data__recent  response_data__simple_numeric
 
+      # The name for this is confusing, because it *replaces* EXPUNGE
+      # >>>
+      #   expunged-resp       =  "VANISHED" [SP "(EARLIER)"] SP known-uids
+      def expunged_resp
+        name    = label "VANISHED"; SP!
+        earlier = if lpar? then label("EARLIER"); rpar; SP!; true else false end
+        uids    = known_uids
+        data    = VanishedData[uids, earlier]
+        UntaggedResponse.new name, data, @str
+      end
+
+      # TODO: replace with uid_set
+      alias known_uids sequence_set
+
       # RFC3501 & RFC9051:
       #   msg-att         = "(" (msg-att-dynamic / msg-att-static)
       #                      *(SP (msg-att-dynamic / msg-att-static)) ")"
@@ -1314,30 +1358,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
-        @str[start...@pos - 1]
-      end
+      alias header_fld_name astring
 
       # mailbox-data    =  "FLAGS" SP flag-list / "LIST" SP mailbox-list /
       #                    "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) /
@@ -1476,6 +1509,111 @@ 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
+      #
+      # From RFC9394 (PARTIAL):
+      #   search-return-data  =/ ret-data-partial
+      #
+      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
+          when "PARTIAL"    then ret_data_partial__value    # RFC9394: PARTIAL
+          else search_return_value
+          end
+        [label, value]
+      end
+
+      # From RFC5267 (CONTEXT=SEARCH, CONTEXT=SORT) and RFC9394 (PARTIAL):
+      #   ret-data-partial    = "PARTIAL"
+      #                         SP "(" partial-range SP partial-results ")"
+      def ret_data_partial__value
+        lpar
+        range   = partial_range;   SP!
+        results = partial_results
+        rpar
+        ESearchResult::PartialResult.new(range, results)
+      end
+
+      # partial-range       = partial-range-first / partial-range-last
+      # tagged-ext-simple   =/ partial-range-last
+      def partial_range
+        case (str = atom)
+        when Patterns::PARTIAL_RANGE_FIRST, Patterns::PARTIAL_RANGE_LAST
+          min, max = [Integer($1), Integer($2)].minmax
+          min..max
+        else
+          parse_error("unexpected atom %p, expected partial-range", str)
+        end
+      end
+
+      # partial-results     = sequence-set / "NIL"
+      #     ;; <sequence-set> from [RFC3501].
+      #     ;; NIL indicates that no results correspond to
+      #     ;; the requested range.
+      def partial_results; NIL? ? nil : sequence_set 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
@@ -1808,6 +1946,9 @@ module Net
       #
       # RFC8474: OBJECTID
       #   resp-text-code   =/ "MAILBOXID" SP "(" objectid ")"
+      #
+      # RFC9586: UIDONLY
+      #   resp-text-code   =/ "UIDREQUIRED"
       def resp_text_code
         name = resp_text_code__name
         data =
@@ -1830,6 +1971,7 @@ module Net
           when "HIGHESTMODSEQ"      then SP!; mod_sequence_value   # CONDSTORE
           when "MODIFIED"           then SP!; sequence_set         # CONDSTORE
           when "MAILBOXID"          then SP!; parens__objectid     # RFC8474: OBJECTID
+          when "UIDREQUIRED"        then                           # RFC9586: UIDONLY
           else
             SP? and text_chars_except_rbra
           end
@@ -1859,11 +2001,10 @@ module Net
       #
       # n.b, uniqueid ⊂ uid-set.  To avoid inconsistent return types, we always
       # match uid_set even if that returns a single-member array.
-      #
       def resp_code_apnd__data
         validity = number; SP!
         dst_uids = uid_set # uniqueid ⊂ uid-set
-        UIDPlusData.new(validity, nil, dst_uids)
+        AppendUID(validity, dst_uids)
       end
 
       # already matched:  "COPYUID"
@@ -1873,7 +2014,25 @@ module Net
         validity = number;  SP!
         src_uids = uid_set; SP!
         dst_uids = uid_set
-        UIDPlusData.new(validity, src_uids, dst_uids)
+        CopyUID(validity, src_uids, dst_uids)
+      end
+
+      def AppendUID(...) DeprecatedUIDPlus(...) || AppendUIDData.new(...) end
+      def CopyUID(...)   DeprecatedUIDPlus(...) || CopyUIDData.new(...)   end
+
+      # TODO: remove this code in the v0.6.0 release
+      def DeprecatedUIDPlus(validity, src_uids = nil, dst_uids)
+        return unless config.parser_use_deprecated_uidplus_data
+        compact_uid_sets = [src_uids, dst_uids].compact
+        count = compact_uid_sets.map { _1.count_with_duplicates }.max
+        max   = config.parser_max_deprecated_uidplus_data_size
+        if count <= max
+          src_uids &&= src_uids.each_ordered_number.to_a
+          dst_uids   = dst_uids.each_ordered_number.to_a
+          UIDPlusData.new(validity, src_uids, dst_uids)
+        elsif config.parser_use_deprecated_uidplus_data != :up_to_max_size
+          parse_error("uid-set is too large: %d > %d", count, max)
+        end
       end
 
       ADDRESS_REGEXP = /\G
@@ -1999,15 +2158,9 @@ module Net
       #      uniqueid        = nz-number
       #                          ; Strictly ascending
       def uid_set
-        token = match(T_NUMBER, T_ATOM)
-        case token.symbol
-        when T_NUMBER then [Integer(token.value)]
-        when T_ATOM
-          token.value.split(",").flat_map {|range|
-            range = range.split(":").map {|uniqueid| Integer(uniqueid) }
-            range.size == 1 ? range : Range.new(range.min, range.max).to_a
-          }
-        end
+        set = sequence_set
+        parse_error("uid-set cannot contain '*'") if set.include_star?
+        set
       end
 
       def nil_atom

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

@@ -5,7 +5,7 @@ module Net
     module SASL
 
       # Authenticator for the "+ANONYMOUS+" SASL mechanism, as specified by
-      # RFC-4505[https://tools.ietf.org/html/rfc4505].  See
+      # RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  See
       # Net::IMAP#authenticate.
       class AnonymousAuthenticator
 
@@ -13,7 +13,7 @@ module Net
         # characters in length.
         #
         # If it contains an "@" sign, the message must be a valid email address
-        # (+addr-spec+ from RFC-2822[https://tools.ietf.org/html/rfc2822]).
+        # (+addr-spec+ from RFC-2822[https://www.rfc-editor.org/rfc/rfc2822]).
         # Email syntax is _not_ validated by AnonymousAuthenticator.
         #
         # Otherwise, it can be any UTF8 string which is permitted by the
@@ -25,7 +25,7 @@ module Net
         #   new(anonymous_message:  "", **) -> authenticator
         #
         # Creates an Authenticator for the "+ANONYMOUS+" SASL mechanism, as
-        # specified in RFC-4505[https://tools.ietf.org/html/rfc4505].  To use
+        # specified in RFC-4505[https://www.rfc-editor.org/rfc/rfc4505].  To use
         # this, see Net::IMAP#authenticate or your client's authentication
         # method.
         #

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