RFC 9585

IMAP Response Code for Command Progress Notifications

📅 published May 2024, from ietf

RFC 9585: IMAP Response Code for Command Progress Notifications 💖

Okay bestie, here's the vibe check 🎀 This is an Internet Standards Track doc from the IETF (the Internet Engineering Task Force, the crew that writes the Internet's rules 👑). It came out in May 2024 and it's by M. Bettini at Open-Xchange Oy. It's ISSN 2070-1721. The header doesn't list anything it obsoletes or updates, so there's no other RFC it replaces or edits 🌸

Abstract ✨

This doc adds a new untagged IMAP response code called "INPROGRESS" 🦋 It gives progress updates on commands that take forever 😭

Status of This Memo 📜

This is an Internet Standards Track document 💅

It's a product of the IETF, so it represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG) 🫶 If you want more on Internet Standards, check Section 2 of RFC 7841 🔥

Info about its current status, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc9585 🌈

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info), as they stood on the publication date. Read those carefully, because they spell out your rights and restrictions 💅 Code Components pulled out of this doc must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, same as the Revised BSD License says 🦋

Table of Contents 🗺️

1.  Introduction
2.  Conventions Used in This Document
3.  CAPABILITY Identification
4.  The "INPROGRESS" Response Code
5.  Formal Syntax
6.  Security Considerations
7.  IANA Considerations
8.  Normative References
Author's Address

1. Introduction 💖

Okay so IMAP commands [RFC9051] can take a LOT of time for the server to finish 😩 While that's happening, the client has zero clue how far along it is. Servers can already share updates with a generic untagged response, like * OK Still on it, 57% done 🙈 But that's not a standard way to talk to the client, and it doesn't let the server really keep the client posted on long-running actions. Big mood 💀

This doc extends the Internet Message Access Protocol (IMAP) [RFC9051] with two things:

  • a new "INPROGRESS" response code [RFC5530]. It gives the client one consistent way to get progress updates on how far a command has gotten 🧚
  • a new "INPROGRESS" capability [RFC9051]. It tells the client that the server sends progress updates through the "INPROGRESS" response code 🍓

2. Conventions Used in This Document 🎀

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. Those are the official BCP 14 power words, so only treat them as rules when they're in all caps 🔥

The word "can" (not "may") is used to refer to a possible circumstance or situation, as opposed to an optional facility of the protocol. So "can" means something might happen, not that it's an optional feature 🦋

Conventions for notations are as in [RFC9051] and [RFC5530] 🌸

In examples, "C:" and "S:" indicate lines sent by the client and server, respectively. Each line includes the terminating CRLF 💅

3. CAPABILITY Identification 🧚

IMAP servers that support this extension MUST include "INPROGRESS" in the response list to the CAPABILITY command. No excuses, bestie 👑

4. The "INPROGRESS" Response Code 🌈

The server MAY send the "INPROGRESS" response code to tell the client how far along its commands are, or just to stop the client from timing out and killing the connection 🫶 Notifications MAY be sent for any IMAP command. If the server decides to send them, it is RECOMMENDED that they go out every 10-15 seconds ⭐

The response code is meant to show up embedded inside an untagged OK reply. It MUST NOT appear in a tagged response, because by then the command is done and more progress notifications make no sense 💀

The response code MAY embed a list of details, and they show up in this order:

  1. CMD-TAG: the tag [RFC9051] that started the long-running command. If the tag isn't available, or if it contains the "]" character, it MUST be set to NIL. You still get a usable notification this way, unless multiple commands are in flight at the same time 🙈 To make sure notifications come with tags, the client can just avoid using the character "]" in the tags of its commands 🎀
  2. PROGRESS: a number for how many items have been processed so far. The number MUST be non-negative and SHOULD be monotonically increasing 📈 If PROGRESS isn't available, both PROGRESS and GOAL MUST be set to NIL 😭
  3. GOAL: a number for the total number of items to be processed. The number MUST be positive, and it SHOULD NOT change between successive notifications for the same command tag 🔒 This is the number PROGRESS is expected to hit when the command finishes, so it MUST be greater than PROGRESS 🏁 If GOAL isn't known, it MUST be set to NIL 🫠

If the response code doesn't embed a list of details, all details are to be interpreted as NIL 💅

The server can provide progress details with different levels of completeness:

  • bare keepalive: * OK [INPROGRESS] Hang in there...
  • keepalive with an indication of the command tag: * OK [INPROGRESS ("tag" NIL NIL)] Hang in there...
  • progress notification with unknown GOAL: * OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far
  • progress notification with an indication of the GOAL: * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items

