wdiff rfc9585.original.xml rfc9585.xml

<?xml version="1.0" encoding="US-ASCII"?> 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 [
 <!ENTITY nbsp    "&#160;">
 <!ENTITY zwsp   "&#8203;">
 <!ENTITY nbhy   "&#8209;">
 <!ENTITY wj     "&#8288;">
]>

<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/XInclude">

<front><!--  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> xmlns:xi="http://www.w3.org/2001/XInclude" symRefs="true" sortRefs="true">

  <front>
    <title abbrev="IMAP4 abbrev="IMAP Response Code for Command Progress">
IMAP4 Progress">IMAP Response
    Code for Command Progress Notifications.
</title> Notifications</title>
    <seriesInfo name="Internet-Draft" value="draft-ietf-extra-imap-inprogress-06"/> name="RFC" value="9585"/>

    <author fullname="Marco Bettini" initials="M." surname="Bettini">
      <organization>Open-Xchange Oy</organization>
      <address>
	<postal>
	  <street>Lars Sonckin kaari 10</street>
	  <code>02600</code>
	  <city>Espoo</city>
	  <country>Finland</country>
	</postal>
	<email>marco.bettini@open-xchange.com</email>
      </address>
    </author>

<date/>

    <date month="May" year="2024"/>

    <area>ART</area>
<workgroup>EXTRA</workgroup>
    <workgroup>extra</workgroup>

    <keyword>IMAP</keyword>
    <keyword>response code</keyword>

    <abstract>
<t>
This
      <t>This document defines a new IMAP untagged response code,
      "INPROGRESS", that provides structured numeric progress notifications regarding the status indication for
      of long-running commands.
      </t>
    </abstract>

</front><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<middle><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<section title="Introduction">

  </front>
  <middle>

<section>
  <name>Introduction</name>

  <t>
Internet Message Access Protocol (IMAP)
IMAP commands <xref target="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. 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 it the server
to inform the
user client of the progress of the long-running actions.
</t>
<t>
This document extends the Internet Message Access Protocol (IMAP)
<xref target="RFC9051"/> with:
</t>
<ul>
<li>a new "INPROGRESS" response code <xref target="RFC5530"/>.
    The new response code provides a consistent means for a client to receive a
    progress update notifications on command completion status.</li>
<li>a new "INPROGRESS" capability <xref target="RFC9051"/>.
    The new capability informs the client that the server emits progress
    update notifications,
    notifications via the "INPROGRESS" response code</li> code.</li>
</ul>
</section>

<section title="Conventions

<section>
  <name>Conventions Used in This Document">
<t>
"Conventions" are basic principles or procedures. Document conventions are
noted in this section.
</t> Document</name>

        <t>
    The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
    "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>",
    "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
    "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
    "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to be
    interpreted as described in BCP 14 BCP&nbsp;14 <xref target="RFC2119"/> <xref
    target="RFC8174"/> when, and only when, they appear in all capitals, as
    shown here.
        </t>

<t>
The word "can" (not "may") is used to refer to a possible
circumstance or situation, as opposed to an optional facility of the
protocol.
</t>
<t>
Conventions for notations are as in <xref target="RFC9051"/> and
<xref target="RFC5530"/>.
</t>
<t>
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. Note that each line includes the terminating CRLF.
</t>
</section>

<section title="CAPABILITY Identification">

<section>
  <name>CAPABILITY Identification</name>
  <t>
IMAP servers that support this extension <bcp14>MUST</bcp14> include
"INPROGRESS" in the response list to the CAPABILITY command.
</t>
</section>

<section title="The

<section>
  <name>The &quot;INPROGRESS&quot; Response Code"> Code</name>
<t>
The server <bcp14>MAY</bcp14> send the "INPROGRESS" Response Code response code to notify
the client about the progress of the commands in execution, execution or simply to
prevent the client from timing out and terminating the connection.
The notifications <bcp14>MAY</bcp14> be sent for any IMAP command.
If the server elects to send notifications, it is <bcp14>RECOMMENDED</bcp14>
that these are sent every 10-15 seconds.
</t>
<t>
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 command has completed and further progress notifications make no sense).
</t>

<t>
The response code <bcp14>MAY</bcp14> embed a list of details, composed which appear
in order of: the following order:
</t>

<ol>
<li>CMD-TAG: the cmd-tag tag <xref target="RFC9051"/> that originated the
    long-running command. If the tag is not available, available or if it contains
    the "]" character, it <bcp14>MUST</bcp14> 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
    cmd-tag(s)
    tags by simply refraining from the use of the character "]" in the
    originating command tags.
</li>
<li>PROGRESS: a number indicating the number of items processed so far.
    The number <bcp14>MUST</bcp14> be non-negative and <bcp14>SHOULD</bcp14>
    be monotonically increasing.
    If the PROGRESS is not available, both PROGRESS and GOAL <bcp14>MUST</bcp14>
    be set to NIL.
