🔀 Merge pull request #98 from arnt/enable

Add support for ENABLE (RFC 5161)

Fixes #33.

Author: nevans

lib/net/imap.rb

@@ -199,8 +199,8 @@ module Net
   # [IDLE[https://tools.ietf.org/html/rfc2177]],
   # [NAMESPACE[https://tools.ietf.org/html/rfc2342]],
   # [UNSELECT[https://tools.ietf.org/html/rfc3691]],
+  # [ENABLE[https://tools.ietf.org/html/rfc5161]],
   #--
-  # TODO: [ENABLE[https://tools.ietf.org/html/rfc5161]],
   # TODO: [LIST-EXTENDED[https://tools.ietf.org/html/rfc5258]],
   # TODO: [LIST-STATUS[https://tools.ietf.org/html/rfc5819]],
   #++
@@ -257,11 +257,9 @@ module Net
   # In addition to the universal commands, the following commands are valid in
   # the "_authenticated_" state:
   #
-  #--
-  # - #enable: <em>Not implemented by Net::IMAP, yet.</em>
+  # - #enable: Enables backwards incompatible server extensions.
   #
   #   <em>Requires the +ENABLE+ capability.</em>
-  #++
   # - #select:  Open a mailbox and enter the "_selected_" state.
   # - #examine: Open a mailbox read-only, and enter the "_selected_" state.
   # - #create: Creates a new mailbox.
@@ -331,12 +329,11 @@ module Net
   #
   # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is <em>not supported
   # yet</em>, Net::IMAP supports several extensions that have been folded into
-  # it: +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
+  # it: +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
   #--
   # TODO: RFC4466, ABNF extensions (automatic support for other extensions)
   # TODO: +ESEARCH+, ExtendedSearchData
   # TODO: +SEARCHRES+,
-  # TODO: +ENABLE+,
   # TODO: +SASL-IR+,
   # TODO: +LIST-EXTENDED+,
   # TODO: +LIST-STATUS+,
@@ -435,6 +432,11 @@ module Net
   # TODO...
   #++
   #
+  # ==== RFC5161: +ENABLE+
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
+  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # - #enable: Enables backwards incompatible server extensions.
+  #
   #--
   # ==== RFC5182 +SEARCHRES+
   # TODO...
@@ -1879,6 +1881,32 @@ def uid_thread(algorithm, search_keys, charset)
       return thread_internal("UID THREAD", algorithm, search_keys, charset)
     end
 
+    # Sends an {ENABLE command [RFC5161 §3.2]}[https://www.rfc-editor.org/rfc/rfc5161#section-3.1]
+    # {[IMAP4rev2 §6.3.1]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.1]
+    # to enable the specified extenstions, which may be either an
+    # array or a string.  Returns a list of the extensions that were enabled.
+    #
+    # Some of the extensions that use ENABLE permit the server to send
+    # syntax that this class cannot parse. Caution is advised.
+    #
+    # The +ENABLE+ command is only valid in the _authenticated_ state, before
+    # any mailbox is selected.
+    #
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +ENABLE+
+    # [RFC5161[https://tools.ietf.org/html/rfc5161]] or IMAP4REV2
+    # [RFC9051[https://tools.ietf.org/html/rfc9051]].
+    #
+    # Additionally, the server capabilities must include a capability matching
+    # each enabled extension (usually the same name as the enabled extension).
+    def enable(extensions)
+      synchronize do
+        send_command("ENABLE #{[extensions].flatten.join(' ')}")
+        return @responses.delete("ENABLED")[-1]
+      end
+    end
+
     # Sends an {IDLE command [RFC2177 §3]}[https://www.rfc-editor.org/rfc/rfc6851#section-3]
     # {[IMAP4rev2 §6.3.13]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.13]
     # that waits for notifications of new or expunged messages.  Yields

lib/net/imap/response_parser.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "response_parser/parser_utils"
 
 module Net
   class IMAP < Protocol
 
     # Parses an \IMAP server response.
     class ResponseParser
+      include ParserUtils
+
       # :call-seq: Net::IMAP::ResponseParser.new -> Net::IMAP::ResponseParser
       def initialize
         @str = nil
