rfc9585.original.xml   rfc9585.xml 
<?xml version="1.0" encoding="US-ASCII"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<?rfc private="Dovecot" ?>
<rfc category="std" docName="draft-ietf-extra-imap-inprogress-06" <!DOCTYPE rfc [
ipr="trust200902" consensus="true" submissionType="IETF" <!ENTITY nbsp "&#160;">
xml:lang="en" version="3" xmlns:xi="http://www.w3.org/2001/XInclude"> <!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;">
]>
<front><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <rfc category="std" docName="draft-ietf-extra-imap-inprogress-06" number="9585" updates="" obsoletes="" ipr="trust200902" consensus="true" submissionType="IETF" tocInclude="true" xml:lang="en" version="3" xmlns:xi="http://www.w3.org/2001/XI nclude" symRefs="true" sortRefs="true">
<title abbrev="IMAP4 Response Code for Command Progress"> <front>
IMAP4 Response Code for Command Progress Notifications. <title abbrev="IMAP Response Code for Command Progress">IMAP Response
</title> Code for Command Progress Notifications</title>
<seriesInfo name="Internet-Draft" value="draft-ietf-extra-imap-inprogress-06"/> <seriesInfo name="RFC" value="9585"/>
<author fullname="Marco Bettini" initials="M." surname="Bettini"> <author fullname="Marco Bettini" initials="M." surname="Bettini">
<organization>Open-Xchange Oy</organization> <organization>Open-Xchange Oy</organization>
<address> <address>
<postal> <postal>
<street>Lars Sonckin kaari 10</street> <street>Lars Sonckin kaari 10</street>
<code>02600</code> <code>02600</code>
<city>Espoo</city> <city>Espoo</city>
<country>Finland</country> <country>Finland</country>
</postal> </postal>
<email>marco.bettini@open-xchange.com</email> <email>marco.bettini@open-xchange.com</email>
</address> </address>
</author> </author>
<date/> <date month="May" year="2024"/>
<area>ART</area> <area>ART</area>
<workgroup>EXTRA</workgroup> <workgroup>extra</workgroup>
<keyword>IMAP</keyword>
<keyword>response code</keyword>
<abstract> <keyword>IMAP</keyword>
<t> <keyword>response code</keyword>
This document defines a new IMAP untagged response code, "INPROGRESS",
that provides structured numeric progress status indication for
long-running commands.
</t>
</abstract>
</front><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <abstract>
<middle><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <t>This document defines a new IMAP untagged response code,
"INPROGRESS", that provides progress notifications regarding the status
of long-running commands.
</t>
</abstract>
<section title="Introduction"> </front>
<t> <middle>
Internet Message Access Protocol (IMAP) <xref target="RFC9051"/> commands
<section>
<name>Introduction</name>
<t>
IMAP commands <xref target="RFC9051"/>
can require a considerable amount of time to be completed by the server. 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 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 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 response, like "* OK Still on it, 57% done"; however, this does not provide
a standard way to communicate with the client and allow it to inform the a standard way to communicate with the client and does not allow the server
user of the progress of the long-running actions. to inform the client of the progress of the long-running actions.
</t> </t>
<t> <t>
This document extends the Internet Message Access Protocol (IMAP) This document extends the Internet Message Access Protocol (IMAP)
<xref target="RFC9051"/> with: <xref target="RFC9051"/> with:
</t> </t>
<ul> <ul>
<li>a new "INPROGRESS" response code <xref target="RFC5530"/>. <li>a new "INPROGRESS" response code <xref target="RFC5530"/>.
The new response code provides consistent means for a client to receive a The new response code provides a consistent means for a client to receive
progress update notifications on command completion status.</li> progress notifications on command completion status.</li>
<li>a new "INPROGRESS" capability <xref target="RFC9051"/>. <li>a new "INPROGRESS" capability <xref target="RFC9051"/>.
The new capability informs the client that the server emits progress The new capability informs the client that the server emits progress
update notifications, via the "INPROGRESS" response code</li> notifications via the "INPROGRESS" response code.</li>
</ul> </ul>
</section> </section>
<section title="Conventions Used in This Document"> <section>
<t> <name>Conventions Used in This Document</name>
"Conventions" are basic principles or procedures. Document conventions are
noted in this section. <t>
</t> The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
<t> "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
The key words ",
"<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
"<bcp14>REQUIRED</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
"<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", be
"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", interpreted as described in BCP&nbsp;14 <xref target="RFC2119"/> <xref
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" target="RFC8174"/> when, and only when, they appear in all capitals, as
in this document are to be interpreted as described in BCP 14 shown here.
<xref target="RFC2119"/> <xref target="RFC8174"/> </t>
when, and only when, they appear in all capitals, as shown here.
</t>
<t> <t>
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.
</t> </t>
<t> <t>
Conventions for notations are as in <xref target="RFC9051"/> and Conventions for notations are as in <xref target="RFC9051"/> and
<xref target="RFC5530"/>. <xref target="RFC5530"/>.
</t> </t>
<t> <t>
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 CRLF. server, respectively. Note that each line includes the terminating CRLF.
</t> </t>
</section> </section>
<section title="CAPABILITY Identification"> <section>
<t> <name>CAPABILITY Identification</name>
<t>
IMAP servers that support this extension <bcp14>MUST</bcp14> include IMAP servers that support this extension <bcp14>MUST</bcp14> include
"INPROGRESS" in the response list to the CAPABILITY command. "INPROGRESS" in the response list to the CAPABILITY command.
</t> </t>
</section> </section>
<section title="The &quot;INPROGRESS&quot; Response Code"> <section>
<name>The &quot;INPROGRESS&quot; Response Code</name>
<t> <t>
The server <bcp14>MAY</bcp14> send the "INPROGRESS" Response Code to notify The server <bcp14>MAY</bcp14> send the "INPROGRESS" response code to notify
the client about the progress of the commands in execution, or simply to the 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 <bcp14>MAY</bcp14> be sent for any IMAP command. The notifications <bcp14>MAY</bcp14> be sent for any IMAP command.
If the server elects to send notifications, it is <bcp14>RECOMMENDED</bcp14> If the server elects to send notifications, it is <bcp14>RECOMMENDED</bcp14>
that these are sent every 10-15 seconds. that these are sent every 10-15 seconds.
</t> </t>
<t> <t>
The response code is meant to appear embedded inside an untagged OK reply. The response code is meant to appear embedded inside an untagged OK reply.
The response code <bcp14>MUST NOT</bcp14> appear in a tagged response The response code <bcp14>MUST NOT</bcp14> appear in a tagged response
(the command has completed and further progress notifications make no sense). (the command has completed and further progress notifications make no sense).
</t> </t>
<t> <t>
The response code <bcp14>MAY</bcp14> embed a list of details, composed The response code <bcp14>MAY</bcp14> embed a list of details, which appear
in order of: in the following order:
</t> </t>
<ol> <ol>
<li>CMD-TAG: the cmd-tag <xref target="RFC9051"/> that originated the <li>CMD-TAG: the tag <xref target="RFC9051"/> that originated the
long-running command. If the tag is not available, or if it contains long-running command. If the tag is not available or if it contains
the "]" character, it <bcp14>MUST</bcp14> be set to NIL. This still the "]" character, it <bcp14>MUST</bcp14> be set to NIL. This still
produces a usable notification, unless multiple commands are in flight produces a usable notification, unless multiple commands are in flight
simultaneously. A client can ensure reception of notifications with simultaneously. A client can ensure reception of notifications with
cmd-tag(s) by simply refraining from the use of character "]" in the tags by simply refraining from the use of the character "]" in the
originating command tags. originating command tags.
</li> </li>
<li>PROGRESS: a number indicating the number of items processed so far. <li>PROGRESS: a number indicating the number of items processed so far.
The number <bcp14>MUST</bcp14> be non-negative and <bcp14>SHOULD</bcp14> The number <bcp14>MUST</bcp14> be non-negative and <bcp14>SHOULD</bcp14>
be monotonically increasing. be monotonically increasing.
If the PROGRESS is not available, both PROGRESS and GOAL <bcp14>MUST</bcp14> If the PROGRESS is not available, both PROGRESS and GOAL <bcp14>MUST</bcp14>
be set to NIL. be set to NIL.
</li> </li>
<li>GOAL: a number indicating the total number of items to be processed. <li>GOAL: a number indicating the total number of items to be processed.
The number <bcp14>MUST</bcp14> be positive and it <bcp14>SHOULD NOT</bcp14> The number <bcp14>MUST</bcp14> be positive, and it <bcp14>SHOULD NOT</bcp14>
change between successive notifications for the same command (i.e. for change between successive notifications for the same command tag.
the same cmd-tag). This is the number that PROGRESS is expected to reach This is the number that PROGRESS is expected to reach
after the completion of the command and therefore it <bcp14>MUST</bcp14> be after the completion of the command; therefore, it <bcp14>MUST</bcp14> be
strictly greater than PROGRESS. If the GOAL is not known, it greater than PROGRESS. If the GOAL is not known, it
<bcp14>MUST</bcp14> be set to NIL.</li> <bcp14>MUST</bcp14> be set to NIL.</li>
</ol> </ol>
<t> <t>
If the response code does not embed a list of details, all details are to If the response code does not embed a list of details, all details are to
be interpreted as NIL. be interpreted as NIL.
</t> </t>
<t> <t>
The server can provide the progress notification details with different The server can provide the progress details with different
degrees of completeness: degrees of completeness:
</t> </t>
<sourcecode> <sourcecode>
- 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 <span class="insert">notification</span> with unknown GOAL - progress notification with an indication of the GOAL
- progress indication with the indication of the GOAL
* OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items
progress <span class="insert">notification</span> with <span class="insert">an< /span> indication of the GOAL
</sourcecode> </sourcecode>
<t> <t>
Examples: Examples:
</t> </t>
<sourcecode> <sourcecode>
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]
skipping to change at line 211 skipping to change at line 206
[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
</sourcecode> </sourcecode>
<t> <t>
PROGRESS and GOAL <bcp14>SHOULD</bcp14> be counts of the kind of item PROGRESS and GOAL <bcp14>SHOULD</bcp14> be counts of the kind of item
being processed - in most cases, messages counts. If that is not possible, being processed -- in most cases, messages counts. If that is not possible,
the counts <bcp14>SHOULD</bcp14> be percentages, with goal set to 100 the counts <bcp14>SHOULD</bcp14> be percentages, with GOAL set to 100
and progress varying between 0 and 99. and PROGRESS varying between 0 and 99.
</t> </t>
<t> <t>
The server <bcp14>SHOULD NOT</bcp14> send a progress notification where The server <bcp14>SHOULD NOT</bcp14> send a progress notification where
PROGRESS equals GOAL, as that would mean the command is completed. PROGRESS equals GOAL, as that would mean the command is completed.
In that case, the proper tagged response should be emitted instead. In that case, the proper tagged response should be emitted instead.
</t> </t>
<t> <t>
If the command completes before the first server notification deadline, If the command completes before the first server notification deadline,
there will be no notifications at all. The client <bcp14>MUST</bcp14> there will be no notifications at all. The client <bcp14>MUST</bcp14>
assume PROGRESS to be 0 and GOAL to be unknown until the server issues a assume PROGRESS to be 0 and GOAL to be unknown until the server issues a
notification for the command. notification for the command.
</t> </t>
<t> <t>
While the server <bcp14>SHOULD</bcp14> keep GOAL constant and PROGRESS While the server <bcp14>SHOULD</bcp14> keep GOAL constant and PROGRESS
monotonically increasing, there are circumstances where this might not monotonically increasing, there are circumstances where this might not
be possible. The client <bcp14>MUST</bcp14> be prepared to handle cases be possible. The client <bcp14>MUST</bcp14> be prepared to handle cases
where the server cannot keep GOAL constant and/or PROGRESS monotonically where the server cannot keep GOAL constant and/or PROGRESS monotonically
increasing. When the GOAL changes or the PROGRESS goes backward, the increasing. When the GOAL changes or the PROGRESS goes backward, the
<bcp14>RECOMMENDED</bcp14> interpretation is that the previous GOAL has <bcp14>RECOMMENDED</bcp14> interpretation is that the previous GOAL has
been reached, but the server discovered that further (long-running) work been reached, but the server discovered that further (long-running) work
is required (either with known or unknown new GOAL), is required (with a new known or unknown GOAL).
</t> </t>
<t> <t>
The client <bcp14>MAY</bcp14> disregard progress notifications entirely or The client <bcp14>MAY</bcp14> disregard progress notifications entirely or
process them only in relation to specific commands. If a User Interface is 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 commands are blocking involved, it is the client's duty to decide which of these
on the user experience, since this may differ based on implementation details. 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.
</t> </t>
<t> <t>
Also, the client <bcp14>MUST NOT</bcp14> consider the values to be authoritative Also, the client <bcp14>MUST NOT</bcp14> consider the values to be authoritative
for any other use than evaluating the progress of the commands. for any other use than evaluating the progress of the commands.
E.g.: the client must not use the GOAL field in place of the proper output of a For example, the client must not use the GOAL field in place of the proper outpu t of a
SEARCH command to know the number of messages in a folder. SEARCH command to know the number of messages in a folder.
</t> </t>
</section> </section>
<section title="Formal Syntax"> <section>
<name>Formal Syntax</name>
<t> <t>
The following syntax specification uses the Augmented Backus-Naur Form The following syntax specification uses the Augmented Backus-Naur Form
(ABNF) <xref target="RFC5234"/> notation. Elements not defined here can (ABNF) <xref target="RFC5234"/> notation. Elements not defined here can
be found in the formal syntax of the ABNF <xref target="RFC5234"/> and IMAP be found in the formal syntax of the ABNF <xref target="RFC5234"/> and IMAP
<xref target="RFC9051"/> specifications. <xref target="RFC9051"/> specifications.
</t> </t>
<t> <t>
Except as noted otherwise, all alphabetic characters are case-insensitive. Except as noted otherwise, all alphabetic characters are case-insensitive.
The use of uppercase or lowercase characters to define token strings are The use of uppercase or lowercase characters to define token strings are
for editorial clarity only. Implementations <bcp14>MUST</bcp14> accept for editorial clarity only. Implementations <bcp14>MUST</bcp14> accept
these strings in a case-insensitive fashion. these strings in a case-insensitive fashion.
</t> </t>
<sourcecode> <sourcecode type="abnf">
inprogress-tag = quoted / nil inprogress-tag = quoted / nil
inprogress-state-unknown = nil SP nil inprogress-state-unknown = nil SP nil
inprogress-state-counting = number SP nil inprogress-state-counting = number SP nil
inprogress-state-known-goal = number SP nz-number inprogress-state-known-goal = number SP nz-number
inprogress-state = inprogress-state-unknown inprogress-state = inprogress-state-unknown
/ inprogress-state-counting / inprogress-state-counting
/ 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 ")" ]
</sourcecode> </sourcecode>
</section> </section>
<section title="Security Considerations"> <section>
<name>Security Considerations</name>
<t> <t>
The details of the response code are not expected to disclose any information 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 that isn't currently available from the command output. The progress details
could be obtained anyway by sending a series of commands with different could be obtained anyway by sending a series of commands with different
workloads - either by constructing data sets or searching in the appropriate workloads -- by either constructing data sets or searching in the appropriate
way. way.
</t> </t>
<t> <t>
The client must protect itself against data sent by a malicious server. The client must protect itself against data sent by a malicious server.
Specifically, the client should guard against values that can cause arithmetic Specifically, the client should guard against values that can cause arithmetic
exceptions, like GOAL = 0, GOAL/VALUE &lt; 0, GOAL/VALUE &gt;= 2^32 exceptions, like GOAL = 0, GOAL/VALUE &lt; 0, GOAL/VALUE ≥ 2<sup>32</sup>
(these are not possible within a correct implementation of the ABNF syntax (these are not possible within a correct implementation of the ABNF syntax
above), and VALUE &gt; GOAL. In these cases, the notification <bcp14>MUST</bcp14 > above), and VALUE &gt; GOAL. In these cases, the notification <bcp14>MUST</bcp14 >
be disregarded. be disregarded.
</t> </t>
</section> </section>
<section title="IANA Considerations"> <section>
<name>IANA Considerations</name>
<t> <t>
IANA is requested to add "INPROGRESS" to the "IMAP Response Codes" registry IANA has added "INPROGRESS" to the "IMAP Response Codes" registry
located at &lt;https://www.iana.org/assignments/imap-response-codes&gt;, located at <eref target="https://www.iana.org/assignments/imap-response-codes
" brackets="angle"/>,
with a reference to this document. with a reference to this document.
</t> </t>
<t> <t>
IANA is requested to add "INPROGRESS" to the "IMAP Capabilities" registry IANA had added "INPROGRESS" to the "IMAP Capabilities" registry
located at &lt;https://www.iana.org/assignments/imap-capabilities&gt;, located at <eref target="https://www.iana.org/assignments/imap-capabilities"
brackets="angle"/>,
with a reference to this document. with a reference to this document.
</t> </t>
</section> </section>
</middle><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> </middle>
<back><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> <back>
<references title="Normative References"> <references>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.2119.xm <name>Normative References</name>
l"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xm
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.5234.xm l"/>
l"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5234.xm
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.5530.xm l"/>
l"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5530.xm
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8174.xm l"/>
l"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xm
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.9051.xm l"/>
l"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9051.xm
l"/>
</references> </references>
<!-- </back>
<references title="Informative References">
</references>
</back><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
</rfc> </rfc>
 End of changes. 45 change blocks. 
129 lines changed or deleted 130 lines changed or added

This html diff was produced by rfcdiff 1.48.