Merge pull request #69 from nevans/uidplus

Fix some UIDPLUS issues

Author: nevans

lib/net/imap.rb

@@ -434,20 +434,22 @@ def login(user, password)
     # Sends a SELECT command to select a +mailbox+ so that messages
     # in the +mailbox+ can be accessed.
     #
-    # After you have selected a mailbox, you may retrieve the
-    # number of items in that mailbox from <code>@responses["EXISTS"][-1]</code>,
-    # and the number of recent messages from <code>@responses["RECENT"][-1]</code>.
-    # Note that these values can change if new messages arrive
-    # during a session; see #add_response_handler for a way of
-    # detecting this event.
+    # After you have selected a mailbox, you may retrieve the number of items in
+    # that mailbox from <tt>imap.responses["EXISTS"][-1]</tt>, and the number of
+    # recent messages from <tt>imap.responses["RECENT"][-1]</tt>.  Note that
+    # these values can change if new messages arrive during a session or when
+    # existing messages are expunged; see #add_response_handler for a way to
+    # detect these events.
     #
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
     # exist or is for some reason non-selectable.
     #
-    # If the server supports the [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]
-    # extension it may return an additional "NO" response with a "UIDNOTSTICKY" response code
-    # indicating that the mailstore does not support persistent UIDs
-    # [1[https://www.rfc-editor.org/rfc/rfc4315.html#page-4]]:
+    # ==== Capabilities
+    #
+    # If [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]] is supported,
+    # the server may return an untagged "NO" response with a "UIDNOTSTICKY"
+    # response code indicating that the mailstore does not support persistent
+    # UIDs:
     #   @responses["NO"].last.code.name == "UIDNOTSTICKY"
     def select(mailbox)
       synchronize do
@@ -759,22 +761,24 @@ def status(mailbox, attr)
     # not exist (it is not created automatically), or if the flags,
     # date_time, or message arguments contain errors.
     #
-    # If the server supports the [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]
-    # extension it returns an array with the UIDVALIDITY and the assigned UID of the
-    # appended message.
+    # ==== Capabilities
+    #
+    # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
+    # supported, the server's response should include a +APPENDUID+ response
+    # code with the UIDVALIDITY of the destination mailbox and the assigned UID
+    # of the appended message.
+    #
+    #--
+    # TODO: add MULTIAPPEND support
+    #++
     def append(mailbox, message, flags = nil, date_time = nil)
       args = []
       if flags
         args.push(flags)
       end
       args.push(date_time) if date_time
       args.push(Literal.new(message))
-      synchronize do
-        resp = send_command("APPEND", mailbox, *args)
-        if resp.data.code && resp.data.code.name == "APPENDUID"
-          return resp.data.code.data
-        end
-      end
+      send_command("APPEND", mailbox, *args)
     end
 
     # Sends a CHECK command to request a checkpoint of the currently
@@ -818,8 +822,10 @@ def expunge
     #        #responses and this method returns them as an array of
     #        <em>sequence number</em> integers.
     #
-    # ==== Required capability
-    # +UIDPLUS+ - described in [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]].
+    # ==== Capability requirement
+    #
+    # +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] must be
+    # supported by the server.
     def uid_expunge(uid_set)
       synchronize do
         send_command("UID EXPUNGE", MessageSet.new(uid_set))
@@ -948,14 +954,21 @@ def uid_store(set, attr, flags)
     # a number, an array of numbers, or a Range object. The number is
     # a message sequence number.
     #
-    # If the server supports the  [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]
-    # extension it returns an array with the UIDVALIDITY, the UID set of the source messages
-    # and the assigned UID set of the copied messages.
+    # ==== Capabilities
+    #
+    # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
+    # supported, the server's response should include a +COPYUID+ response code
+    # with the UIDVALIDITY of the destination mailbox, the UID set of the source
+    # messages, and the assigned UID set of the moved messages.
     def copy(set, mailbox)
       copy_internal("COPY", set, mailbox)
     end
 
     # Similar to #copy, but +set+ contains unique identifiers.
+    #
+    # ==== Capabilities
+    #
+    # +UIDPLUS+ affects #uid_copy the same way it affects #copy.
     def uid_copy(set, mailbox)
       copy_internal("UID COPY", set, mailbox)
     end
@@ -965,18 +978,27 @@ def uid_copy(set, mailbox)
     # a number, an array of numbers, or a Range object. The number is
     # a message sequence number.
     #
