doc: Add RFC documents

1 files changed, 451 insertions, 0 deletions

diff --git a/doc/rfc/rfc8970.txt b/doc/rfc/rfc8970.txt
new file mode 100644
index 0000000..d40f47a
--- /dev/null
+++ b/doc/rfc/rfc8970.txt
@@ -0,0 +1,451 @@
+
+
+
+
+Internet Engineering Task Force (IETF)                        M. Slusarz
+Request for Comments: 8970                             Open-Xchange Inc.
+Category: Standards Track                                  December 2020
+ISSN: 2070-1721
+
+
+              IMAP4 Extension: Message Preview Generation
+
+Abstract
+
+   This document specifies an Internet Message Access Protocol (IMAP)
+   protocol extension that allows a client to request a server-generated
+   abbreviated text representation of message data that is useful as a
+   contextual preview of the entire message.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc8970.
+
+Copyright Notice
+
+   Copyright (c) 2020 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+Table of Contents
+
+   1.  Introduction
+   2.  Conventions Used in This Document
+   3.  FETCH Data Item
+     3.1.  Command
+     3.2.  Response
+     3.3.  Preview Text Format
+   4.  LAZY Priority Modifier
+     4.1.  LAZY
+     4.2.  Client Implementation Advice
+   5.  Examples
+   6.  Formal Syntax
+   7.  IANA Considerations
+   8.  Security Considerations
+   9.  References
+     9.1.  Normative References
+     9.2.  Informative References
+   Acknowledgments
+   Author's Address
+
+1.  Introduction
+
+   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
+   in viewing the full message contents.  Mail clients implementing the
+   Internet Message Access Protocol [RFC3501] would benefit from a
+   standardized, consistent way to generate these brief textual previews
+   of messages.
+
+   Generation of a preview on the server has several benefits.  First,
+   it allows consistent representation of previews across all clients.
+   While different clients might generate quite different preview text,
+   having common preview text generated by the server can give a more
+   consistent user experience to those who use multiple clients.
+
+   Second, server-side preview generation is more efficient.  A client-
+   based algorithm needs to issue, at a minimum, a FETCH BODYSTRUCTURE
+   command in order to determine which MIME [RFC2045] body part(s)
+   should be represented in the preview.  Subsequently, at least one
+   FETCH BODY command may be needed to retrieve body data used in
+   preview generation.  These FETCH commands cannot be pipelined since
+   the BODYSTRUCTURE query must be parsed on the client before the list
+   of parts to be retrieved via the BODY command(s) can be determined.
+
+   Additionally, it may be difficult to predict the amount of body data
+   that must be retrieved to adequately represent the part via a
+   preview, therefore requiring inefficient fetching of excessive data
+   in order to account for this uncertainty.  For example, a preview
+   algorithm to display data contained in a text/html [RFC2854] part
+   will likely strip the markup tags to obtain textual content.
+   However, without 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 part is retrieved or 2) an additional partial
+   FETCH is executed when the client determines that it does not possess
+   sufficient data from a previous partial FETCH to display an adequate
+   representation of the preview.
+
+   Finally, server generation allows caching in a centralized location.
+   Using server-generated previews allows global generation once per
+   message, and that preview can be cached for the retention period of
+   the source message.  Retrieval of message data may be expensive
+   within a server, for example, so a server can be configured to reduce
+   its storage retrieval load by pre-generating preview data.
+
+   A server indicates support for this extension via the "PREVIEW"
+   capability name.
+
+2.  Conventions Used in This Document
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+   "User" is used to refer to a human user, whereas "client" refers to
+   the software being run by the user.
+
+   In examples, "C:" and "S:" indicate lines sent by the client and
+   server, respectively.  If a single "C:" or "S:" label applies to
+   multiple lines, then the line breaks between those lines are for
+   editorial clarity only and are not part of the actual protocol
+   exchange.
+
+   As with all IMAP extension documents, the case used in writing IMAP
+   protocol elements herein is chosen for editorial clarity, and
+   implementations must pay attention to the numbered rules at the
+   beginning of Section 9 of [RFC3501].
+
+3.  FETCH Data Item
+
+3.1.  Command
+
+   To retrieve a preview for a message, the PREVIEW FETCH attribute is
+   used when issuing a FETCH command.
+
+3.2.  Response
+
+   The server returns a variable-length string that is the generated
+   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
+   intended to be interpreted in any way by the client software.
+
+   Example: Retrieving preview information in a SELECTed mailbox.
+
+     C: A1 FETCH 1 (PREVIEW)
+     S: * 1 FETCH (PREVIEW "Preview text!")
+     S: A1 OK FETCH complete.
+
+   A server SHOULD strive to generate the same string for a given
+   message for each request.  However, since previews are understood to
+   be an approximation of the message data and not a canonical view of
+   its contents, a client MUST NOT assume that a message preview is
+   immutable for a given message.  This relaxed requirement permits a
+   server to offer previews as an option without requiring potentially
+   burdensome storage and/or processing requirements to guarantee
+   immutability for a use case that does not require this strictness.
+   For example, the underlying IMAP server may change due to a system
+   software upgrade; an account's state information may be retained in
+   the migration, but the new server may generate different preview text
+   than the old server.
+
+   It is possible that the server has determined that no meaningful
+   preview text can be generated for a particular message.  Examples of
+   this involve encrypted messages, content types the server does not
+   support previews of, and other situations where the server is not
+   able to extract information for a preview.  In such cases, the server
+   MUST return a zero-length string.  Clients SHOULD NOT send another
+   FETCH for a preview for such messages.  (As discussed previously,
+   preview data is not immutable, so there is chance that 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 client should not
+   continually send out requests to try to detect this infrequent
+   occurrence.)
+
+   If the LAZY modifier (Section 4.1) is used, the server MAY return NIL
+   for the preview response, indicating that preview generation could
+   not be completed without causing undue delay.  A server MUST NOT
+   return NIL to a FETCH PREVIEW request made without the LAZY modifier.
+
+3.3.  Preview Text Format
+
+   The generated preview text MUST be treated as text/plain [RFC2046]
+   media type data by the client.
+
+   The generated string MUST NOT be content transfer encoded and MUST be
+   encoded in UTF-8 [RFC3629].  The server SHOULD remove any formatting
+   markup and do whatever processing might be useful in rendering the
+   preview as plain text.
+
+   For purposes of this section, a "preview character" is defined as a
+   single Universal Character Set (UCS) character encoded in UTF-8.
+   Note: a single preview character may comprise multiple octets, so any
+   buffers implemented to conform to the string limitations identified
+   in this document should be sized to prevent possible overflow errors.
+
+   The server SHOULD limit the length of the preview text to 200 preview
+   characters.  This length should provide sufficient data to generally
+   support both various languages (and their different average word
+   lengths) and diverse client display size requirements.
+
+   The server MUST NOT output preview text longer than 256 preview
+   characters.
+
+   If the preview is not generated based on the body content of the
+   message, and the LANGUAGE extension [RFC5255] is supported by the
+   server, the preview text SHOULD be generated according to the
+   language rules that apply to human-readable text.  For example, a
+   message that consists of a single image MIME part has no human-
+   readable text from which to generate preview information.  Instead,
+   the server may wish to output a description that the message contains
+   an image and describe some attributes of the image, such as image
+   format, size, and filename.  This descriptive text is not a product
+   of the message body itself but is rather auto-generated data by the
+   server; it should thus use the rules defined for human-readable text
+   described in the LANGUAGE extension (if supported on the server).
+
+4.  LAZY Priority Modifier
+
+4.1.  LAZY
+
+   The LAZY modifier directs the server to return the preview
+   representation only if that data can be returned without undue delay
+   to the client.
+
+   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
+   response.
+
+   The LAZY modifier MUST be implemented by any server that supports the
+   PREVIEW extension.
+
+4.2.  Client Implementation Advice
+
+   Upon opening a mailbox, a client generally performs a FETCH of
+   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
+   additionally display preview information as part of this listing.
+   Quickly providing the base mailbox listing with basic message details
+   is the primary goal of this command as this is required to allow the
+   user to begin interacting with the mailbox.  Preview data is likely
+   to be of secondary importance; it provides useful context, but it is
+   not necessary to perform message actions.  A client can load
+   unavailable previews in the background and display them
+   asynchronously to the user as the preview data is provided by the
+   server.
+
+   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
+   mailbox listing.  This allows the server to advantageously return
+   preview data without blocking the primary goal of quickly returning
+   the basic message details used to generate the mailbox listing.
+
+   Once this initial FETCH is complete, the client can then issue FETCH
+   requests, without the LAZY modifier, to load the PREVIEW data item
+   for the messages in which preview data was not returned.  It is
+   RECOMMENDED that these FETCH requests be issued in small batches,
+   e.g., 50 messages per FETCH command, since preview generation may be
+   expensive and a single large request may exceed server resource
+   limits.
+
+   See Example 2 in Section 5 for an implementation of this strategy.
+
+   A client SHOULD NOT continually issue FETCH PREVIEW requests with the
+   LAZY modifier in a selected mailbox as the server is under no
+   requirement to return preview information for this command, which
+   could lead to an unnecessary waste of system and network resources.
+
+5.  Examples
+
+   Example 1: Requesting preview without LAZY modifier.
+
+     C: A1 CAPABILITY
+     S: * CAPABILITY IMAP4rev1 PREVIEW
+     S: A1 OK Capability command completed.
+     [...a mailbox is SELECTed...]
+     C: A2 FETCH 1 (RFC822.SIZE PREVIEW)
+     S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW {200}
+     S: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+     S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue.
+     S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla
+     S: ligula nullam
+     S: )
+     S: A2 OK FETCH complete.
+
+   Example 2: Requesting preview with LAZY modifier, to obtain previews
+   during initial mailbox listing if readily available; otherwise, load
+   previews in background.
+
+     C: B1 FETCH 1:4 (ENVELOPE PREVIEW (LAZY))
+     S: * 1 FETCH (ENVELOPE ("Wed, 23 Sep 2020 15:03:11 +0000" [...])
+        PREVIEW "Preview text for message 1.")
+     S: * 2 FETCH (PREVIEW "" ENVELOPE
+        ("Thu, 24 Sep 2020 12:17:23 +0000" [...]))
+     S: * 3 FETCH (ENVELOPE ("Fri, 25 Sep 2020 09:13:45 +0000" [...])
+        PREVIEW NIL)
+     S: * 4 FETCH (ENVELOPE ("Sat, 26 Sep 2020 07:11:18 +0000" [...])
+        PREVIEW NIL)
+     S: B1 OK FETCH completed.
+     [...Client has preview for message 1 and knows that message 2 has
+         a preview that is empty; only need to request preview of
+         messages 3 & 4 (e.g., in background)...]
+     C: B2 FETCH 3:4 (PREVIEW)
+     S: * 3 FETCH (PREVIEW {30}
+     S: Message data from message 3.
+     S: )
+     S: * 4 FETCH (PREVIEW "Message 4 preview")
+     S: B2 OK Fetch completed.
+
+   Example 3: Requesting preview for search results within a single
+   mailbox.  Use the SEARCHRES extension [RFC5182] to save a round-trip.
+
+     C: C1 CAPABILITY
+     S: * CAPABILITY IMAP4rev1 PREVIEW SEARCHRES
+     S: C1 OK Capability command completed.
+     [...a mailbox is SELECTed...]
+     C: C2 SEARCH RETURN (SAVE) FROM "FOO"
+     C: C3 FETCH $ (UID PREVIEW (LAZY))
+     S: C2 OK SEARCH completed.
+     S: * 5 FETCH (UID 13 PREVIEW "Preview!")
+     S: * 9 FETCH (UID 23 PREVIEW NIL)
+     S: C3 OK FETCH completed.
+     [...Retrieve message 9 preview in background...]
+     C: C4 UID FETCH 23 (PREVIEW)
+     S: * 9 FETCH (UID 23 PREVIEW "Another preview!")
+     S: C4 OK FETCH completed.
+
+6.  Formal Syntax
+
+   The following syntax specification uses the Augmented Backus-Naur
+   Form (ABNF) as described in [RFC5234].  It includes definitions from
+   IMAP [RFC3501].
+
+     capability        =/ "PREVIEW"
+
+     fetch-att         =/ "PREVIEW" [SP "(" preview-mod *(SP
+                          preview-mod) ")"]
+
+     msg-att-dynamic   =/ "PREVIEW" SP nstring
+
+     preview-mod       =  "LAZY"
+
+7.  IANA Considerations
+
+   IMAP [RFC3501] capabilities are registered by publishing a Standards
+   Track or IESG-approved Experimental RFC in the "IMAP Capabilities"
+   registry located at <http://www.iana.org/assignments/imap-
+   capabilities>.
+
+   IANA has added the "PREVIEW" capability to this registry.
+
+8.  Security Considerations
+
+   Implementation of this extension might enable denial-of-service
+   attacks against server resources, due to excessive memory or CPU
+   usage during preview generation or increased storage usage if preview
+   results are stored on the server after generation.  In order to
+   mitigate such attacks, servers SHOULD log the client authentication
+   identity on FETCH PREVIEW operations in order to facilitate tracking
+   of abusive clients.
+
+   Servers MAY limit the resources that preview generation uses.  Such
+   resource limitations might, in an extreme example, cause a server to
+   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 least some preview text be provided in this
+   situation, even if the quality of the preview is degraded.
+
+   Just as the messages they summarize, preview data may contain
+   sensitive information.  If generated preview data is stored on the
+   server, e.g., for caching purposes, these previews MUST be protected
+   with equivalent authorization and confidentiality controls as the
+   source message.
+
+9.  References
+
+9.1.  Normative References
+
+   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+              Extensions (MIME) Part Two: Media Types", RFC 2046,
+              DOI 10.17487/RFC2046, November 1996,
+              <https://www.rfc-editor.org/info/rfc2046>.
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+              4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003,
+              <https://www.rfc-editor.org/info/rfc3501>.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November
+              2003, <https://www.rfc-editor.org/info/rfc3629>.
+
+   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234,
+              DOI 10.17487/RFC5234, January 2008,
+              <https://www.rfc-editor.org/info/rfc5234>.
+
+   [RFC5255]  Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
+              Message Access Protocol Internationalization", RFC 5255,
+              DOI 10.17487/RFC5255, June 2008,
+              <https://www.rfc-editor.org/info/rfc5255>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+9.2.  Informative References
+
+   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+              Extensions (MIME) Part One: Format of Internet Message
+              Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
+              <https://www.rfc-editor.org/info/rfc2045>.
+
+   [RFC2854]  Connolly, D. and L. Masinter, "The 'text/html' Media
+              Type", RFC 2854, DOI 10.17487/RFC2854, June 2000,
+              <https://www.rfc-editor.org/info/rfc2854>.
+
+   [RFC5182]  Melnikov, A., "IMAP Extension for Referencing the Last
+              SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March
+              2008, <https://www.rfc-editor.org/info/rfc5182>.
+
+Acknowledgments
+
+   The author would like to thank the following people for their
+   comments and contributions to this document: Stephan Bosch, Bron
+   Gondwana, Teemu Huovila, Neil Jenkins, Steffen Lehmann, Barry Leiba,
+   Alexey Melnikov, Chris Newman, Pete Resnick, Jeff Sipek, Timo
+   Sirainen, Steffen Templin, and Aki Tuomi.
+
+Author's Address
+
+   Michael M. Slusarz
+   Open-Xchange Inc.
+   530 Lytton Avenue
+   Palo Alto, California 94301
+   United States of America
+
+   Email: michael.slusarz@open-xchange.com