✨ Add STATUS MAILBOXID (RFC8474, OBJECTID)

Previously, any number-type status values worked—which is most of them. This adds support for `MAILBOXID` (needed for the `OBJECTID` extension).
ruby · Nov 13, 2023 · 7a44de3 · 7a44de3
1 parent 36f1381
commit 7a44de3
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 11 deletions.
diff --git a/lib/net/imap.rb b/lib/net/imap.rb
@@ -509,8 +509,7 @@ module Net
   # - 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.
-  # >>>
-  #   *NOTE: The +MAILBOXID+ attribute for #status is not supported yet.
+  # - Updates #status with support for the +MAILBOXID+ status attribute.
   #
   # == References
   #
@@ -1691,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/response_parser.rb b/lib/net/imap/response_parser.rb
@@ -1589,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

diff --git a/test/net/imap/fixtures/response_parser/rfc8474_objectid_responses.yml b/test/net/imap/fixtures/response_parser/rfc8474_objectid_responses.yml
@@ -23,6 +23,16 @@
         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