@@ -96,6 +99,45 @@ def parse(str)
 
       Token = Struct.new(:symbol, :value)
 
+      # atom            = 1*ATOM-CHAR
+      #
+      # TODO: match atom entirely by regexp (in the "lexer")
+      def atom; -combine_adjacent(*ATOM_TOKENS) end
+
+      # the #accept version of #atom
+      def atom?; -combine_adjacent(*ATOM_TOKENS) if lookahead?(*ATOM_TOKENS) end
+
+      # Returns <tt>atom.upcase</tt>
+      def case_insensitive__atom; -combine_adjacent(*ATOM_TOKENS).upcase end
+
+      # Returns <tt>atom?&.upcase</tt>
+      def case_insensitive__atom?
+        -combine_adjacent(*ATOM_TOKENS).upcase if lookahead?(*ATOM_TOKENS)
+      end
+
+      # In addition to explicitly uses of +tagged-ext-label+, use this to match
+      # keywords when the grammar has not provided any extension syntax.
+      #
+      # Do *not* use this for labels where the grammar specifies extensions
+      # can be +atom+, even if all currently defined labels would match.  For
+      # example response codes in +resp-text-code+.
+      #
+      #   tagged-ext-label    = tagged-label-fchar *tagged-label-char
+      #                         ; Is a valid RFC 3501 "atom".
+      #   tagged-label-fchar  = ALPHA / "-" / "_" / "."
+      #   tagged-label-char   = tagged-label-fchar / DIGIT / ":"
+      #
+      # TODO: add to lexer and only match tagged-ext-label
+      alias tagged_ext_label  case_insensitive__atom
+      alias tagged_ext_label? case_insensitive__atom?
+
+      # Use #label or #label_in to assert specific known labels
+      # (+tagged-ext-label+ only, not +atom+).
+      def label(word)
+        (val = tagged_ext_label) == word and return val
+        parse_error("unexpected atom %p, expected %p instead", val, word)
+      end
+
       def response
         token = lookahead
         case token.symbol
@@ -157,9 +199,11 @@ def response_untagged
           when /\A(?:STATUS)\z/ni
             return status_response
           when /\A(?:CAPABILITY)\z/ni
-            return capability_response
+            return capability_data__untagged
           when /\A(?:NOOP)\z/ni
             return ignored_response
+          when /\A(?:ENABLED)\z/ni
+            return enable_data
           else
             return text_response
           end
@@ -967,29 +1011,38 @@ def status_response
         return UntaggedResponse.new(name, data, @str)
       end
 
-      def capability_response
-        token = match(T_ATOM)
-        name = token.value.upcase
-        match(T_SPACE)
-        UntaggedResponse.new(name, capability_data, @str)
+      # The presence of "IMAP4rev1" or "IMAP4rev2" is unenforced here.
+      # The grammar rule is used by both response-data and resp-text-code.
+      # But this method only returns UntaggedResponse (response-data).
+      #
+      # RFC3501:
+      #   capability-data  = "CAPABILITY" *(SP capability) SP "IMAP4rev1"
+      #                      *(SP capability)
+      # RFC9051:
+      #   capability-data  = "CAPABILITY" *(SP capability) SP "IMAP4rev2"
+      #                      *(SP capability)
+      def capability_data__untagged
+        UntaggedResponse.new label("CAPABILITY"), capability__list, @str
       end
 
-      def capability_data
-        data = []
-        while true
-          token = lookahead
-          case token.symbol
-          when T_CRLF, T_RBRA
-            break
-          when T_SPACE
-            shift_token
-            next
-          end
-          data.push(atom.upcase)
-        end
-        data
+      # enable-data   = "ENABLED" *(SP capability)
+      def enable_data
+        UntaggedResponse.new label("ENABLED"), capability__list, @str
+      end
+
+      # As a workaround for buggy servers, allow a trailing SP:
+      #     *(SP capapility) [SP]
+      def capability__list
+        data = []; while _ = SP? && capability? do data << _ end; data
       end
 
+      # capability      = ("AUTH=" auth-type) / atom
+      #                     ; New capabilities MUST begin with "X" or be
+      #                     ; registered with IANA as standard or
+      #                     ; standards-track
+      alias capability  case_insensitive__atom
+      alias capability? case_insensitive__atom?
+
       def id_response
         token = match(T_ATOM)
         name = token.value.upcase
