🔀 Merge pull request #226 from nevans/OBJECTID-extension

nevans · web-flow · commit fde2df90b9fe · 2023-11-13T01:04:56.000-05:00
✨ Add support for `OBJECTID` extension (RFC8474)
diff --git a/lib/net/imap.rb b/lib/net/imap.rb
@@ -492,7 +492,7 @@ module Net
   # - #xlist: replaced by +SPECIAL-USE+ attributes in #list responses.
   #
   # *NOTE:* The +OBJECTID+ extension should replace +X-GM-MSGID+ and
-  # +X-GM-THRID+, although neither Gmail nor Net::IMAP support it yet.
+  # +X-GM-THRID+, but Gmail does not support it (as of 2023-11-10).
   #
   # ==== RFC6851: +MOVE+
   # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051] and also included
@@ -504,6 +504,13 @@ module Net
   #
   # - See #enable for information about support for UTF-8 string encoding.
   #
+  # ==== RFC8474: +OBJECTID+
+  # - Adds +MAILBOXID+ ResponseCode to #create tagged response.
+  # - Adds +MAILBOXID+ ResponseCode to #select and #examine untagged response.
+  # - Updates #fetch and #uid_fetch with the +EMAILID+ and +THREADID+ items.
+  #   See FetchData#emailid and FetchData#emailid.
+  # - Updates #status with support for the +MAILBOXID+ status attribute.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::
@@ -1683,21 +1690,52 @@ def lsub(refname, mailbox)
 
     # Sends a {STATUS commands [IMAP4rev1 §6.3.10]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.10]
     # and returns the status of the indicated +mailbox+. +attr+ is a list of one
-    # or more attributes whose statuses are to be requested.  Supported
-    # attributes include:
+    # or more attributes whose statuses are to be requested.
+    #
+    # The return value is a hash of attributes.
+    #
+    # A Net::IMAP::NoResponseError is raised if status values
+    # for +mailbox+ cannot be returned; for instance, because it
+    # does not exist.
+    #
+    # ===== Supported attributes:
+    #
+    # +MESSAGES+::    The number of messages in the mailbox.
+    #
+    # +UIDNEXT+::     The next unique identifier value of the mailbox.
+    #
+    # +UIDVALIDITY+:: The unique identifier validity value of the mailbox.
+    #
+    # +UNSEEN+::      The number of messages without the <tt>\Seen</tt> flag.
     #
-    # MESSAGES:: the number of messages in the mailbox.
-    # RECENT:: the number of recent messages in the mailbox.
-    # UNSEEN:: the number of unseen messages in the mailbox.
+    # +DELETED+::     The number of messages with the <tt>\Deleted</tt> flag.
     #
-    # The return value is a hash of attributes. For example:
+    # +SIZE+::
+    #     The approximate size of the mailbox---must be greater than or equal to
+    #     the sum of all messages' +RFC822.SIZE+ fetch item values.
+    #
+    # +MAILBOXID+::
+    #     A server-allocated unique identifier for the mailbox.
+    #     See +OBJECTID+
+    #     {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-4].
+    #
+    # +RECENT+::
+    #     The number of messages with the <tt>\Recent</tt> flag.
+    #     _NOTE:_ +RECENT+ was removed from IMAP4rev2.
+    #
+    # ===== For example:
     #
     #   p imap.status("inbox", ["MESSAGES", "RECENT"])
     #   #=> {"RECENT"=>0, "MESSAGES"=>44}
     #
-    # A Net::IMAP::NoResponseError is raised if status values
-    # for +mailbox+ cannot be returned; for instance, because it
-    # does not exist.
+    # ===== Capabilities
+    #
+    # +SIZE+ requires the server's capabilities to include either +IMAP4rev2+ or
+    # <tt>STATUS=SIZE</tt>
+    # {[RFC8483]}[https://www.rfc-editor.org/rfc/rfc8483.html].
+    #
+    # +MAILBOXID+ requires the server's capabilities to include +OBJECTID+
+    # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
     def status(mailbox, attr)
       synchronize do
         send_command("STATUS", mailbox, attr)
diff --git a/lib/net/imap/fetch_data.rb b/lib/net/imap/fetch_data.rb
@@ -53,7 +53,11 @@ class IMAP < Protocol
     # * <b><tt>"RFC822.TEXT"</tt></b> --- See #rfc822_text or replace with
     #   <tt>"BODY[TEXT]"</tt> and #text.
     #
-    # Net::IMAP supports dynamic attributes defined by the following extensions:
+    # Net::IMAP supports static attributes defined by the following extensions:
+    # * +OBJECTID+ {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html]
+    #   * <b><tt>"EMAILID"</tt></b> --- See #emailid.
+    #   * <b><tt>"THREADID"</tt></b> --- See #threadid.
+    #
     # * +X-GM-EXT-1+ {[non-standard Gmail
     #   extension]}[https://developers.google.com/gmail/imap/imap-extensions]
     #   * <b><tt>"X-GM-MSGID"</tt></b> --- unique message ID.  Access via #attr.
