Open-Xchange Oy

Lars Sonckin kaari 10 02600 Espoo Finland marco.bettini@open-xchange.com

ART extra IMAP response code This document defines a new IMAP untagged response code, "INPROGRESS", that provides progress notifications regarding the status of long-running commands.

Status of This Memo 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 at .

Copyright Notice 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 () 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.

Table of Contents

• .  Introduction
• .  Conventions Used in This Document
• .  CAPABILITY Identification
• .  The "INPROGRESS" Response Code
• .  Formal Syntax
• .  Security Considerations
• .  IANA Considerations
• .  Normative References
• Author's Address

Introduction 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 does not allow the server to inform the client 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 a consistent means for a client to receive progress notifications on command completion status.
• a new "INPROGRESS" capability . The new capability informs the client that the server emits progress notifications via the "INPROGRESS" response code.

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

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

The "INPROGRESS" Response Code 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 (the command has completed and further progress notifications make no sense). The response code MAY embed a list of details, which appear in the following order:

1. CMD-TAG: the tag that originated the long-running command. If the tag is not available or if it contains the "]" character, it MUST be set to NIL. This still produces a usable notification, unless multiple commands are in flight simultaneously. A client can ensure reception of notifications with tags by simply refraining from the use of the character "]" in the originating command tags.
2. PROGRESS: a number indicating the number of items processed so far. The number MUST be non-negative and SHOULD be monotonically increasing. If the PROGRESS is not available, both PROGRESS and GOAL MUST be set to NIL.
3. GOAL: a number indicating 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 that PROGRESS is expected to reach after the completion of the command; therefore, it MUST be greater than PROGRESS. If the GOAL is not known, it MUST be set to NIL.

If the response code does not embed a list of details, all details are to be interpreted as NIL. The server can provide the progress details with different degrees 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 GOAL SHOULD be counts of the kind of item being processed -- in most cases, messages counts. If that is not possible, the counts SHOULD be percentages, with GOAL set to 100 and PROGRESS varying between 0 and 99. The server SHOULD NOT send a progress notification where PROGRESS 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 client MUST assume PROGRESS to be 0 and GOAL to be 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 (with a new known or unknown GOAL). The client MAY disregard progress notifications entirely or process them only in relation to specific commands. If a user interface is involved, it is the client's duty to decide which of these notifications should emerge to the user interface and/or modify the user's ability to interact in their presence, 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. 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.

Formal Syntax 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 and IMAP 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 = inprogress-state-unknown / inprogress-state-counting / inprogress-state-known-goal resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP inprogress-state ")" ]

Security Considerations The details of the response code are not expected to disclose any information that isn't currently available from the command output. The progress details could be obtained anyway by sending a series of commands with different workloads -- by either constructing data sets or searching in the appropriate 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³² (these are not possible within a correct implementation of the ABNF syntax above), and VALUE > GOAL. In these cases, the notification MUST be disregarded.

IANA Considerations IANA has added "INPROGRESS" to the "IMAP Response Codes" registry located at , with a reference to this document. IANA had added "INPROGRESS" to the "IMAP Capabilities" registry located at , with a reference to this document.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] IMAP responses consist of a response type (OK, NO, BAD), an optional machine-readable response code, and a human-readable text. This document collects and documents a variety of machine-readable response codes, for better interoperation and error reporting. [STANDARDS-TRACK] RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The Internet Message Access Protocol Version 4rev2 (IMAP4rev2) allows a client to access and manipulate electronic mail messages on a server. IMAP4rev2 permits manipulation of mailboxes (remote message folders) in a way that is functionally equivalent to local folders. IMAP4rev2 also provides the capability for an offline client to resynchronize with the server. IMAP4rev2 includes operations for creating, deleting, and renaming mailboxes; checking for new messages; removing messages permanently; setting and clearing flags; parsing per RFCs 5322, 2045, and 2231; searching; and selective fetching of message attributes, texts, and portions thereof. Messages in IMAP4rev2 are accessed by the use of numbers. These numbers are either message sequence numbers or unique identifiers. IMAP4rev2 does not specify a means of posting mail; this function is handled by a mail submission protocol such as the one specified in RFC 6409.

Author's Address Open-Xchange Oy

Lars Sonckin kaari 10 02600 Espoo Finland marco.bettini@open-xchange.com