Internet DRAFT - draft-bettini-imap-inprogress
draft-bettini-imap-inprogress
Network Working Group M. Bettini
Internet-Draft Open-Xchange Oy
Intended status: Standards Track 8 March 2023
Expires: 9 September 2023
IMAP4 Response Code for Command Progress Notifications.
draft-bettini-imap-inprogress-00
Abstract
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.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
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
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 9 September 2023.
Copyright Notice
Copyright (c) 2023 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.
Bettini Expires 9 September 2023 [Page 1]
Internet-Draft IMAP4 Response Code for Command Progress March 2023
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 2
3. The "INPROGRESS" Response Code . . . . . . . . . . . . . . . 3
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . 5
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
7. Normative References . . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
1. Introduction
Internet Message Access Protocol (IMAP) [RFC9051] 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)
[RFC9051] with a new "INPROGRESS" response code [RFC5530]. The new
response code provides consistent means for a client to receive
progress updates on command completion status.
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",
"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 possible
circumstance or situation, as opposed to an optional facility of the
protocol.
Conventions for notations are as in [RFC9051] and [RFC5530].
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. Note that each line includes the terminating
CRLF.
Bettini Expires 9 September 2023 [Page 2]
Internet-Draft IMAP4 Response Code for Command Progress March 2023
3. The "INPROGRESS" Response Code
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 [RFC9051] 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
Bettini Expires 9 September 2023 [Page 3]
Internet-Draft IMAP4 Response Code for Command Progress March 2023
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.
4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) [RFC5234] notation. Elements not defined here can be
found in the formal syntax of the ABNF [RFC5234], IMAP [RFC9051] and
IMAP ABNF extension [RFC4466] 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 ")" ]
Bettini Expires 9 September 2023 [Page 4]
Internet-Draft IMAP4 Response Code for Command Progress March 2023
5. Security Considerations
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.
6. IANA Considerations
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.
7. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, DOI 10.17487/RFC4466, April 2006,
<https://www.rfc-editor.org/info/rfc4466>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC5530] Gulbrandsen, A., "IMAP Response Codes", RFC 5530,
DOI 10.17487/RFC5530, May 2009,
<https://www.rfc-editor.org/info/rfc5530>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
Access Protocol (IMAP) - Version 4rev2", RFC 9051,
DOI 10.17487/RFC9051, August 2021,
<https://www.rfc-editor.org/info/rfc9051>.
Author's Address
Bettini Expires 9 September 2023 [Page 5]
Internet-Draft IMAP4 Response Code for Command Progress March 2023
Marco Bettini
Open-Xchange Oy
Lars Sonckin Kaari 12
FI-02600 Espoo
Finland
Email: marco.bettini@open-xchange.com
Bettini Expires 9 September 2023 [Page 6]