@@ -1125,7 +1178,7 @@ def resp_text_code
         when /\A(?:BADCHARSET)\z/n
           result = ResponseCode.new(name, charset_list)
         when /\A(?:CAPABILITY)\z/ni
-          result = ResponseCode.new(name, capability_data)
+          result = ResponseCode.new(name, capability__list)
         when /\A(?:PERMANENTFLAGS)\z/n
           match(T_SPACE)
           result = ResponseCode.new(name, flag_list)
@@ -1321,10 +1374,6 @@ def case_insensitive_string
         T_PLUS
       ]
 
-      def atom
-        -combine_adjacent(*ATOM_TOKENS)
-      end
-
       # ASTRING-CHAR    = ATOM-CHAR / resp-specials
       # resp-specials   = "]"
       ASTRING_CHARS_TOKENS = [*ATOM_TOKENS, T_RBRA]
@@ -1396,12 +1445,18 @@ def nil_atom
       # This advances @pos directly so it's safe before changing @lex_state.
       def accept_space
         if @token
-          shift_token if @token.symbol == T_SPACE
+          if @token.symbol == T_SPACE
+            shift_token
+            " "
+          end
         elsif @str[@pos] == " "
           @pos += 1
+          " "
         end
       end
 
+      alias SP? accept_space
+
       # The RFC is very strict about this and usually we should be too.
       # But skipping spaces is usually a safe workaround for buggy servers.
       #
@@ -1413,46 +1468,6 @@ def accept_spaces
         end
       end
 
-      def match(*args, lex_state: @lex_state)
-        if @token && lex_state != @lex_state
-          parse_error("invalid lex_state change to %s with unconsumed token",
-                      lex_state)
-        end
-        begin
-          @lex_state, original_lex_state = lex_state, @lex_state
-          token = lookahead
-          unless args.include?(token.symbol)
-            parse_error('unexpected token %s (expected %s)',
-                        token.symbol.id2name,
-                        args.collect {|i| i.id2name}.join(" or "))
-          end
-          shift_token
-          return token
-        ensure
-          @lex_state = original_lex_state
-        end
-      end
-
-      # like match, but does not raise error on failure.
-      #
-      # returns and shifts token on successful match
-      # returns nil and leaves @token unshifted on no match
-      def accept(*args)
-        token = lookahead
-        if args.include?(token.symbol)
-          shift_token
-          token
-        end
-      end
-
-      def lookahead
-        @token ||= next_token
-      end
-
-      def shift_token
-        @token = nil
-      end
-
       def next_token
         case @lex_state
         when EXPR_BEG

lib/net/imap/response_parser/parser_utils.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+    class ResponseParser
+      # basic utility methods for parsing.
+      #
+      # (internal API, subject to change)
+      module ParserUtils # :nodoc:
+
+        private
+
+        def match(*args, lex_state: @lex_state)
+          if @token && lex_state != @lex_state
+            parse_error("invalid lex_state change to %s with unconsumed token",
+                        lex_state)
+          end
+          begin
+            @lex_state, original_lex_state = lex_state, @lex_state
+            token = lookahead
+            unless args.include?(token.symbol)
+              parse_error('unexpected token %s (expected %s)',
+                          token.symbol.id2name,
+                          args.collect {|i| i.id2name}.join(" or "))
+            end
+            shift_token
+            return token
+          ensure
+            @lex_state = original_lex_state
+          end
+        end
+
+        # like match, but does not raise error on failure.
+        #
+        # returns and shifts token on successful match
+        # returns nil and leaves @token unshifted on no match
+        def accept(*args)
+          token = lookahead
+          if args.include?(token.symbol)
+            shift_token
+            token
+          end
+        end
+
+        # like accept, without consuming the token
+        def lookahead?(*symbols)
+          @token if symbols.include?((@token ||= next_token)&.symbol)
+        end
+
+        def lookahead
+          @token ||= next_token
+        end
+
+        def shift_token
+          @token = nil
+        end
+      end
+    end
+  end
+end