rfc9585.original   rfc9585.txt 
EXTRA M. Bettini Internet Engineering Task Force (IETF) M. Bettini
Internet-Draft Open-Xchange Oy Request for Comments: 9585 Open-Xchange Oy
Intended status: Standards Track 4 April 2024 Category: Standards Track May 2024
Expires: 6 October 2024 ISSN: 2070-1721
IMAP4 Response Code for Command Progress Notifications. IMAP Response Code for Command Progress Notifications
draft-ietf-extra-imap-inprogress-06
Abstract Abstract
This document defines a new IMAP untagged response code, This document defines a new IMAP untagged response code,
"INPROGRESS", that provides structured numeric progress status "INPROGRESS", that provides progress notifications regarding the
indication for long-running commands. status of long-running commands.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 6 October 2024. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9585.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2024 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction
2. Conventions Used in This Document . . . . . . . . . . . . . . 2 2. Conventions Used in This Document
3. CAPABILITY Identification . . . . . . . . . . . . . . . . . . 3 3. CAPABILITY Identification
4. The "INPROGRESS" Response Code . . . . . . . . . . . . . . . 3 4. The "INPROGRESS" Response Code
5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 5 5. Formal Syntax
6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. Security Considerations
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 7. IANA Considerations
8. Normative References . . . . . . . . . . . . . . . . . . . . 6 8. Normative References
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 Author's Address
1. Introduction 1. Introduction
Internet Message Access Protocol (IMAP) [RFC9051] commands can IMAP commands [RFC9051] can require a considerable amount of time to
require a considerable amount of time to be completed by the server. be completed by the server. In these cases, the client has no
In these cases, the client has no information about the progress of information about the progress of the commands. It is already
the commands. It is already possible to expose updates with a possible to expose updates with a generic untagged response, like "*
generic untagged response, like "* OK Still on it, 57% done"; OK Still on it, 57% done"; however, this does not provide a standard
however, this does not provide a standard way to communicate with the way to communicate with the client and does not allow the server to
client and allow it to inform the user of the progress of the long- inform the client of the progress of the long-running actions.
running actions.
This document extends the Internet Message Access Protocol (IMAP) This document extends the Internet Message Access Protocol (IMAP)
[RFC9051] with: [RFC9051] with:
* a new "INPROGRESS" response code [RFC5530]. The new response code * a new "INPROGRESS" response code [RFC5530]. The new response code
provides consistent means for a client to receive a progress provides a consistent means for a client to receive progress
update notifications on command completion status. notifications on command completion status.
* a new "INPROGRESS" capability [RFC9051]. The new capability * a new "INPROGRESS" capability [RFC9051]. The new capability
informs the client that the server emits progress update informs the client that the server emits progress notifications
notifications, via the "INPROGRESS" response code via the "INPROGRESS" response code.
2. Conventions Used in This Document 2. Conventions Used in This Document
"Conventions" are basic principles or procedures. Document
conventions are noted in this section.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
The word "can" (not "may") is used to refer to a possible The word "can" (not "may") is used to refer to a possible
circumstance or situation, as opposed to an optional facility of the circumstance or situation, as opposed to an optional facility of the
protocol. protocol.
Conventions for notations are as in [RFC9051] and [RFC5530]. Conventions for notations are as in [RFC9051] and [RFC5530].
In examples, "C:" and "S:" indicate lines sent by the client and In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. Note that each line includes the terminating server, respectively. Note that each line includes the terminating
CRLF. CRLF.
3. CAPABILITY Identification 3. CAPABILITY Identification
IMAP servers that support this extension MUST include "INPROGRESS" in IMAP servers that support this extension MUST include "INPROGRESS" in
the response list to the CAPABILITY command. the response list to the CAPABILITY command.
4. The "INPROGRESS" Response Code 4. The "INPROGRESS" Response Code
The server MAY send the "INPROGRESS" Response Code to notify the The server MAY send the "INPROGRESS" response code to notify the
client about the progress of the commands in execution, or simply to client about the progress of the commands in execution or simply to
prevent the client from timing out and terminating the connection. prevent the client from timing out and terminating the connection.
The notifications MAY be sent for any IMAP command. If the server The notifications MAY be sent for any IMAP command. If the server
elects to send notifications, it is RECOMMENDED that these are sent elects to send notifications, it is RECOMMENDED that these are sent
every 10-15 seconds. every 10-15 seconds.
The response code is meant to appear embedded inside an untagged OK The response code is meant to appear embedded inside an untagged OK
reply. The response code MUST NOT appear in a tagged response (the reply. The response code MUST NOT appear in a tagged response (the
command has completed and further progress notifications make no command has completed and further progress notifications make no
sense). sense).
The response code MAY embed a list of details, composed in order of: The response code MAY embed a list of details, which appear in the
following order:
1. CMD-TAG: the cmd-tag [RFC9051] that originated the long-running 1. CMD-TAG: the tag [RFC9051] that originated the long-running
command. If the tag is not available, or if it contains the "]" command. If the tag is not available or if it contains the "]"
character, it MUST be set to NIL. This still produces a usable character, it MUST be set to NIL. This still produces a usable
notification, unless multiple commands are in flight notification, unless multiple commands are in flight
simultaneously. A client can ensure reception of notifications simultaneously. A client can ensure reception of notifications
with cmd-tag(s) by simply refraining from the use of character with tags by simply refraining from the use of the character "]"
"]" in the originating command tags. in the originating command tags.
2. PROGRESS: a number indicating the number of items processed so 2. PROGRESS: a number indicating the number of items processed so
far. The number MUST be non-negative and SHOULD be monotonically far. The number MUST be non-negative and SHOULD be monotonically
increasing. If the PROGRESS is not available, both PROGRESS and increasing. If the PROGRESS is not available, both PROGRESS and
GOAL MUST be set to NIL. GOAL MUST be set to NIL.
3. GOAL: a number indicating the total number of items to be 3. GOAL: a number indicating the total number of items to be
processed. The number MUST be positive and it SHOULD NOT change processed. The number MUST be positive, and it SHOULD NOT change
between successive notifications for the same command (i.e. for between successive notifications for the same command tag. This
the same cmd-tag). This is the number that PROGRESS is expected is the number that PROGRESS is expected to reach after the
to reach after the completion of the command and therefore it completion of the command; therefore, it MUST be greater than
MUST be strictly greater than PROGRESS. If the GOAL is not PROGRESS. If the GOAL is not known, it MUST be set to NIL.
known, it MUST be set to NIL.
If the response code does not embed a list of details, all details If the response code does not embed a list of details, all details
are to be interpreted as NIL. are to be interpreted as NIL.
The server can provide the progress notification details with The server can provide the progress details with different degrees of
different degrees of completeness: completeness:
- bare keepalive - bare keepalive
* OK [INPROGRESS] Hang in there.. * OK [INPROGRESS] Hang in there...
- keepalive with an indication of the command tag - keepalive with an indication of the command tag
* OK [INPROGRESS ("tag" NIL NIL)] Hang in there.. * OK [INPROGRESS ("tag" NIL NIL)] Hang in there...
- progress indication with unknown GOAL - progress notification with unknown GOAL
* OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far * OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far
- progress indication with the indication of the GOAL - progress notification with an indication of the GOAL
* OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items
Examples: Examples:
C: A001 search text "this will be slow" C: A001 search text "this will be slow"
[13 seconds later] [13 seconds later]
S: * OK [INPROGRESS ("A001" 454 1000)] Processed 45% of the items S: * OK [INPROGRESS ("A001" 454 1000)] Processed 45% of the items
[14 seconds later] [14 seconds later]
S: * OK [INPROGRESS ("A001" 999 1000)] Processed 99% of the items S: * OK [INPROGRESS ("A001" 999 1000)] Processed 99% of the items
[5 seconds later] [5 seconds later]
skipping to change at page 4, line 46 skipping to change at line 178
[13 seconds later] [13 seconds later]
S: * OK [INPROGRESS ("A003" 987 2001)] Still working on this... S: * OK [INPROGRESS ("A003" 987 2001)] Still working on this...
[14 seconds later] [14 seconds later]
S: * OK [INPROGRESS ("A003" 1388 2001)] Still working on this... S: * OK [INPROGRESS ("A003" 1388 2001)] Still working on this...
[14 seconds later] [14 seconds later]
S: * OK [INPROGRESS ("A003" 1876 2001)] Still working on this... S: * OK [INPROGRESS ("A003" 1876 2001)] Still working on this...
[9 seconds later] [9 seconds later]
S: A003 OK Copy completed S: A003 OK Copy completed
PROGRESS and GOAL SHOULD be counts of the kind of item being PROGRESS and GOAL SHOULD be counts of the kind of item being
processed - in most cases, messages counts. If that is not possible, processed -- in most cases, messages counts. If that is not
the counts SHOULD be percentages, with goal set to 100 and progress possible, the counts SHOULD be percentages, with GOAL set to 100 and
varying between 0 and 99. PROGRESS varying between 0 and 99.
The server SHOULD NOT send a progress notification where PROGRESS The server SHOULD NOT send a progress notification where PROGRESS
equals GOAL, as that would mean the command is completed. In that equals GOAL, as that would mean the command is completed. In that
case, the proper tagged response should be emitted instead. case, the proper tagged response should be emitted instead.
If the command completes before the first server notification If the command completes before the first server notification
deadline, there will be no notifications at all. The client MUST deadline, there will be no notifications at all. The client MUST
assume PROGRESS to be 0 and GOAL to be unknown until the server assume PROGRESS to be 0 and GOAL to be unknown until the server
issues a notification for the command. issues a notification for the command.
While the server SHOULD keep GOAL constant and PROGRESS monotonically While the server SHOULD keep GOAL constant and PROGRESS monotonically
increasing, there are circumstances where this might not be possible. increasing, there are circumstances where this might not be possible.
The client MUST be prepared to handle cases where the server cannot The client MUST be prepared to handle cases where the server cannot
keep GOAL constant and/or PROGRESS monotonically increasing. When keep GOAL constant and/or PROGRESS monotonically increasing. When
the GOAL changes or the PROGRESS goes backward, the RECOMMENDED the GOAL changes or the PROGRESS goes backward, the RECOMMENDED
interpretation is that the previous GOAL has been reached, but the interpretation is that the previous GOAL has been reached, but the
server discovered that further (long-running) work is required server discovered that further (long-running) work is required (with
(either with known or unknown new GOAL), a new known or unknown GOAL).
The client MAY disregard progress notifications entirely or process The client MAY disregard progress notifications entirely or process
them only in relation to specific commands. If a User Interface is them only in relation to specific commands. If a user interface is
involved, it is the client's duty to decide which of these commands involved, it is the client's duty to decide which of these
are blocking on the user experience, since this may differ based on notifications should emerge to the user interface and/or modify the
implementation details. 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 Also, the client MUST NOT consider the values to be authoritative for
any other use than evaluating the progress of the commands. E.g.: any other use than evaluating the progress of the commands. For
the client must not use the GOAL field in place of the proper output example, the client must not use the GOAL field in place of the
of a SEARCH command to know the number of messages in a folder. proper output of a SEARCH command to know the number of messages in a
folder.
5. Formal Syntax 5. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) [RFC5234] notation. Elements not defined here can be Form (ABNF) [RFC5234] notation. Elements not defined here can be
found in the formal syntax of the ABNF [RFC5234] and IMAP [RFC9051] found in the formal syntax of the ABNF [RFC5234] and IMAP [RFC9051]
specifications. specifications.
Except as noted otherwise, all alphabetic characters are case- Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of uppercase or lowercase characters to define insensitive. The use of uppercase or lowercase characters to define
skipping to change at page 6, line 10 skipping to change at line 242
/ inprogress-state-known-goal / inprogress-state-known-goal
resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP
inprogress-state ")" ] inprogress-state ")" ]
6. Security Considerations 6. Security Considerations
The details of the response code are not expected to disclose any The details of the response code are not expected to disclose any
information that isn't currently available from the command output. information that isn't currently available from the command output.
The progress details could be obtained anyway by sending a series of The progress details could be obtained anyway by sending a series of
commands with different workloads - either by constructing data sets commands with different workloads -- by either constructing data sets
or searching in the appropriate way. or searching in the appropriate way.
The client must protect itself against data sent by a malicious The client must protect itself against data sent by a malicious
server. Specifically, the client should guard against values that server. Specifically, the client should guard against values that
can cause arithmetic exceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/ can cause arithmetic exceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/
VALUE >= 2^32 (these are not possible within a correct implementation VALUE ≥ 2^32 (these are not possible within a correct implementation
of the ABNF syntax above), and VALUE > GOAL. In these cases, the of the ABNF syntax above), and VALUE > GOAL. In these cases, the
notification MUST be disregarded. notification MUST be disregarded.
7. IANA Considerations 7. IANA Considerations
IANA is requested to add "INPROGRESS" to the "IMAP Response Codes" IANA has added "INPROGRESS" to the "IMAP Response Codes" registry
registry located at <https://www.iana.org/assignments/imap-response- located at <https://www.iana.org/assignments/imap-response-codes>,
codes>, with a reference to this document. with a reference to this document.
IANA is requested to add "INPROGRESS" to the "IMAP Capabilities" IANA had added "INPROGRESS" to the "IMAP Capabilities" registry
registry located at <https://www.iana.org/assignments/imap- located at <https://www.iana.org/assignments/imap-capabilities>, with
capabilities>, with a reference to this document. a reference to this document.
8. Normative References 8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
 End of changes. 30 change blocks. 
92 lines changed or deleted 87 lines changed or added

This html diff was produced by rfcdiff 1.48.