-    # The MOVE extension is described in [EXT-MOVE[https://tools.ietf.org/html/rfc6851]].
+    # ==== Capabilities requirements
+    #
+    # +MOVE+ [RFC6851[https://tools.ietf.org/html/rfc6851]] must be supported by
+    # the server.
+    #
+    # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
+    # also supported, the server's response should include a +COPYUID+ response
+    # code with the UIDVALIDITY of the destination mailbox, the UID set of the
+    # source messages, and the assigned UID set of the moved messages.
     #
-    # If the server supports the [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]
-    # extension it returns an array with the UIDVALIDITY, the UID set of the source messages
-    # and the assigned UID set of the moved messages.
     def move(set, mailbox)
       copy_internal("MOVE", set, mailbox)
     end
 
     # Similar to #move, but +set+ contains unique identifiers.
     #
-    # The MOVE extension is described in [EXT-MOVE[https://tools.ietf.org/html/rfc6851]].
+    # ==== Capabilities requirements
+    #
+    # Same as #move: +MOVE+ [RFC6851[https://tools.ietf.org/html/rfc6851]] must
+    # be supported by the server.  +UIDPLUS+ also affects #uid_move the same way
+    # it affects #move.
     def uid_move(set, mailbox)
       copy_internal("UID MOVE", set, mailbox)
     end
@@ -1432,12 +1454,7 @@ def store_internal(cmd, set, attr, flags)
     end
 
     def copy_internal(cmd, set, mailbox)
-      synchronize do
-        resp = send_command(cmd, MessageSet.new(set), mailbox)
-        if resp.data.code && resp.data.code.name == "COPYUID"
-          return resp.data.code.data
-        end
-      end
+      send_command(cmd, MessageSet.new(set), mailbox)
     end
 
     def sort_internal(cmd, sort_keys, search_keys, charset)

lib/net/imap/response_data.rb

@@ -113,6 +113,65 @@ class ResponseText < Struct.new(:code, :text)
     class ResponseCode < Struct.new(:name, :data)
     end
 
+    # Net::IMAP::UIDPlusData represents the ResponseCode#data that accompanies
+    # the +APPENDUID+ and +COPYUID+ response codes.
+    #
+    # ==== Capability requirement
+    #
+    # The +UIDPLUS+ capability[rdoc-ref:Net::IMAP#capability] must be supported.
+    # A server that supports +UIDPLUS+ should send a UIDPlusData object inside
+    # every TaggedResponse returned by the append[rdoc-ref:Net::IMAP#append],
+    # copy[rdoc-ref:Net::IMAP#copy], move[rdoc-ref:Net::IMAP#move], {uid
+    # copy}[rdoc-ref:Net::IMAP#uid_copy], and {uid
+    # move}[rdoc-ref:Net::IMAP#uid_move] commands---unless the destination
+    # mailbox reports +UIDNOTSTICKY+.
+    #
+    #--
+    # TODO: support MULTIAPPEND
+    #++
+    #
+    # ==== References
+    #
+    # [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]]::
+    #   Crispin, M., "Internet Message Access Protocol (IMAP) - UIDPLUS
+    #   extension", RFC 4315, DOI 10.17487/RFC4315, December 2005,
+    #   <https://www.rfc-editor.org/info/rfc4315>.
+    #
+    class UIDPlusData < Struct.new(:uidvalidity, :source_uids, :assigned_uids)
+      ##
+      # method: uidvalidity
+      # :call-seq: uidvalidity -> nonzero uint32
+      #
+      # The UIDVALIDITY of the destination mailbox.
+
+      ##
+      # method: source_uids
+      # :call-seq: source_uids -> nil or an array of nonzero uint32
+      #
+      # The UIDs of the copied or moved messages.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+
+      ##
+      # method: assigned_uids
+      # :call-seq: assigned_uids -> an array of nonzero uint32
+      #
+      # The newly assigned UIDs of the copied, moved, or appended messages.
+      #
+      # Note:: This always returns an array, even when it contains only one UID.
+
+      ##
+      # :call-seq: uid_mapping -> nil or a hash
+      #
+      # Returns a hash mapping each source UID to the newly assigned destination
+      # UID.
+      #
+      # Note:: Returns +nil+ for Net::IMAP#append.
+      def uid_mapping
+        source_uids&.zip(assigned_uids)&.to_h
+      end
+    end
+
     # Net::IMAP::MailboxList represents contents of the LIST response.
     #
     #   mailbox_list    ::= "(" #("\Marked" / "\Noinferiors" /

lib/net/imap/response_parser.rb

@@ -1104,11 +1104,8 @@ def resp_text
       #                   "UNSEEN" SP nz-number /
       #                   atom [SP 1*<any TEXT-CHAR except "]">]
       #
