IMAP4 Response Code for Command Progress Notifications.

Internet Message Access Protocol (IMAP) commands can require a considerable amount of time to be completed by the server. In these cases, the client has no information about the progress of the commands. It is already possible to expose updates with a generic untagged response, like "* OK Still on it, 57% done"; however, this does not provide a standard way to communicate with the client and allow it to inform the user of the progress of the long-running actions. This document extends the Internet Message Access Protocol (IMAP) with:

a new "INPROGRESS" response code . The new response code provides consistent means for a client to receive progress update notifications on command completion status.
a new "INPROGRESS" capability . The new capability informs the client that the server emits progress update notifications, via the "INPROGRESS" response code

"Conventions" are basic principles or procedures. Document conventions are noted in this section. 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 when, and only when, they appear in all capitals, as shown here. The word "can" (not "may") is used to refer to a possible circumstance or situation, as opposed to an optional facility of the protocol. Conventions for notations are as in and . In examples, "C:" and "S:" indicate lines sent by the client and server, respectively. Note that each line includes the terminating CRLF.

IMAP servers that support this extension MUST include "INPROGRESS" in the response list to the CAPABILITY command.

The server MAY send the "INPROGRESS" Response Code to notify the client about the progress of the commands in execution, or simply to prevent the client from timing out and terminating the connection. The notifications MAY be sent for any IMAP command. If the server elects to send notifications, it is RECOMMENDED that these are sent every 10...15 seconds. The response code is meant to appear embedded inside an untagged OK reply. The response code MUST NOT appear in a tagged response (as that implies the command has completed and that no further progress notifications are needed). The response code MAY embed a list of details, composed in order of:

CMD-TAG: the cmd-tag that originated the long-running command. If the tag is not available, or if it contains "]" characters, it MUST be replaced by NIL
PROGRESS: a number indicating the number of items processed so far. If the PROGRESS is not available, both PROGRESS and GOAL MUST be replaced by NIL.
GOAL: a number indicating the total number of items to be processed. This is the number that PROGRESS is expected to reach at the completion of the command. If the GOAL is not known, it MUST be replaced by NIL.

The server can provide the progress notifications details with different degrees of completeness: - bare keepalive * OK [INPROGRESS] Hang in there.. - keepalive with indication of the command tag * OK [INPROGRESS ("tag" NIL NIL)] Hang in there.. - progress indication with unknown GOAL * OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far - progress indication with the indication of the GOAL * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items Example: C: 001 search text very-long-to-complete ... time passes ... S: * OK [INPROGRESS ("001" 454 1000)] Processed 45% of the items ... time passes ... S: * OK [INPROGRESS ("001" 999 1000)] Processed 99% of the items ... time passes, but less than the threshold ... S: [...] actual results for the command S: 001 OK done If all the details are NIL, the whole details section MAY be omitted, i.e.: * OK [INPROGRESS (NIL NIL NIL)] Working on it can be replaced by: * OK [INPROGRESS] Working on it The cmd-tag detail MUST NOT contain "]". If that is the case, the server MUST replace the cmd-tag with NIL. This still produces a usable notification, unless multiple commands are in flight simultaneously. A client can ensure to receive notifications with cmd-tag(s) by simply refraining to embed the character "]" in the originating command tags. The PROGRESS number MUST be non-negative and SHOULD be monotonically increasing. The GOAL number MUST be positive when provided, and it SHOULD NOT change between successive notifications for the same command (i.e. for the same cmd-tag). PROGRESS and GOAL SHOULD be counts of the kind of item being processed - in most cases, message counts. If that is not possible, the counts SHOULD be percentages (progress varies from 0 to 99 and goal stays fixed at 100). In this case, the numbers are suffixed by "%" and the goal MUST be 100%. The command is completed when PROGRESS equals GOAL. In this case, the server SHOULD NOT send a progress notification but just the proper command completion. If the command isn't completed yet, PROGRESS MUST be strictly less than GOAL. If the command completes before the first server interval, there will be no notifications. The client MUST assume PROGRESS=0 and GOAL unknown until the server issues a notification for the command. While the server SHOULD keep GOAL constant and PROGRESS monotonically increasing, there are circumstances where this might not be possible. The client MUST be prepared to handle cases where the server cannot keep GOAL constant and/or PROGRESS monotonically increasing. When the GOAL changes or the PROGRESS goes backward, the RECOMMENDED interpretation is that the previous GOAL has been reached, but the server discovered that further (long-running) work is required (either with known or unknown new GOAL), The client MAY disregard progress notifications entirely or process them only in relation with specific commands. If a UI is involved, it is the client's duty to decide which of these commands are blocking on the user experience, since this may differ based on implementation details. Also, the client MUST NOT consider the values to be authoritative for any other use than evaluating the progress of the commands progress. E.g.: 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.

The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation. Elements not defined here can be found in the formal syntax of the ABNF , IMAP and IMAP ABNF extension specifications. Except as noted otherwise, all alphabetic characters are case-insensitive. The use of uppercase or lowercase characters to define token strings are for editorial clarity only. 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-percentage = number "%" SP "100" "%" inprogress-state = inprogress-state-unknown / inprogress-state-counting / inprogress-state-known-goal / inprogress-state-percentage resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP inprogress-state ")" ]

The details of the response code are not expected to disclose any information that isn't currently available from commands output. The progress details could be obtained anyway by a series of sending commands with different workloads - either by constructing data sets or searching in the appropriate way into them. 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.

IANA is requested to add "INPROGRESS" to the "IMAP Response Codes" registry located at <https://www.iana.org/assignments/imap-response-codes>, with a reference to this document. IANA is requested to add "INPROGRESS" to the "IMAP Capabilities" registry located at <https://www.iana.org/assignments/imap-capabilities>, with a reference to this document.