</li>
<li>GOAL: a number indicating the total number of items to be processed.
    The number <bcp14>MUST</bcp14> be positive positive, and it <bcp14>SHOULD NOT</bcp14>
    change between successive notifications for the same command (i.e. for
    the same cmd-tag). tag.
    This is the number that PROGRESS is expected to reach
    after the completion of the command and therefore command; therefore, it <bcp14>MUST</bcp14> be
    strictly
    greater than PROGRESS. If the GOAL is not known, it
    <bcp14>MUST</bcp14> be set to NIL.</li>
</ol>
<t>
If the response code does not embed a list of details, all details are to
be interpreted as NIL.
</t>
<t>
The server can provide the progress notification details with different
degrees of completeness:
</t>

<sourcecode>
- bare keepalive
  * OK [INPROGRESS] Hang in there.. there...
- keepalive with an indication of the command tag
  * OK [INPROGRESS ("tag" NIL NIL)] Hang in there.. there...
- progress indication notification with unknown GOAL
  * OK [INPROGRESS ("tag" 175 NIL)] Processed 175 items so far
- progress indication notification with the an indication of the GOAL
  * OK [INPROGRESS ("tag" 175 1000)] Processed 17% of the items
</sourcecode>
<t>
Examples:
</t>
<sourcecode>
  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).
</sourcecode>

<sourcecode>
  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
</sourcecode>

<t>
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,
the counts <bcp14>SHOULD</bcp14> be percentages, with goal GOAL set to 100
and progress PROGRESS varying between 0 and 99.
</t>
<t>
The server <bcp14>SHOULD NOT</bcp14> 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.
</t>
<t>
If the command completes before the first server notification deadline,
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
notification for the command.
</t>
<t>
While the server <bcp14>SHOULD</bcp14> keep GOAL constant and PROGRESS
monotonically increasing, there are circumstances where this might not
be possible. The client <bcp14>MUST</bcp14> 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
<bcp14>RECOMMENDED</bcp14> interpretation is that the previous GOAL has
been reached, but the server discovered that further (long-running) work
is required (either with (with a new known or unknown new GOAL), GOAL).
</t>

<t>
The client <bcp14>MAY</bcp14> disregard progress notifications entirely or
process them only in relation to specific commands. If a User Interface user interface is
involved, it is the client's duty to decide which of these commands are blocking
on
notifications should emerge to the user experience, interface and/or modify the user's
ability to interact in their presence, since this may differ based on
implementation details.
</t>
<t>
Also, the client <bcp14>MUST NOT</bcp14> consider the values to be authoritative
for any other use than evaluating the progress of the commands.
E.g.:
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.
</t>
</section>

<section title="Formal Syntax">

<section>
  <name>Formal Syntax</name>
<t>
The following syntax specification uses the Augmented Backus-Naur Form
(ABNF) <xref target="RFC5234"/> notation. Elements not defined here can
be found in the formal syntax of the ABNF <xref target="RFC5234"/> and IMAP
<xref target="RFC9051"/> specifications.
</t>
<t>
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 <bcp14>MUST</bcp14> accept
these strings in a case-insensitive fashion.
</t>
<sourcecode>
<sourcecode type="abnf">
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 ")" ]
</sourcecode>
</section>

<section title="Security Considerations">

<section>
  <name>Security Considerations</name>
<t>
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 - either -- by either constructing data sets or searching in the appropriate
way.
</t>

<t>
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 &lt; 0, GOAL/VALUE &gt;= 2^32 ≥ 2<sup>32</sup>
(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>
be disregarded.
</t>
</section>

<section title="IANA Considerations">

<section>
  <name>IANA Considerations</name>
<t>
   IANA is requested to add has added "INPROGRESS" to the "IMAP Response Codes" registry
   located at &lt;https://www.iana.org/assignments/imap-response-codes&gt;, <eref target="https://www.iana.org/assignments/imap-response-codes" brackets="angle"/>,
   with a reference to this document.
</t>
<t>
   IANA is requested to add had added "INPROGRESS" to the "IMAP Capabilities" registry
   located at &lt;https://www.iana.org/assignments/imap-capabilities&gt;, <eref target="https://www.iana.org/assignments/imap-capabilities" brackets="angle"/>,
   with a reference to this document.
</t>
</section>

</middle><!--  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<back><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<references title="Normative References">

</middle>
<back>

<references>
  <name>Normative References</name>
  <xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.2119.xml"/> href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
  <xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.5234.xml"/> href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml"/>
  <xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.5530.xml"/> href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5530.xml"/>
  <xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8174.xml"/> href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
  <xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.9051.xml"/>
</references>

<!--
  <references title="Informative References"> href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.9051.xml"/>
</references>
-->
</back><!--  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

</back>
</rfc>