@@ -462,6 +466,40 @@ def binary_size(*part_nums)
       #   identified message.
       def modseq; attr["MODSEQ"] end
 
+      # :call-seq: emailid -> string or nil
+      #
+      # An ObjectID that uniquely identifies the immutable content of a single
+      # message.
+      #
+      # The server must return the same +EMAILID+ for both the source and
+      # destination messages after a COPY or MOVE command.  However, it is
+      # possible for different messages with the same EMAILID to have different
+      # mutable attributes, such as flags.
+      #
+      # This is the same as getting the value for <tt>"EMAILID"</tt> from
+      # #attr.
+      #
+      # The server must support the +OBJECTID+ extension
+      # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
+      def emailid; attr["EMAILID"] end
+
+      # :call-seq: threadid -> string or nil
+      #
+      # An ObjectID that uniquely identifies a set of messages that the server
+      # believes should be grouped together.
+      #
+      # It is generally based on some combination of References, In-Reply-To,
+      # and Subject, but the exact implementation is left up to the server
+      # implementation.  The server should return the same thread identifier for
+      # related messages, even if they are in different mailboxes.
+      #
+      # This is the same as getting the value for <tt>"THREADID"</tt> from
+      # #attr.
+      #
+      # The server must support the +OBJECTID+ extension
+      # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
+      def threadid; attr["THREADID"] end
+
       private
 
       def body_section_attr(...) section_attr("BODY", ...) end
diff --git a/lib/net/imap/response_data.rb b/lib/net/imap/response_data.rb
@@ -256,6 +256,10 @@ class ResponseText < Struct.new(:code, :text)
     # * +ALREADYEXISTS+
     # * +NONEXISTENT+
     #
+    # Other supported \IMAP extension response codes:
+    # * +OBJECTID+ {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-7]
+    #   * +MAILBOXID+, #data will be a string
+    #
     class ResponseCode < Struct.new(:name, :data)
       ##
       # method: name
diff --git a/lib/net/imap/response_parser.rb b/lib/net/imap/response_parser.rb
@@ -893,6 +893,8 @@ def msg_att(n)
             when "RFC822.HEADER"        then nstring            # not in rev2
             when "RFC822.TEXT"          then nstring            # not in rev2
             when "MODSEQ"               then parens__modseq     # CONDSTORE
+            when "EMAILID"              then parens__objectid   # OBJECTID
+            when "THREADID"             then nparens__objectid  # OBJECTID
             when "X-GM-MSGID"           then x_gm_id            # GMail
             when "X-GM-THRID"           then x_gm_id            # GMail
             when "X-GM-LABELS"          then x_gm_labels        # GMail
@@ -1587,6 +1589,7 @@ def status_att_val
           when "UIDVALIDITY"   then nz_number           # RFC3501, RFC9051
           when "RECENT"        then number              # RFC3501 (obsolete)
           when "SIZE"          then number64            # RFC8483, RFC9051
+          when "MAILBOXID"     then parens__objectid    # RFC8474
           else
             number? || ExtensionData.new(tagged_ext_val)
           end
@@ -1792,6 +1795,9 @@ def resp_text
       #   resp-text-code   =/ "HIGHESTMODSEQ" SP mod-sequence-value /
       #                       "NOMODSEQ" /
       #                       "MODIFIED" SP sequence-set
+      #
+      # RFC8474: OBJECTID
+      #   resp-text-code   =/ "MAILBOXID" SP "(" objectid ")"
       def resp_text_code
         name = resp_text_code__name
         data =
@@ -1811,6 +1817,7 @@ def resp_text_code
             "LIMIT", "OVERQUOTA", "ALREADYEXISTS", "NONEXISTENT", "CLOSED",
             "NOTSAVED", "UIDNOTSTICKY", "UNKNOWN-CTE", "HASCHILDREN"
           when "NOMODSEQ"           # CONDSTORE
+          when "MAILBOXID"          then SP!; parens__objectid     # RFC8474: OBJECTID
           else
             SP? and text_chars_except_rbra
           end
@@ -1976,6 +1983,15 @@ def charset; quoted? || atom end
 
       def parens__modseq; lpar; _ = permsg_modsequence; rpar; _ end
 
+      # RFC8474:
+      # objectid = 1*255(ALPHA / DIGIT / "_" / "-")
+      #         ; characters in object identifiers are case
+      #         ; significant
+      alias objectid atom
+
+      def parens__objectid; lpar; _ = objectid; rpar; _ end
+      def nparens__objectid; NIL? ? nil : parens__objectid end
+
       # RFC-4315 (UIDPLUS) or RFC9051 (IMAP4rev2):
       #      uid-set         = (uniqueid / uid-range) *("," uid-set)
       #      uid-range       = (uniqueid ":" uniqueid)