-      # See https://datatracker.ietf.org/doc/html/rfc4315#section-6.4 for UIDPLUS extension
-      #
-      # resp-code-apnd  = "APPENDUID" SP nz-number SP append-uid
-      # resp-code-copy  = "COPYUID" SP nz-number SP uid-set SP uid-set
-      # resp-text-code  =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY"
+      # +UIDPLUS+ ABNF:: https://www.rfc-editor.org/rfc/rfc4315.html#section-4
+      #   resp-text-code  =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY"
       def resp_text_code
         token = match(T_ATOM)
         name = token.value.upcase
@@ -1126,19 +1123,9 @@ def resp_text_code
           match(T_SPACE)
           result = ResponseCode.new(name, number)
         when /\A(?:APPENDUID)\z/n
-          match(T_SPACE)
-          uidvalidity = number
-          match(T_SPACE)
-          append_uid = number
-          result = ResponseCode.new(name, [uidvalidity, append_uid])
+          result = ResponseCode.new(name, resp_code_apnd__data)
         when /\A(?:COPYUID)\z/n
-          match(T_SPACE)
-          uidvalidity = number
-          match(T_SPACE)
-          from_uid = uid_set
-          match(T_SPACE)
-          to_uid = uid_set
-          result = ResponseCode.new(name, [uidvalidity, from_uid, to_uid])
+          result = ResponseCode.new(name, resp_code_copy__data)
         else
           token = lookahead
           if token.symbol == T_SPACE
@@ -1165,6 +1152,34 @@ def charset_list
         result
       end
 
+      # already matched:  "APPENDUID"
+      #
+      # +UIDPLUS+ ABNF:: https://www.rfc-editor.org/rfc/rfc4315.html#section-4
+      #   resp-code-apnd  = "APPENDUID" SP nz-number SP append-uid
+      #   append-uid      = uniqueid
+      #   append-uid      =/ uid-set
+      #                     ; only permitted if client uses [MULTIAPPEND]
+      #                     ; to append multiple messages.
+      #
+      # 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
+        match(T_SPACE); validity = number
+        match(T_SPACE); dst_uids = uid_set # uniqueid ⊂ uid-set
+        UIDPlusData.new(validity, nil, dst_uids)
+      end
+
+      # already matched:  "COPYUID"
+      #
+      # resp-code-copy  = "COPYUID" SP nz-number SP uid-set SP uid-set
+      def resp_code_copy__data
+        match(T_SPACE); validity = number
+        match(T_SPACE); src_uids = uid_set
+        match(T_SPACE); dst_uids = uid_set
+        UIDPlusData.new(validity, src_uids, dst_uids)
+      end
+
       def address_list
         token = lookahead
         if token.symbol == T_NIL
@@ -1350,19 +1365,14 @@ def number
       #      uniqueid        = nz-number
       #                          ; Strictly ascending
       def uid_set
-        case lookahead.symbol
-        when T_NUMBER then [match(T_NUMBER).value.to_i]
+        token = match(T_NUMBER, T_ATOM)
+        case token.symbol
+        when T_NUMBER then [Integer(token.value)]
         when T_ATOM
-          match(T_ATOM).value.split(',').flat_map do |element|
-            if element.include?(':')
-              Range.new(*element.split(':').map(&:to_i)).to_a
-            else
-              element.to_i
-            end
-          end
-        else
-          shift_token
-          nil
+          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
       end
 

test/net/imap/test_imap.rb

@@ -848,16 +848,16 @@ def test_uidplus_responses
 
         hello world
       EOF
-      assert_equal(resp, [38505, 3955])
+      assert_equal([38505, nil, [3955]], resp.data.code.data.to_a)
       resp = imap.uid_copy([3955,3960..3962], 'trash')
       assert_equal(requests.pop, "RUBY0002 UID COPY 3955,3960:3962 trash\r\n")
       assert_equal(
-        resp,
-        [38505, [3955, 3960, 3961, 3962], [3963, 3964, 3965, 3966]]
+        [38505, [3955, 3960, 3961, 3962], [3963, 3964, 3965, 3966]],
+        resp.data.code.data.to_a
       )
       resp = imap.uid_copy(3955, 'trash')
       assert_equal(requests.pop, "RUBY0003 UID COPY 3955 trash\r\n")
-      assert_equal(resp, [38505, [3955], [3967]])
+      assert_equal([38505, [3955], [3967]], resp.data.code.data.to_a)
       imap.select('trash')
       assert_equal(
         imap.responses["NO"].last.code,