1
2
3
4
5Internet Engineering Task Force (IETF) M. Bettini
6Request for Comments: 9585 Open-Xchange Oy
7Category: Standards Track May 2024
8ISSN: 2070-1721
9
10
11 IMAP Response Code for Command Progress Notifications
12
13Abstract
14
15 This document defines a new IMAP untagged response code,
16 "INPROGRESS", that provides progress notifications regarding the
17 status of long-running commands.
18
19Status of This Memo
20
21 This is an Internet Standards Track document.
22
23 This document is a product of the Internet Engineering Task Force
24 (IETF). It represents the consensus of the IETF community. It has
25 received public review and has been approved for publication by the
26 Internet Engineering Steering Group (IESG). Further information on
27 Internet Standards is available in Section 2 of RFC 7841.
28
29 Information about the current status of this document, any errata,
30 and how to provide feedback on it may be obtained at
31 https://www.rfc-editor.org/info/rfc9585.
32
33Copyright Notice
34
35 Copyright (c) 2024 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
37
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents
40 (https://trustee.ietf.org/license-info) in effect on the date of
41 publication of this document. Please review these documents
42 carefully, as they describe your rights and restrictions with respect
43 to this document. Code Components extracted from this document must
44 include Revised BSD License text as described in Section 4.e of the
45 Trust Legal Provisions and are provided without warranty as described
46 in the Revised BSD License.
47
48Table of Contents
49
50 1. Introduction
51 2. Conventions Used in This Document
52 3. CAPABILITY Identification
53 4. The "INPROGRESS" Response Code
54 5. Formal Syntax
55 6. Security Considerations
56 7. IANA Considerations
57 8. Normative References
58 Author's Address
59
601. Introduction
61
62 IMAP commands [RFC9051] can require a considerable amount of time to
63 be completed by the server. In these cases, the client has no
64 information about the progress of the commands. It is already
65 possible to expose updates with a generic untagged response, like "*
66 OK Still on it, 57% done"; however, this does not provide a standard
67 way to communicate with the client and does not allow the server to
68 inform the client of the progress of the long-running actions.
69
70 This document extends the Internet Message Access Protocol (IMAP)
71 [RFC9051] with:
72
73 * a new "INPROGRESS" response code [RFC5530]. The new response code
74 provides a consistent means for a client to receive progress
75 notifications on command completion status.
76
77 * a new "INPROGRESS" capability [RFC9051]. The new capability
78 informs the client that the server emits progress notifications
79 via the "INPROGRESS" response code.
80
812. Conventions Used in This Document
82
83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
85 "OPTIONAL" in this document are to be interpreted as described in
86 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
87 capitals, as shown here.
88
89 The word "can" (not "may") is used to refer to a possible
90 circumstance or situation, as opposed to an optional facility of the
91 protocol.
92
93 Conventions for notations are as in [RFC9051] and [RFC5530].
94
95 In examples, "C:" and "S:" indicate lines sent by the client and
96 server, respectively. Note that each line includes the terminating
97 CRLF.
98
993. CAPABILITY Identification
100
101 IMAP servers that support this extension MUST include "INPROGRESS" in ../imapserver/server.go:184
102 the response list to the CAPABILITY command.
103
1044. The "INPROGRESS" Response Code ../imapclient/parse.go:134
105
106 The server MAY send the "INPROGRESS" response code to notify the
107 client about the progress of the commands in execution or simply to
108 prevent the client from timing out and terminating the connection.
109 The notifications MAY be sent for any IMAP command. If the server ../imapserver/search.go:20
110 elects to send notifications, it is RECOMMENDED that these are sent
111 every 10-15 seconds.
112
113 The response code is meant to appear embedded inside an untagged OK
114 reply. The response code MUST NOT appear in a tagged response (the
115 command has completed and further progress notifications make no
116 sense).
117
118 The response code MAY embed a list of details, which appear in the
119 following order:
120
121 1. CMD-TAG: the tag [RFC9051] that originated the long-running
122 command. If the tag is not available or if it contains the "]" ../imapserver/search.go:204
123 character, it MUST be set to NIL. This still produces a usable
124 notification, unless multiple commands are in flight
125 simultaneously. A client can ensure reception of notifications
126 with tags by simply refraining from the use of the character "]"
127 in the originating command tags.
128
129 2. PROGRESS: a number indicating the number of items processed so
130 far. The number MUST be non-negative and SHOULD be monotonically
131 increasing. If the PROGRESS is not available, both PROGRESS and
132 GOAL MUST be set to NIL.
133
134 3. GOAL: a number indicating the total number of items to be
135 processed. The number MUST be positive, and it SHOULD NOT change
136 between successive notifications for the same command tag. This
137 is the number that PROGRESS is expected to reach after the
138 completion of the command; therefore, it MUST be greater than
139 PROGRESS. If the GOAL is not known, it MUST be set to NIL.
140
141 If the response code does not embed a list of details, all details
142 are to be interpreted as NIL.
143
144 The server can provide the progress details with different degrees of
145 completeness:
146
147 - bare keepalive
148 * OK [INPROGRESS] Hang in there...
149 - keepalive with an indication of the command tag
150 * OK [INPROGRESS ("tag" NIL NIL)] Hang in there...
151 - progress notification with unknown GOAL
152 * OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far
153 - progress notification with an indication of the GOAL
154 * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items
155
156 Examples:
157
158 C: A001 search text "this will be slow"
159 [13 seconds later]
160 S: * OK [INPROGRESS ("A001" 454 1000)] Processed 45% of the items
161 [14 seconds later]
162 S: * OK [INPROGRESS ("A001" 999 1000)] Processed 99% of the items
163 [5 seconds later]
164 S: * SEARCH 447 735
165 S: A001 OK Search completed (23.387 + 0.004 + 0.017 secs).
166
167 C: A003 COPY 2000:4000 Meeting-Minutes
168 [12 seconds later]
169 S: * OK [INPROGRESS ("A003" 175 2001)] Still working on this...
170 [14 seconds later]
171 S: * OK [INPROGRESS ("A003" 440 2001)] Still working on this...
172 [13 seconds later]
173 S: * OK [INPROGRESS ("A003" 987 2001)] Still working on this...
174 [14 seconds later]
175 S: * OK [INPROGRESS ("A003" 1388 2001)] Still working on this...
176 [14 seconds later]
177 S: * OK [INPROGRESS ("A003" 1876 2001)] Still working on this...
178 [9 seconds later]
179 S: A003 OK Copy completed
180
181 PROGRESS and GOAL SHOULD be counts of the kind of item being
182 processed -- in most cases, messages counts. If that is not
183 possible, the counts SHOULD be percentages, with GOAL set to 100 and
184 PROGRESS varying between 0 and 99.
185
186 The server SHOULD NOT send a progress notification where PROGRESS
187 equals GOAL, as that would mean the command is completed. In that
188 case, the proper tagged response should be emitted instead.
189
190 If the command completes before the first server notification
191 deadline, there will be no notifications at all. The client MUST
192 assume PROGRESS to be 0 and GOAL to be unknown until the server
193 issues a notification for the command.
194
195 While the server SHOULD keep GOAL constant and PROGRESS monotonically
196 increasing, there are circumstances where this might not be possible.
197 The client MUST be prepared to handle cases where the server cannot
198 keep GOAL constant and/or PROGRESS monotonically increasing. When
199 the GOAL changes or the PROGRESS goes backward, the RECOMMENDED
200 interpretation is that the previous GOAL has been reached, but the
201 server discovered that further (long-running) work is required (with
202 a new known or unknown GOAL).
203
204 The client MAY disregard progress notifications entirely or process
205 them only in relation to specific commands. If a user interface is
206 involved, it is the client's duty to decide which of these
207 notifications should emerge to the user interface and/or modify the
208 user's ability to interact in their presence, since this may differ
209 based on implementation details.
210
211 Also, the client MUST NOT consider the values to be authoritative for
212 any other use than evaluating the progress of the commands. For
213 example, the client must not use the GOAL field in place of the
214 proper output of a SEARCH command to know the number of messages in a
215 folder.
216
2175. Formal Syntax
218
219 The following syntax specification uses the Augmented Backus-Naur
220 Form (ABNF) [RFC5234] notation. Elements not defined here can be
221 found in the formal syntax of the ABNF [RFC5234] and IMAP [RFC9051]
222 specifications.
223
224 Except as noted otherwise, all alphabetic characters are case-
225 insensitive. The use of uppercase or lowercase characters to define
226 token strings are for editorial clarity only. Implementations MUST
227 accept these strings in a case-insensitive fashion.
228
229 inprogress-tag = quoted / nil
230 inprogress-state-unknown = nil SP nil
231 inprogress-state-counting = number SP nil
232 inprogress-state-known-goal = number SP nz-number ../imapserver/search.go:382
233
234 inprogress-state = inprogress-state-unknown
235 / inprogress-state-counting
236 / inprogress-state-known-goal
237
238 resp-text-code =/ "INPROGRESS" [ SP "(" inprogress-tag SP ../imapclient/parse.go:227
239 inprogress-state ")" ]
240
2416. Security Considerations
242
243 The details of the response code are not expected to disclose any
244 information that isn't currently available from the command output.
245 The progress details could be obtained anyway by sending a series of
246 commands with different workloads -- by either constructing data sets
247 or searching in the appropriate way.
248
249 The client must protect itself against data sent by a malicious
250 server. Specifically, the client should guard against values that
251 can cause arithmetic exceptions, like GOAL = 0, GOAL/VALUE < 0, GOAL/
252 VALUE ≥ 2^32 (these are not possible within a correct implementation
253 of the ABNF syntax above), and VALUE > GOAL. In these cases, the
254 notification MUST be disregarded.
255
2567. IANA Considerations
257
258 IANA has added "INPROGRESS" to the "IMAP Response Codes" registry
259 located at <https://www.iana.org/assignments/imap-response-codes>,
260 with a reference to this document.
261
262 IANA had added "INPROGRESS" to the "IMAP Capabilities" registry
263 located at <https://www.iana.org/assignments/imap-capabilities>, with
264 a reference to this document.
265
2668. Normative References
267
268 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
269 Requirement Levels", BCP 14, RFC 2119,
270 DOI 10.17487/RFC2119, March 1997,
271 <https://www.rfc-editor.org/info/rfc2119>.
272
273 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
274 Specifications: ABNF", STD 68, RFC 5234,
275 DOI 10.17487/RFC5234, January 2008,
276 <https://www.rfc-editor.org/info/rfc5234>.
277
278 [RFC5530] Gulbrandsen, A., "IMAP Response Codes", RFC 5530,
279 DOI 10.17487/RFC5530, May 2009,
280 <https://www.rfc-editor.org/info/rfc5530>.
281
282 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
283 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
284 May 2017, <https://www.rfc-editor.org/info/rfc8174>.
285
286 [RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
287 Access Protocol (IMAP) - Version 4rev2", RFC 9051,
288 DOI 10.17487/RFC9051, August 2021,
289 <https://www.rfc-editor.org/info/rfc9051>.
290
291Author's Address
292
293 Marco Bettini
294 Open-Xchange Oy
295 Lars Sonckin kaari 10
296 FI-02600 Espoo
297 Finland
298 Email: marco.bettini@open-xchange.com
299