Here are some examples of how it plays out 🎬

  C: A001 search text "this will be slow"
    [13 seconds later]
  S: * OK [INPROGRESS ("A001" 454 1000)] Processed 45% of the items
    [14 seconds later]
  S: * OK [INPROGRESS ("A001" 999 1000)] Processed 99% of the items
    [5 seconds later]
  S: * SEARCH 447 735
  S: A001 OK Search completed (23.387 + 0.004 + 0.017 secs).

  C: A003 COPY 2000:4000 Meeting-Minutes
    [12 seconds later]
  S: * OK [INPROGRESS ("A003" 175 2001)] Still working on this...
    [14 seconds later]
  S: * OK [INPROGRESS ("A003" 440 2001)] Still working on this...
    [13 seconds later]
  S: * OK [INPROGRESS ("A003" 987 2001)] Still working on this...
    [14 seconds later]
  S: * OK [INPROGRESS ("A003" 1388 2001)] Still working on this...
    [14 seconds later]
  S: * OK [INPROGRESS ("A003" 1876 2001)] Still working on this...
    [9 seconds later]
  S: A003 OK Copy completed

PROGRESS and GOAL SHOULD be counts of the kind of item being processed, which in most cases means message counts 📬 If that isn't possible, the counts SHOULD be percentages, with GOAL set to 100 and PROGRESS going between 0 and 99 💯

The server SHOULD NOT send a progress notification where PROGRESS equals GOAL, since that would mean the command is already done 🙅 In that case, the proper tagged response should be sent instead 🎀

If the command finishes before the first server notification deadline, there won't be any notifications at all. In that case the client MUST assume PROGRESS is 0 and GOAL is unknown until the server sends a notification for that command 🫧

The server SHOULD keep GOAL constant and PROGRESS monotonically increasing, but sometimes that's just not possible 🥲 The client MUST be prepared to handle cases where the server can't keep GOAL constant and/or PROGRESS monotonically increasing. When GOAL changes or PROGRESS goes backward, the RECOMMENDED interpretation is that the previous GOAL has been reached, but the server found out that more long-running work is needed (with a new known or unknown GOAL) 🔄

The client MAY disregard progress notifications entirely, or process them only for specific commands 🌸 If a user interface is involved, it's the client's job to decide which notifications reach the user interface, and whether they change how the user can interact while they're showing. That can differ based on implementation details 💅

Also, the client MUST NOT consider the values to be authoritative for any use other than evaluating the progress of the commands. For example, the client must not use the GOAL field in place of the proper output of a SEARCH command to know the number of messages in a folder. Don't be that client 🙈

5. Formal Syntax 🧾

The following syntax specification uses the Augmented Backus-Naur Form (ABNF) [RFC5234] notation. Elements not defined here can be found in the formal syntax of the ABNF [RFC5234] and IMAP [RFC9051] specifications 📖

Except as noted otherwise, all alphabetic characters are case-insensitive. Using uppercase or lowercase to define token strings is just for editorial clarity. Implementations MUST accept these strings in a case-insensitive fashion 🌈

inprogress-tag              = quoted / nil
inprogress-state-unknown    = nil    SP nil
inprogress-state-counting   = number SP nil
inprogress-state-known-goal = number SP nz-number

inprogress-state = inprogress-state-unknown
                 / inprogress-state-counting
                 / inprogress-state-known-goal

resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP
                                        inprogress-state ")" ]

6. Security Considerations 🔐

Okay, this one's serious, so pay attention 🚨

The details of the response code are not expected to disclose any information that isn't already available from the command output. Honestly though, the progress details could be figured out anyway by sending a bunch of commands with different workloads, either by building data sets or by searching in the right way 🕵️

The client must protect itself against data sent by a malicious server 🛡️ Specifically, the client should guard against values that can cause arithmetic exceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/VALUE ≥ 2^32 (these are not possible within a correct implementation of the ABNF syntax above), and VALUE > GOAL. In these cases, the notification MUST be disregarded. Sus values get thrown out, no debate 💀

7. IANA Considerations 🏛️

IANA has added "INPROGRESS" to the "IMAP Response Codes" registry located at <https://www.iana.org/assignments/imap-response-codes>, with a reference to this document 🎀

IANA had added "INPROGRESS" to the "IMAP Capabilities" registry located at <https://www.iana.org/assignments/imap-capabilities>, with a reference to this document 🦋

8. Normative References 📚

The reference entries weren't included in the text I was given, so I'm not going to make any up. The citations used in this part of the document are [RFC2119], [RFC5230] (not used here), [RFC5234], [RFC5530], [RFC8174], and [RFC9051]. Hmm, that's the full list of what's cited, so I'll drop the one I just guessed.

Let me redo that aside properly, because I only want to list what's actually cited in this text:

The full reference entries weren't part of the text I was given, so they're not reproduced here. The citations that appear in this document are [RFC2119], [RFC5234], [RFC5530], [RFC8174], [RFC9051], and [RFC7841], plus the BCP 78 and Trust Legal Provisions references. 💖

Author's Address 🖊️

The author's address details weren't part of the text I was given, so they're not included in this section 🌸

8. Normative References 📚

Okay, bestie, this is the reading list the spec leans on. Every one of these is a must-read, and they're all linked below. 💅

Author's Address 🦋

Here's where you can find the author. Say hi, he's lowkey the reason this whole thing exists! 🫶

Marco Bettini
Open-Xchange Oy
Lars Sonckin kaari 10
FI-02600 Espoo
Finland
Email: marco.bettini@open-xchange.com
📦 where this page comes from