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.