Open-Xchange Oy

Lars Sonckin Kaari 12 02600 Espoo Finland marco.bettini@open-xchange.com

General IMAP response code This document defines a new IMAP untagged response code, "INPROGRESS", that serves as a keepalive for the client and, optionally, provides numeric progress status indication.

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. Also, some clients may trigger timeouts if the server doesn't communicate within a certain time interval. While this is already possible with a generic untagged response, like "* OK Still working", this does not provide a standardized way to provide command status completion information to the client, which could be used to inform the client user of 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 updates on command completion status.

"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.

The "INPROGRESS" Response Code MAY be sent by the server to update the client on the progress of the execution of client's commands, or simply to prevent the client from timing out and terminating the connection. If the server elects to send updates, it SHOULD do 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 no further progress update is needed). The response code MAY embed a list of details, composed in order of:

1. OPTIONAL the cmd-tag that originated the long running command,
2. OPTIONAL a number indicating the PROGRESS,
3. OPTIONAL a number indicating the GOAL. This is the number that PROGRESS is expected to reach at the completion of the command (if known).

If a detail is not available, it MUST be replaced with 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 total (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, cmd-tag MUST be replaced by NIL. The GOAL number MUST be non-zero 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 - OR, if that is not possible, percentages (progress varies from 0 to 99 and goal stays fixed at 100). The command is completed when PROGRESS equals GOAL. In this case the 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.

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 is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion. resp-text-code =/ "INPROGRESS" [ SP "(" quoted / nil SP number / nil SP number / nil ")" ]

The details of response code are not expected disclose to the client any information that isn't already provided at the command completion. Also, the details are not expected to reveal any significant insight about the load of the server, which in case could anyway be inferred by the total completion time of the command.

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.