| RFC 9585 | IMAP Response Code for Command Progress | May 2024 |
| Bettini | Standards Track | [Page] |
This document defines a new IMAP untagged response code, "INPROGRESS", that provides progress notifications regarding the status of long-running commands.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc9585.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
IMAP commands[RFC9051]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 thecommands. It is already possible to expose updates with a generic untaggedresponse, like "* OK Still on it, 57% done"; however, this does not providea standard way to communicate with the client and does not allow the serverto inform the client of the progress of the long-running actions.¶
This document extends the Internet Message Access Protocol (IMAP)[RFC9051] with:¶
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.¶
The word "can" (not "may") is used to refer to a possiblecircumstance or situation, as opposed to an optional facility of theprotocol.¶
Conventions for notations are as in[RFC9051] and[RFC5530].¶
In examples, "C:" and "S:" indicate lines sent by the client andserver, respectively. Note that each line includes the terminating CRLF.¶
IMAP servers that support this extensionMUST include"INPROGRESS" in the response list to the CAPABILITY command.¶
The serverMAY send the "INPROGRESS" response code to notifythe client about the progress of the commands in execution or simply toprevent the client from timing out and terminating the connection.The notificationsMAY be sent for any IMAP command.If the server elects to send notifications, it isRECOMMENDEDthat these are sent every 10-15 seconds.¶
The response code is meant to appear embedded inside an untagged OK reply.The response codeMUST NOT appear in a tagged response(the command has completed and further progress notifications make no sense).¶
The response codeMAY embed a list of details, which appearin the following order:¶
If the response code does not embed a list of details, all details are tobe interpreted as NIL.¶
The server can provide the progress details with differentdegrees 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¶Examples:¶
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 GOALSHOULD be counts of the kind of itembeing processed -- in most cases, messages counts. If that is not possible,the countsSHOULD be percentages, with GOAL set to 100and PROGRESS varying between 0 and 99.¶
The serverSHOULD NOT send a progress notification wherePROGRESS equals GOAL, as that would mean the command is completed.In that case, the proper tagged response should be emitted instead.¶
If the command completes before the first server notification deadline,there will be no notifications at all. The clientMUSTassume PROGRESS to be 0 and GOAL to be unknown until the server issues anotification for the command.¶
While the serverSHOULD keep GOAL constant and PROGRESSmonotonically increasing, there are circumstances where this might notbe possible. The clientMUST be prepared to handle caseswhere the server cannot keep GOAL constant and/or PROGRESS monotonicallyincreasing. When the GOAL changes or the PROGRESS goes backward, theRECOMMENDED interpretation is that the previous GOAL hasbeen reached, but the server discovered that further (long-running) workis required (with a new known or unknown GOAL).¶
The clientMAY disregard progress notifications entirely orprocess them only in relation to specific commands. If a user interface isinvolved, it is the client's duty to decide which of these notifications should emerge to the user interface and/or modify the user'sability to interact in their presence, since this may differ based onimplementation details.¶
Also, the clientMUST NOT consider the values to be authoritativefor any other use than evaluating the progress of the commands.For example, the client must not use the GOAL field in place of the proper output of aSEARCH command to know the number of messages in a folder.¶
The following syntax specification uses the Augmented Backus-Naur Form(ABNF)[RFC5234] notation. Elements not defined here canbe found in the formal syntax of the ABNF[RFC5234] and IMAP[RFC9051] specifications.¶
Except as noted otherwise, all alphabetic characters are case-insensitive.The use of uppercase or lowercase characters to define token strings arefor editorial clarity only. ImplementationsMUST acceptthese strings in a case-insensitive fashion.¶
inprogress-tag = quoted / nilinprogress-state-unknown = nil SP nilinprogress-state-counting = number SP nilinprogress-state-known-goal = number SP nz-numberinprogress-state = inprogress-state-unknown / inprogress-state-counting / inprogress-state-known-goalresp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP inprogress-state ")" ]¶The details of the response code are not expected to disclose any informationthat isn't currently available from the command output. The progress detailscould be obtained anyway by sending a series of commands with differentworkloads -- by either constructing data sets or searching in the appropriateway.¶
The client must protect itself against data sent by a malicious server.Specifically, the client should guard against values that can cause arithmeticexceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/VALUE ≥ 232(these are not possible within a correct implementation of the ABNF syntaxabove), and VALUE > GOAL. In these cases, the notificationMUSTbe disregarded.¶
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.¶