diff --git a/test/net/imap/fixtures/response_parser/rfc8474_objectid_responses.yml b/test/net/imap/fixtures/response_parser/rfc8474_objectid_responses.yml
@@ -0,0 +1,56 @@
+---
+:tests:
+  rfc8474_example_4.1_MAILBOXID_response_to_CREATE:
+    :response: "3 OK [MAILBOXID (F2212ea87-6097-4256-9d51-71338625)] Completed\r\n"
+    :expected: !ruby/struct:Net::IMAP::TaggedResponse
+      tag: '3'
+      name: OK
+      data: !ruby/struct:Net::IMAP::ResponseText
+        code: !ruby/struct:Net::IMAP::ResponseCode
+          name: MAILBOXID
+          data: F2212ea87-6097-4256-9d51-71338625
+        text: Completed
+      raw_data: "3 OK [MAILBOXID (F2212ea87-6097-4256-9d51-71338625)] Completed\r\n"
+
+  rfc8474_example_4.2_MAILBOXID_untagged_response_to_SELECT:
+    :response: "* OK [MAILBOXID (F2212ea87-6097-4256-9d51-71338625)] Ok\r\n"
+    :expected: !ruby/struct:Net::IMAP::UntaggedResponse
+      name: OK
+      data: !ruby/struct:Net::IMAP::ResponseText
+        code: !ruby/struct:Net::IMAP::ResponseCode
+          name: MAILBOXID
+          data: F2212ea87-6097-4256-9d51-71338625
+        text: Ok
+      raw_data: "* OK [MAILBOXID (F2212ea87-6097-4256-9d51-71338625)] Ok\r\n"
+
+  rfc8474_example_4.3_MAILBOXID_attribute_for_STATUS:
+    :response: "* STATUS foo (MAILBOXID (F2212ea87-6097-4256-9d51-71338625))\r\n"
+    :expected: !ruby/struct:Net::IMAP::UntaggedResponse
+      name: STATUS
+      data: !ruby/struct:Net::IMAP::StatusData
+        mailbox: foo
+        attr:
+          MAILBOXID: F2212ea87-6097-4256-9d51-71338625
+      raw_data: "* STATUS foo (MAILBOXID (F2212ea87-6097-4256-9d51-71338625))\r\n"
+
+  rfc8474_example_5.3_EMAILID_and_THREADID:
+    :response: "* 3 FETCH (EMAILID (M5fdc09b49ea703) THREADID (T11863d02dd95b5))\r\n"
+    :expected: !ruby/struct:Net::IMAP::UntaggedResponse
+      name: FETCH
+      data: !ruby/struct:Net::IMAP::FetchData
+        seqno: 3
+        attr:
+          EMAILID: M5fdc09b49ea703
+          THREADID: T11863d02dd95b5
+      raw_data: "* 3 FETCH (EMAILID (M5fdc09b49ea703) THREADID (T11863d02dd95b5))\r\n"
+
+  rfc8474_example_5.3_no_THREADID_support:
+    :response: "* 2 FETCH (EMAILID (M00000002) THREADID NIL)\r\n"
+    :expected: !ruby/struct:Net::IMAP::UntaggedResponse
+      name: FETCH
+      data: !ruby/struct:Net::IMAP::FetchData
+        seqno: 2
+        attr:
+          EMAILID: M00000002
+          THREADID:
+      raw_data: "* 2 FETCH (EMAILID (M00000002) THREADID NIL)\r\n"
diff --git a/test/net/imap/test_fetch_data.rb b/test/net/imap/test_fetch_data.rb
@@ -37,10 +37,20 @@ class FetchDataTest < Test::Unit::TestCase
   end
 
   test "#modseq returns MODSEQ value (RFC7162: CONDSTORE)" do
-    data = FetchData.new( 22222, {"MODSEQ" => 123_456_789})
+    data = FetchData.new(22222, {"MODSEQ" => 123_456_789})
     assert_equal(123_456_789, data.modseq)
   end
 
+  test "#emailid returns EMAILID value (RFC8474: OBJECTID)" do
+    data = FetchData.new(22222, {"EMAILID" => "THIS-IS-IT-01234"})
+    assert_equal "THIS-IS-IT-01234", data.emailid
+  end
+
+  test "#threadid returns THREADID value (RFC8474: OBJECTID)" do
+    data = FetchData.new(22222, {"THREADID" => "THAT-IS-THAT-98765"})
+    assert_equal "THAT-IS-THAT-98765", data.threadid
+  end
+
   test "simple RFC822 attrs accessors (deprecated by RFC9051)" do
     data = FetchData.new(
       22222, {
diff --git a/test/net/imap/test_imap_response_parser.rb b/test/net/imap/test_imap_response_parser.rb
@@ -90,6 +90,9 @@ def teardown
   # RFC 5256: THREAD response
   generate_tests_from fixture_file: "thread_responses.yml"
 
+  # RFC 8474: OBJECTID responses
+  generate_tests_from fixture_file: "rfc8474_objectid_responses.yml"
+
   ############################################################################
   # Workarounds or unspecified extensions:
   generate_tests_from fixture_file: "quirky_behaviors.yml"
