rfc8970xml2.original.xml   rfc8970.xml 
<?xml version="1.0" encoding="US-ASCII"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2045 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.2045.xml">
<!ENTITY RFC2046 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.2046.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.2119.xml">
<!ENTITY RFC2854 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.2854.xml">
<!ENTITY RFC3501 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.3501.xml">
<!ENTITY RFC3629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.3629.xml">
<!ENTITY RFC5182 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.5182.xml">
<!ENTITY RFC5234 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.5234.xml">
<!ENTITY RFC5255 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.5255.xml">
<!ENTITY RFC8174 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC
.8174.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?> <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<?rfc strict="yes" ?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" docName="draft-ietf-extra-imap-f
<?rfc toc="yes"?> etch-preview-10" number="8970" ipr="trust200902" obsoletes="" updates="" submiss
<?rfc symrefs="yes"?> ionType="IETF" category="std" consensus="true" xml:lang="en" tocInclude="true" s
<?rfc sortrefs="yes" ?> ymRefs="true" sortRefs="true" version="3">
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-ietf-extra-imap-fetch-preview-10" ipr="trust2 00902"> <!-- xml2rfc v2v3 conversion 3.5.0 -->
<front> <front>
<title abbrev="IMAP: PREVIEW Extension">IMAP4 Extension: Message Preview Gen eration</title> <title abbrev="IMAP: PREVIEW Extension">IMAP4 Extension: Message Preview Gen eration</title>
<seriesInfo name="RFC" value="8970"/>
<author fullname="Michael M. Slusarz" initials="M." surname="Slusarz"> <author fullname="Michael M. Slusarz" initials="M." surname="Slusarz">
<organization>Open-Xchange Inc.</organization> <organization>Open-Xchange Inc.</organization>
<address> <address>
<postal> <postal>
<street>530 Lytton Avenue</street> <street>530 Lytton Avenue</street>
<city>Palo Alto</city> <city>Palo Alto</city>
<region>California</region> <region>California</region>
<code>94301</code> <code>94301</code>
<country>US</country> <country>US</country>
</postal> </postal>
<phone></phone> <phone/>
<email>michael.slusarz@open-xchange.com</email> <email>michael.slusarz@open-xchange.com</email>
</address> </address>
</author> </author>
<date year="2020" month="December" />
<date year="2020" />
<area>ART</area> <area>ART</area>
<workgroup>EXTRA</workgroup> <workgroup>EXTRA</workgroup>
<keyword>IMAP4</keyword> <keyword>IMAP4</keyword>
<keyword>FETCH</keyword> <keyword>FETCH</keyword>
<keyword>PREVIEW</keyword> <keyword>PREVIEW</keyword>
<abstract> <abstract>
<t>This document specifies an Internet Message Access Protocol (IMAP) <t>This document specifies an Internet Message Access Protocol (IMAP)
protocol extension allowing a client to request a server-generated protocol extension that allows a client to request a server-generated
abbreviated text representation of message data useful as a contextual abbreviated text representation of message data that is useful as a contex
tual
preview of the entire message.</t> preview of the entire message.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section anchor="Introduction" title="Introduction"> <section anchor="Introduction" numbered="true" toc="default">
<name>Introduction</name>
<t>Many modern mail clients display small extracts of the body text as <t>Many modern mail clients display small extracts of the body text as
an aid to allow a user to quickly decide whether they are interested an aid to allow a user to quickly decide whether they are interested
in viewing the full message contents. Mail clients implementing the in viewing the full message contents. Mail clients implementing the
<xref target="RFC3501">Internet Message Access Protocol</xref> <xref target="RFC3501" format="default">Internet Message Access Protocol</ xref>
would benefit from a standardized, consistent way to would benefit from a standardized, consistent way to
generate these brief textual previews of messages.</t> generate these brief textual previews of messages.</t>
<t>Generation of a preview on the server has several benefits. First, <t>
it allows consistent representation of previews across all clients. Generation of a preview on the server has several benefits. First,
This standardized display can reduce user confusion when using it allows consistent representation of previews across all clients.
multiple clients, as abbreviated message representations in clients While different clients might generate quite different preview text,
will show identical message contents.</t> having common preview text generated by the server can give a more
consistent user experience to those who use multiple clients.
</t>
<t>Second, server-side preview generation is more efficient. A <t>Second, server-side preview generation is more efficient. A
client-based algorithm needs to issue, at a minimum, a FETCH client-based algorithm needs to issue, at a minimum, a FETCH
BODYSTRUCTURE command in order to determine which <xref BODYSTRUCTURE command in order to determine which <xref target="RFC2045" f
target="RFC2045">MIME</xref> body part(s) should be represented in ormat="default">MIME</xref> body part(s) should be represented in
the preview. Subsequently, at least one FETCH BODY command may be the preview. Subsequently, at least one FETCH BODY command may be
needed to retrieve body data used in preview generation. These FETCH needed to retrieve body data used in preview generation. These FETCH
commands cannot be pipelined since the BODYSTRUCTURE query must be commands cannot be pipelined since the BODYSTRUCTURE query must be
parsed on the client before the list of parts to be retrieved via the parsed on the client before the list of parts to be retrieved via the
BODY command(s) can be determined.</t> BODY command(s) can be determined.</t>
<t>Additionally, it may be difficult to predict the amount of body <t>Additionally, it may be difficult to predict the amount of body
data that must be retrieved to adequately represent the part via a data that must be retrieved to adequately represent the part via a
preview, therefore requiring inefficient fetching of excessive data preview, therefore requiring inefficient fetching of excessive data
in order to account for this uncertainty. For example, a preview in order to account for this uncertainty. For example, a preview
algorithm to display data contained in a <xref algorithm to display data contained in a <xref target="RFC2854" format="de
target="RFC2854">text/html</xref> part will likely fault">text/html</xref> part will likely
strip the markup tags to obtain textual content. However, without strip the markup tags to obtain textual content. However, without
fetching the entire content of the part, there is no way to guarantee fetching the entire content of the part, there is no way to guarantee
that sufficient non-tag content will exist unless either 1) the entire that sufficient non-tag content will exist unless either 1) the entire
part is retrieved or 2) an additional partial FETCH is executed when part is retrieved or 2) an additional partial FETCH is executed when
the client determines that it does not possess sufficient data from a the client determines that it does not possess sufficient data from a
previous partial FETCH to display an adequate representation of the previous partial FETCH to display an adequate representation of the
preview.</t> preview.</t>
<t>Finally, server generation allows caching in a centralized <t>Finally, server generation allows caching in a centralized
location. Using server-generated previews allows global generation location. Using server-generated previews allows global generation
once per message, and that preview can be cached for the retention once per message, and that preview can be cached for the retention
period of the source message. Retrieval of message data may be period of the source message. Retrieval of message data may be
expensive within a server, for example, so a server can be configured expensive within a server, for example, so a server can be configured
to reduce its storage retrieval load by pre-generating preview to reduce its storage retrieval load by pre-generating preview
data.</t> data.</t>
<t>A server indicates support for this extension via the "PREVIEW" <t>A server indicates support for this extension via the "PREVIEW"
capability name.</t> capability name.</t>
</section> </section>
<section anchor="Conventions" numbered="true" toc="default">
<name>Conventions Used in This Document</name>
<section anchor="Conventions" title="Conventions Used In This Document"> <t>
<t> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
"MAY", and "OPTIONAL" in this document are to be interpreted as ",
described in <xref target="RFC2119">BCP 14</xref> "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
<xref target="RFC8174"></xref> when, and only when, they appear in "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
all capitals, as shown here.</t> "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
be
interpreted as described in BCP&nbsp;14 <xref target="RFC2119"/> <xref
target="RFC8174"/> when, and only when, they appear in all capitals, as
shown here.
</t>
<t>"User" is used to refer to a human user, whereas "client" refers to <t>"User" is used to refer to a human user, whereas "client" refers to
the software being run by the user.</t> the software being run by the user.</t>
<t>In examples, "C:" and "S:" indicate lines sent by the client and <t>In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If a single "C:" or "S:" label applies to server, respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol editorial clarity only and are not part of the actual protocol
exchange.</t> exchange.</t>
<t>As with all IMAP extension documents, the case used in writing <t>As with all IMAP extension documents, the case used in writing
IMAP protocol elements herein is chosen for editorial clarity, and IMAP protocol elements herein is chosen for editorial clarity, and
implementations must pay attention to the numbered rules at the implementations must pay attention to the numbered rules at the
beginning of <xref target="RFC3501"></xref> Section 9.</t> beginning of <xref target="RFC3501" sectionFormat="of" section="9" format= "default"/>.</t>
</section> </section>
<section anchor="Fetch" numbered="true" toc="default">
<section anchor="Fetch" title="FETCH Data Item"> <name>FETCH Data Item</name>
<section title="Command"> <section numbered="true" toc="default">
<t>To retrieve a preview for a message, the "PREVIEW" FETCH attribute <name>Command</name>
<t>To retrieve a preview for a message, the PREVIEW FETCH attribute
is used when issuing a FETCH command.</t> is used when issuing a FETCH command.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Response"> <name>Response</name>
<t>The server returns a variable-length string that is the generated <t>The server returns a variable-length string that is the generated
preview for that message. This string is intended to be viewed by the preview for that message. This string is intended to be viewed by the
user as a contextual preview of the entire message, and is not user as a contextual preview of the entire message and is not
intended to be interpreted in any way by the client software.</t> intended to be interpreted in any way by the client software.</t>
<t keepWithNext="true">Example: Retrieving preview information in a SELE
<figure> CTed
<preamble>Example: Retrieving preview information in a SELECTed mailbox.</t>
mailbox</preamble> <sourcecode name="" type=""><![CDATA[
<artwork><![CDATA[
C: A1 FETCH 1 (PREVIEW) C: A1 FETCH 1 (PREVIEW)
S: * 1 FETCH (PREVIEW "Preview text!") S: * 1 FETCH (PREVIEW "Preview text!")
S: A1 OK FETCH complete. S: A1 OK FETCH complete.
]]></artwork> ]]></sourcecode>
</figure> <t>A server <bcp14>SHOULD</bcp14> strive to generate the same string for
a given
<t>A server SHOULD strive to generate the same string for a given
message for each request. However, since previews are understood to be message for each request. However, since previews are understood to be
an approximation of the message data and not a canonical view of its an approximation of the message data and not a canonical view of its
contents, a client MUST NOT assume that a message preview is contents, a client <bcp14>MUST NOT</bcp14> assume that a message preview is
immutable for a given message. This relaxed requirement permits a immutable for a given message. This relaxed requirement permits a
server to offer previews as an option without requiring potentially server to offer previews as an option without requiring potentially
burdensome storage and/or processing requirements to guarantee burdensome storage and/or processing requirements to guarantee
immutability for a use case that does not require this strictness. immutability for a use case that does not require this strictness.
For example, the underlying IMAP server may change due to a system For example, the underlying IMAP server may change due to a system
software upgrade; an account's state information may be retained in software upgrade; an account's state information may be retained in
the migration but the new server may generate different PREVIEW the migration, but the new server may generate different preview
text than the old server.</t> text than the old server.</t>
<t>It is possible that the server has determined that no meaningful <t>It is possible that the server has determined that no meaningful
preview text can be generated for a particular message. Examples of preview text can be generated for a particular message. Examples of
this involve encrypted messages, content types the server does not this involve encrypted messages, content types the server does not
support previews of, and other situations where the server is not support previews of, and other situations where the server is not
able to extract information for a preview. In such cases, the able to extract information for a preview. In such cases, the
server MUST return a zero-length string. Clients SHOULD NOT send server <bcp14>MUST</bcp14> return a zero-length string. Clients <bcp14>S HOULD NOT</bcp14> send
another FETCH for a preview for such messages. (As discussed another FETCH for a preview for such messages. (As discussed
previously, preview data is not immutable so there is chance that previously, preview data is not immutable, so there is chance that
at some point in the future the server would be able to generate at some point in the future the server would be able to generate
meaningful text. However, this scenario is expected to be rare so a meaningful text. However, this scenario is expected to be rare, so a
client should not continually send out requests to try to capture client should not continually send out requests to try to detect
this infrequent occurrence.)</t> this infrequent occurrence.)</t>
<t>If the <xref format="default" target="LAZY">LAZY modifier</xref> is
<t>If the <xref format="none" target="LAZY">LAZY modifier</xref> is used, the server <bcp14>MAY</bcp14> return NIL for the preview response,
used, the server MAY return NIL for the preview response, indicating indicating
that preview generation could not be completed without causing that preview generation could not be completed without causing
undue delay. A server MUST NOT return NIL to a FETCH PREVIEW request undue delay. A server <bcp14>MUST NOT</bcp14> return NIL to a FETCH PREV IEW request
made without the LAZY modifier.</t> made without the LAZY modifier.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Preview Text Format"> <name>Preview Text Format</name>
<t>The generated preview text MUST be treated as <t>The generated preview text <bcp14>MUST</bcp14> be treated as
<xref target="RFC2046">text/plain</xref> media type data by the <xref target="RFC2046" format="default">text/plain</xref> media type dat
a by the
client.</t> client.</t>
<t>The generated string <bcp14>MUST NOT</bcp14> be content transfer enco
<t>The generated string MUST NOT be content transfer encoded and MUST ded and <bcp14>MUST</bcp14>
be encoded in <xref target="RFC3629">UTF-8</xref>. The server SHOULD be encoded in <xref target="RFC3629" format="default">UTF-8</xref>. The
server <bcp14>SHOULD</bcp14>
remove any formatting markup and do whatever processing might be remove any formatting markup and do whatever processing might be
useful in rendering the preview as plain text.</t> useful in rendering the preview as plain text.</t>
<t>For purposes of this section, a "preview character" is defined as a <t>For purposes of this section, a "preview character" is defined as a
single UCS character encoded in UTF-8. Note: a single preview single Universal Character Set (UCS) character encoded in UTF-8. Note: a single preview
character may compromise multiple octets, so any buffers implemented character may compromise multiple octets, so any buffers implemented
to conform to the string limitations identified in this document to conform to the string limitations identified in this document
should be sized to prevent possible overflow errors.</t> should be sized to prevent possible overflow errors.</t>
<t>The server <bcp14>SHOULD</bcp14> limit the length of the preview text
<t>The server SHOULD limit the length of the preview text to 200 to 200
preview characters. This length should provide sufficient data to preview characters. This length should provide sufficient data to
generally support both various languages (and their different average generally support both various languages (and their different average
word lengths) and diverse client display size requirements.</t> word lengths) and diverse client display size requirements.</t>
<t>The server <bcp14>MUST NOT</bcp14> output preview text longer than 25
<t>The server MUST NOT output preview text longer than 256 preview 6 preview
characters.</t> characters.</t>
<t>If the preview is not generated based on the body content of the <t>If the preview is not generated based on the body content of the
message, and the <xref target="RFC5255">LANGUAGE</xref> extension is message, and the <xref target="RFC5255" format="default">LANGUAGE extens
supported by the server, the preview text SHOULD be generated ion</xref> is
supported by the server, the preview text <bcp14>SHOULD</bcp14> be gener
ated
according to the language rules that apply to human-readable text. according to the language rules that apply to human-readable text.
For example, a message that consists of a single image MIME part has For example, a message that consists of a single image MIME part has
no human-readable text from which to generate preview information. no human-readable text from which to generate preview information.
Instead, the server may wish to output a description that the message Instead, the server may wish to output a description that the message
contains an image and describe some attributes of the image, such as contains an image and describe some attributes of the image, such as
image format, size, and filename. This descriptive text is not a image format, size, and filename. This descriptive text is not a
product of the message body itself but is rather auto-generated data product of the message body itself but is rather auto-generated data
by the server, and should thus use the rules defined for by the server; it should thus use the rules defined for
human-readable text described in the LANGUAGE extension (if human-readable text described in the LANGUAGE extension (if
supported on the server).</t> supported on the server).</t>
</section> </section>
</section> </section>
<section anchor="Lazy_Modifier" numbered="true" toc="default">
<section anchor="Lazy_Modifier" title="LAZY Priority Modifier"> <name>LAZY Priority Modifier</name>
<section anchor="LAZY" title="LAZY"> <section anchor="LAZY" numbered="true" toc="default">
<name>LAZY</name>
<t>The LAZY modifier directs the server to return the preview <t>The LAZY modifier directs the server to return the preview
representation only if that data can be returned without undue representation only if that data can be returned without undue
delay to the client.</t> delay to the client.</t>
<t>If this modifier is used, and the server is unable to return <t>If this modifier is used, and the server is unable to return
preview data without undue delay, the server MUST return NIL as the preview data without undue delay, the server <bcp14>MUST</bcp14> return NIL as the
preview response.</t> preview response.</t>
<t>The LAZY modifier <bcp14>MUST</bcp14> be implemented by any server th
<t>The LAZY modifier MUST be implemented by any server that supports at supports
the PREVIEW extension.</t> the PREVIEW extension.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Client Implementation Advice"> <name>Client Implementation Advice</name>
<t>Upon opening a mailbox, a client generally performs a FETCH of <t>Upon opening a mailbox, a client generally performs a FETCH of
message details in order to create a listing to present to the user message details in order to create a listing to present to the user
(e.g. ENVELOPE data). Using this extension, a client may want to (e.g., ENVELOPE data). Using this extension, a client may want to
additionally display preview information as part of this listing. additionally display preview information as part of this listing.
Quickly providing the base mailbox listing, with basic message Quickly providing the base mailbox listing with basic message
details, is the primary goal of this command as this is required details is the primary goal of this command as this is required
to allow the user to begin interacting with the mailbox. Preview data to allow the user to begin interacting with the mailbox. Preview data
is likely to be of secondary importance; it provides useful context, is likely to be of secondary importance; it provides useful context,
but it is not necessary to perform message actions. A client can but it is not necessary to perform message actions. A client can
load unavailable previews in the background and display them load unavailable previews in the background and display them
asynchronously to the user as the preview data is provided by the asynchronously to the user as the preview data is provided by the
server.</t> server.</t>
<t>In this scenario, the client would add the PREVIEW data item, with <t>In this scenario, the client would add the PREVIEW data item, with
the LAZY modifier, to the list of FETCH items needed to generate the the LAZY modifier, to the list of FETCH items needed to generate the
mailbox listing. This allows the server to advantageously return mailbox listing. This allows the server to advantageously return
preview data without blocking the primary goal of quickly returning preview data without blocking the primary goal of quickly returning
the basic message details used to generate the mailbox listing.</t> the basic message details used to generate the mailbox listing.</t>
<t>Once this initial FETCH is complete, the client can then issue <t>Once this initial FETCH is complete, the client can then issue
FETCH requests, without the LAZY modifier, to load the PREVIEW data FETCH requests, without the LAZY modifier, to load the PREVIEW data
item for the messages in which preview data was not returned. It is item for the messages in which preview data was not returned. It is
RECOMMENDED that these FETCH requests be issued in small batches, <bcp14>RECOMMENDED</bcp14> that these FETCH requests be issued in small batches,
e.g., 50 messages per FETCH command, since preview generation may be e.g., 50 messages per FETCH command, since preview generation may be
expensive and a single large request may exceed server resource expensive and a single large request may exceed server resource
limits.</t> limits.</t>
<t>See Example 2 in <xref target="Examples"/> for an implementation of t
<t>See <xref format="none" target="example_2">Example 2</xref> for his strategy.</t>
an implementation of this strategy.</t> <t>A client <bcp14>SHOULD NOT</bcp14> continually issue FETCH PREVIEW
requests with the LAZY modifier in a selected mailbox as the server is
<t>A client SHOULD NOT continually issue LAZY PREVIEW FETCH commands under no requirement to return preview information for this command,
in a selected mailbox as the server is under no requirement to return which could lead to an unnecessary waste of system and network
preview information for this command, which could lead to an resources.</t>
unnecessary waste of system and network resources.</t>
</section> </section>
</section> </section>
<section anchor="Examples" numbered="true" toc="default">
<section anchor="Examples" title="Examples"> <name>Examples</name>
<figure> <t keepWithNext="true">Example 1: Requesting preview without LAZY
<preamble>Example 1: Requesting PREVIEW without LAZY modifier.</t>
modifier.</preamble> <sourcecode name="" type=""><![CDATA[
<artwork><![CDATA[
C: A1 CAPABILITY C: A1 CAPABILITY
S: * CAPABILITY IMAP4rev1 PREVIEW S: * CAPABILITY IMAP4rev1 PREVIEW
S: A1 OK Capability command completed. S: A1 OK Capability command completed.
[...a mailbox is SELECTed...] [...a mailbox is SELECTed...]
C: A2 FETCH 1 (RFC822.SIZE PREVIEW) C: A2 FETCH 1 (RFC822.SIZE PREVIEW)
S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200} S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200}
S: Lorem ipsum dolor sit amet, consectetur adipiscing elit. S: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue. S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue.
S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla
S: ligula nullam S: ligula nullam
S: ) S: )
S: A2 OK FETCH complete. S: A2 OK FETCH complete.
]]></artwork> ]]></sourcecode>
</figure> <t keepWithNext="true">Example 2: Requesting preview with LAZY modifier, t
o
<figure anchor="example_2" suppress-title="true">
<preamble>Example 2: Requesting PREVIEW with LAZY modifier, to
obtain previews during initial mailbox listing if readily obtain previews during initial mailbox listing if readily
available; otherwise, load previews in background.</preamble> available; otherwise, load previews in background.</t>
<sourcecode name="" type=""><![CDATA[
<artwork><![CDATA[ C: B1 FETCH 1:4 (ENVELOPE PREVIEW (LAZY))
C: D1 FETCH 1:4 (ENVELOPE PREVIEW (LAZY))
S: * 1 FETCH (ENVELOPE ("Wed, 23 Sep 2020 15:03:11 +0000" [...]) S: * 1 FETCH (ENVELOPE ("Wed, 23 Sep 2020 15:03:11 +0000" [...])
PREVIEW "Preview text for message 1.") PREVIEW "Preview text for message 1.")
S: * 2 FETCH (PREVIEW "" ENVELOPE S: * 2 FETCH (PREVIEW "" ENVELOPE
("Thu, 24 Sep 2020 12:17:23 +0000" [...])) ("Thu, 24 Sep 2020 12:17:23 +0000" [...]))
S: * 3 FETCH (ENVELOPE ("Fri, 25 Sep 2020 09:13:45 +0000" [...]) S: * 3 FETCH (ENVELOPE ("Fri, 25 Sep 2020 09:13:45 +0000" [...])
PREVIEW NIL) PREVIEW NIL)
S: * 4 FETCH (ENVELOPE ("Sat, 26 Sep 2020 07:11:18 +0000" [...]) S: * 4 FETCH (ENVELOPE ("Sat, 26 Sep 2020 07:11:18 +0000" [...])
PREVIEW NIL) PREVIEW NIL)
S: D1 OK FETCH completed. S: B1 OK FETCH completed.
[...Client has preview for message 1 and knows that message 2 has [...Client has preview for message 1 and knows that message 2 has
a preview that is empty; only need to request preview of a preview that is empty; only need to request preview of
messages 3 & 4 (e.g. in background)...] messages 3 & 4 (e.g., in background)...]
C: D2 FETCH 3:4 (PREVIEW) C: B2 FETCH 3:4 (PREVIEW)
S: * 3 FETCH (PREVIEW {30} S: * 3 FETCH (PREVIEW {30}
S: Message data from message 3. S: Message data from message 3.
S: ) S: )
S: * 4 FETCH (PREVIEW "Message 4 preview") S: * 4 FETCH (PREVIEW "Message 4 preview")
S: D2 OK Fetch completed. S: B2 OK Fetch completed.
]]></artwork> ]]></sourcecode>
</figure> <t keepWithNext="true">Example 3: Requesting preview for
search results within a single mailbox. Use the <xref target="RFC5182"
<figure> format="default">SEARCHRES extension</xref> to save a round-trip.</t>
<preamble>Example 3: Retrieve preview information for search results <sourcecode name="" type=""><![CDATA[
within a single mailbox. Use <xref target="RFC5182">SEARCHRES</xref> C: C1 CAPABILITY
extension to save a round-trip.</preamble>
<artwork><![CDATA[
C: E1 CAPABILITY
S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES
S: E1 OK Capability command completed. S: C1 OK Capability command completed.
[...a mailbox is SELECTed...] [...a mailbox is SELECTed...]
C: E2 SEARCH RETURN (SAVE) FROM "FOO" C: C2 SEARCH RETURN (SAVE) FROM "FOO"
C: E3 FETCH $ (UID PREVIEW (LAZY)) C: C3 FETCH $ (UID PREVIEW (LAZY))
S: E2 OK SEARCH completed. S: C2 OK SEARCH completed.
S: * 5 FETCH (UID 13 PREVIEW "Preview!") S: * 5 FETCH (UID 13 PREVIEW "Preview!")
S: * 9 FETCH (UID 23 PREVIEW NIL) S: * 9 FETCH (UID 23 PREVIEW NIL)
S: E3 OK FETCH completed. S: C3 OK FETCH completed.
[...Retrieve message 9 preview in background...] [...Retrieve message 9 preview in background...]
C: E4 UID FETCH 23 (PREVIEW) C: C4 UID FETCH 23 (PREVIEW)
S: * 9 FETCH (UID 23 PREVIEW "Another preview!") S: * 9 FETCH (UID 23 PREVIEW "Another preview!")
S: E4 OK FETCH completed. S: C4 OK FETCH completed.
]]></artwork> ]]></sourcecode>
</figure>
</section> </section>
<section anchor="Syntax" numbered="true" toc="default">
<section anchor="Syntax" title="Formal Syntax"> <name>Formal Syntax</name>
<t>The following syntax specification uses the augmented Backus-Naur <t>The following syntax specification uses the Augmented Backus-Naur
Form (BNF) as described in <xref target="RFC5234">ABNF</xref>. It Form (ABNF) as described in <xref target="RFC5234" format="default"></xref
includes definitions from <xref target="RFC3501">IMAP</xref>.</t> >. It
includes definitions from <xref target="RFC3501" format="default">IMAP</xr
<figure> ef>.</t>
<artwork type="abnf"><![CDATA[ <sourcecode type="abnf" name=""><![CDATA[
capability =/ "PREVIEW" capability =/ "PREVIEW"
fetch-att =/ "PREVIEW" [SP "(" preview-mod *(SP fetch-att =/ "PREVIEW" [SP "(" preview-mod *(SP
preview-mod) ")"] preview-mod) ")"]
msg-att-dynamic =/ "PREVIEW" SP nstring msg-att-dynamic =/ "PREVIEW" SP nstring
preview-mod = "LAZY" preview-mod = "LAZY"
]]></artwork> ]]></sourcecode>
</figure>
</section> </section>
<section anchor="IANA" numbered="true" toc="default">
<section anchor="IANA" title="IANA Considerations"> <name>IANA Considerations</name>
<t><xref target="RFC3501">IMAP4</xref> capabilities are registered by <t><xref target="RFC3501" format="default">IMAP</xref> capabilities are
publishing a standards track or IESG-approved experimental RFC. registered by publishing a Standards Track or IESG-approved Experimental
The registry is currently located at: RFC in the "IMAP Capabilities" registry located at <eref
<list hangIndent="8" style="empty"> target="http://www.iana.org/assignments/imap-capabilities"
<t>http://www.iana.org/assignments/imap-capabilities</t> brackets="angle"/>.
</list>
</t> </t>
<t>This document requests that IANA adds the "PREVIEW" capability <t>IANA has added the "PREVIEW" capability to this registry.</t>
to the <xref target="RFC3501">IMAP4</xref> capabilities registry.</t>
</section> </section>
<section anchor="Security" numbered="true" toc="default">
<section anchor="Security" title="Security Considerations"> <name>Security Considerations</name>
<t>Implementation of this extension might enable denial-of-service <t>Implementation of this extension might enable denial-of-service
attacks against server resources, due to excessive memory or CPU usage attacks against server resources, due to excessive memory or CPU usage
during preview generation or increased storage usage if preview results during preview generation or increased storage usage if preview results
are stored on the server after generation. In order to mitigate such are stored on the server after generation. In order to mitigate such
attacks, servers SHOULD log the client authentication identity on FETCH attacks, servers <bcp14>SHOULD</bcp14> log the client authentication ident ity on FETCH
PREVIEW operations in order to facilitate tracking of abusive PREVIEW operations in order to facilitate tracking of abusive
clients.</t> clients.</t>
<t>Servers <bcp14>MAY</bcp14> limit the resources that preview generation
<t>Servers MAY limit the resources that preview generation uses. Such uses. Such
resource limitations might, in an extreme example, cause a server to resource limitations might, in an extreme example, cause a server to
return a preview that is the empty string for a message that otherwise return a preview that is the empty string for a message that otherwise
would have had a non-empty preview. However, it is recommended that at would have had a non-empty preview. However, it is recommended that at
least some preview text be provided in this situation, even if the least some preview text be provided in this situation, even if the
quality of the preview is degraded.</t> quality of the preview is degraded.</t>
<t>Just as the messages they summarize, preview data may contain <t>Just as the messages they summarize, preview data may contain
sensitive information. If generated preview data is stored on the sensitive information. If generated preview data is stored on the
server, e.g. for caching purposes, these previews MUST be protected with server, e.g., for caching purposes, these previews <bcp14>MUST</bcp14> be protected with
equivalent authorization and confidentiality controls as the source equivalent authorization and confidentiality controls as the source
message.</t> message.</t>
</section> </section>
</middle> </middle>
<back> <back>
<references title="Normative References"> <references>
&RFC2046; <name>References</name>
&RFC2119; <references>
&RFC3501; <name>Normative References</name>
&RFC3629; <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
&RFC5234; FC.2046.xml"/>
&RFC5255; <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
&RFC8174; FC.2119.xml"/>
</references> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.3501.xml"/>
<references title="Informative References"> <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
&RFC2045; FC.3629.xml"/>
&RFC2854; <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
&RFC5182; FC.5234.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.5255.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.8174.xml"/>
</references>
<references>
<name>Informative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.2045.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.2854.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R
FC.5182.xml"/>
</references>
</references> </references>
<section title="Change History (To be removed by RFC Editor before <section numbered="false" anchor="Acknowledgments" toc="default">
publication)"> <name>Acknowledgments</name>
<t>Changes from draft-slusarz-imap-fetch-snippet-00:
<list style='symbols'>
<t>Added standardized language to Section 2 regarding IMAP ABNF
conventions</t>
<t>Changed draft name to draft-ietf-extra-imap-fetch-snippet-##</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-snippet-00:
<list style='symbols'>
<t>Changed nomenclature from "snippet" to "preview"</t>
<t>Changed draft name to draft-ietf-extra-imap-fetch-preview-##</t>
<t>Update to RFC 8174 boilerplate</t>
<t>Updated length requirements for PREVIEW=FUZZY</t>
<t>Added preview-atom ABNF to limit use of "=" character</t>
<t>UTF-8 is a normative reference</t>
<t>Clarify that characters for purpose of length limitations are
defined as UCS characters as encoded by UTF-8</t>
<t>Fix some incorrect literal lengths in examples</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-00:
<list style='symbols'>
<t>Updated postal address</t>
<t>Added example to FETCH response section</t>
<t>Added example on how LANGUAGE extension may influence preview
generation</t>
<t>Added recommendation that only one LAZY FETCH be executed for a
message per mailbox</t>
<t>Added request to create algorithm and modifier registries</t>
<t>Added requirement that algorithm and modifier names conform
to RFC 6648</t>
<t>Added DoS attack info to security considerations</t>
<t>Distinguish between NIL response and zero-length string</t>
<t>Don't use deprecated "X-" convention in example</t>
<t>Spelling and nits</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-01:
<list style='symbols'>
<t>Fix capability ABNF</t>
<t>Removed CAPABILITY string for examples where it did not add
valuable context</t>
<t>Altered preview data in examples to cover a variety of
potential server return scenarios</t>
<t>Added "SHOULD be registered" language to algorithm names
and priority modifiers</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-02:
<list style='symbols'>
<t>Move Acknowledgments to un-numbered appendix</t>
<t>Improved abstract text</t>
<t>Consistently use "priority modifiers" instead of "modifiers"</t>
<t>Update example to conform with RFC 3501 UID FETCH
requirements</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-03:
<list style='symbols'>
<t>Remove preview modifier registry request</t>
<t>Improve instructions for registration of algorithms</t>
<t>Add storage information to security considerations</t>
<t>Clarify parsing of algorithm list in FETCH command</t>
<t>Clarify difference between NIL response and zero-length string</t>
<t>Add normative reference for text/plain</t>
<t>Add warning regarding buffers and multiple octet preview
characters</t>
<t>Clarify how to handle preview data return when using an explicit
algorithm list</t>
<t>Various editorial fixes</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-04:
<list style='symbols'>
<t>Make clear that preview caching is tied to retention period of
the source message</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-05:
<list style='symbols'>
<t>Clarify "zero-length string" preview data vs. NIL preview data</t>
<t>MIME data -> media type</t>
<t>Capability registration should not include the algorithm name</t>
<t>Give example of how PREVIEW data might change over time</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-06:
<list style='symbols'>
<t>Change algorithm names to media types</t>
<t>FUZZY algorithm changed to text/imap-fetch-preview</t>
<t>Remove server broadcast of PREVIEW algorithm extensions from
capability</t>
<t>Default, fallback algorithm in absence of client selection now
MUST be text/imap-fetch-preview</t>
<t>LAZY modifier should work on default algorithm if no specific
algorithm is provided as an argument</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-07:
<list style='symbols'>
<t>Remove algorithm selection; PREVIEW always returns text in
format defined in Section 3.3</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-08:
<list style='symbols'>
<t>FETCH PREVIEW without LAZY modifier MUST NOT return NIL</t>
<t>Improve client implementation advice for LAZY modifier</t>
</list>
</t>
<t>Changes from draft-ietf-extra-imap-fetch-preview-09:
<list style='symbols'>
<t>Clarified that string response is to be interpreted by user, not
the client</t>
<t>Give example behavior of resource limitation</t>
<t>Various editorial fixes</t>
</list>
</t>
</section>
<section numbered="false" anchor="Acknowledgments"
title="Acknowledgments">
<t>The author would like to thank the following people for their <t>The author would like to thank the following people for their
comments and contributions to this document: Stephan Bosch, Bron comments and contributions to this document: <contact fullname="Stephan
Gondwana, Teemu Huovila, Neil Jenkins, Steffen Lehmann, Barry Leiba, Bosch"/>, <contact fullname="Bron Gondwana"/>, <contact fullname="Teemu
Alexey Melnikov, Chris Newman, Pete Resnick, Jeff Sipek, Timo Sirainen, Huovila"/>, <contact fullname="Neil Jenkins"/>, <contact
Steffen Templin, and Aki Tuomi.</t> fullname="Steffen Lehmann"/>, <contact fullname="Barry Leiba"/>,
<contact fullname="Alexey Melnikov"/>, <contact fullname="Chris
Newman"/>, <contact fullname="Pete Resnick"/>, <contact fullname="Jeff
Sipek"/>, <contact fullname="Timo Sirainen"/>, <contact
fullname="Steffen Templin"/>, and <contact fullname="Aki Tuomi"/>.</t>
</section> </section>
</back> </back>
</rfc> </rfc>
 End of changes. 83 change blocks. 
343 lines changed or deleted 198 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/