✨ Add fetch support for EMAILID and THREADID

These are the `msg-att` added by the `OBJECTID` extension.

Author: nevans

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,12 @@ module Net
   #
   # - See #enable for information about support for UTF-8 string encoding.
   #
+  # ==== RFC8474: +OBJECTID+
+  # - Updates #fetch and #uid_fetch with the +EMAILID+ and +THREADID+ items.
+  #   See FetchData#emailid and FetchData#emailid.
+  # >>>
+  #   *NOTE: The +MAILBOXID+ attribute for #status is not supported yet.
+  #
   # == References
   #
   # [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]]::

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

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
@@ -1976,6 +1978,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)

test/net/imap/fixtures/response_parser/rfc8474_objectid_responses.yml

@@ -0,0 +1,23 @@
+---
+:tests:
+  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"

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, {

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"