--- 1/draft-ietf-extra-imap-fetch-preview-03.txt 2019-04-24 22:13:13.041847574 -0700 +++ 2/draft-ietf-extra-imap-fetch-preview-04.txt 2019-04-24 22:13:13.073848379 -0700 @@ -1,18 +1,18 @@ EXTRA M. Slusarz Internet-Draft Open-Xchange Inc. -Intended status: Standards Track February 16, 2019 -Expires: August 20, 2019 +Intended status: Standards Track April 24, 2019 +Expires: October 26, 2019 IMAP4 Extension: Message Preview Generation - draft-ietf-extra-imap-fetch-preview-03 + draft-ietf-extra-imap-fetch-preview-04 Abstract This document specifies an Internet Message Access Protocol (IMAP) protocol extension allowing a client to request a server-generated abbreviated representation of message data useful as a contextual preview of the entire message. Status of This Memo @@ -22,21 +22,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on August 20, 2019. + This Internet-Draft will expire on October 26, 2019. Copyright Notice Copyright (c) 2019 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 @@ -50,24 +50,24 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions Used In This Document . . . . . . . . . . . . . . 3 3. FETCH Data Item . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Command . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 4 4. PREVIEW Algorithms . . . . . . . . . . . . . . . . . . . . . 5 4.1. FUZZY . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5. PREVIEW Priority Modifiers . . . . . . . . . . . . . . . . . 6 5.1. LAZY . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 - 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 10.2. Informative References . . . . . . . . . . . . . . . . . 11 Appendix A. Change History (To be removed by RFC Editor before publication) . . . . . . . . . . . . . . . . . . . . 11 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 13 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 1. Introduction @@ -100,31 +100,31 @@ 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 + Using server-generated previews allows global generation once per message, and then cached indefinitely. 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 by listing one or more capability names consisting of "PREVIEW=" followed by a supported preview algorithm name. This format provides for future upwards- compatible extensions and/or the ability to use locally-defined - preview algorithms and priority modifiers. + preview algorithms. 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 @@ -141,36 +141,42 @@ implementations must pay attention to the numbered rules at the beginning of [RFC3501] Section 9. 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. - If no algorithm identifier is provided, the server decides which of - its built-in algorithms to use to generate the preview text. + If no algorithm list is provided, the server decides which of its + built-in algorithms to use to generate the preview text. - Alternately, the client may explicitly indicate which algorithm(s) - should be used in a parenthesized list after the PREVIEW attribute - containing the name of the algorithm. These algorithms MUST be one - of the algorithms identified as supported in the PREVIEW capability - responses. If a client requests an algorithm that is unsupported, - the server MUST return a tagged BAD response. + The client may explicitly indicate which algorithm(s) should be used + to generate the preview list via a parenthesized list of algorithm + names output after the PREVIEW attribute. Unsupported algorithms in + the list MUST be ignored. If the list contains no supported + algorithms, the server MUST return a tagged BAD response to the FETCH + command. The order of the algorithms in the parenthesized list (from left to right) defines the client's priority decision. Duplicate algorithms in the list SHOULD be ignored. For purposes of duplicate detection, priority modifiers (Section 5) should be ignored. A server MUST honor a client's algorithm priority decision. + A server should return preview data for the first algorithm that + returns non-empty preview text. Non-empty preview text is defined as + either the NIL response or an empty string. If no algorithm produces + non-empty preview text, the server should respond with the preview + data generated by the final algorithm in the list. + 3.2. Response The algorithm used by the server to generate the preview is returned preceding the preview string. The server returns a variable-length string that is the generated preview for that message. Example: Retrieving preview information in a SELECTed mailbox @@ -183,58 +189,70 @@ be a representation 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. If the preview is not available, the server MUST return NIL as the PREVIEW response. A NIL response indicates to the client that preview information MAY become available in a future PREVIEW FETCH - request. Note that this is semantically different than returning a - zero-length string, which indicates an empty preview. + request. + + Examples why a preview may not be available include: the preview + generation process is not available due to transient server resource + limitations, the message body text is unavailable, or a server- + imposed timeout was reached during generation. + + A NIL response is semantically different than returning a zero-length + string, which indicates that no meaningful preview text can be + generated for the message. 4. PREVIEW Algorithms 4.1. FUZZY The FUZZY algorithm directs the server to use any internal algorithm it desires, subject to the below limitations, to generate a textual preview for a message. The FUZZY algorithm MUST be implemented by any server that supports the PREVIEW extension. + The preview text MUST be treated as text/plain [RFC2046] MIME data by + the client. + The generated string MUST NOT be content transfer encoded and MUST be - encoded in UTF-8 [RFC3629]. For purposes of this section, a "preview - character" is defined as a single UCS character encoded in UTF-8. + encoded in UTF-8 [RFC3629]. The server SHOULD remove any formatting + markup and do what other processing might be useful in rendering the + preview as plain text. - The preview text MUST be treated as text/plain MIME data by the - client. + For purposes of this section, a "preview character" is defined as a + single UCS character encoded in UTF-8. Note: a single preview + character may compromise 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 different client display size requirements. The server MUST NOT output preview text longer than 256 preview characters. - The server SHOULD remove any formatting markup that exists in the - original text. - If the FUZZY algorithm generates a preview that is not based on the body content of the message and the LANGUAGE [RFC5255] extension is supported by the server, the preview text SHOULD be generated - according to the 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 to generate preview information from. + 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, and should thus use the rules defined for human- generated text described in the LANGUAGE extension (if supported on the server). 5. PREVIEW Priority Modifiers @@ -347,81 +366,84 @@ C: E4 UID FETCH 23 (PREVIEW (FUZZY)) S: * 9 FETCH (UID 23 PREVIEW (FUZZY "Another preview!")) S: E4 OK FETCH completed. 7. Formal Syntax The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in ABNF [RFC5234]. It includes definitions from IMAP [RFC3501]. - capability =/ "PREVIEW=" (preview-alg / preview-mod-ext) + capability =/ "PREVIEW=" preview-alg fetch-att =/ "PREVIEW" [SP "(" preview-alg-fetch *(SP preview-alg-fetch) ")"] msg-att-dynamic =/ "PREVIEW" SP "(" preview-alg SP nstring ")" preview-alg = "FUZZY" / preview-alg-ext preview-alg-ext = preview-atom ; New algorithm names SHOULD be ; registered with IANA and MUST ; conform with the ; recommendations described in - ; RFC 6648, Section 3 + ; [RFC6648], Section 3 preview-alg-fetch = preview-alg / preview-mod "=" preview-alg preview-atom = 1*. + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, . [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO @@ -437,20 +459,25 @@ Message Access Protocol Internationalization", RFC 5255, DOI 10.17487/RFC5255, June 2008, . [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating the "X-" Prefix and Similar Constructs in Application Protocols", BCP 178, RFC 6648, DOI 10.17487/RFC6648, June 2012, . + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 10.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, . @@ -527,25 +554,46 @@ server return scenarios o Added "SHOULD be registered" language to algorithm names and priority modifiers Changes from draft-ietf-extra-imap-fetch-preview-02: o Move Acknowledgments to un-numbered appendix o Improved abstract text - o Consistently use "priority modifiers" instead of "modifiers" o Update example to conform with RFC 3501 UID FETCH requirements + Changes from draft-ietf-extra-imap-fetch-preview-03: + + o Remove preview modifier registry request + + o Improve instructions for registration of algorithms + + o Add storage information to security considerations + + o Clarify parsing of algorithm list in FETCH command + + o Clarify difference between NIL response and zero-length string + + o Add normative reference for text/plain + + o Add warning regarding buffers and multiple octet preview + characters + + o Clarify how to handle preview data return when using an explicit + algorithm list + + o Various editorial fixes + Acknowledgments The author would like to thank the following people for their comments and contributions to this document: Stephan Bosch, Bron Gondwana, Teemu Huovila, Steffen Lehmann, Alexey Melnikov, Chris Newman, Jeff Sipek, Timo Sirainen, Steffen Templin, and Aki Tuomi. Author's Address Michael M. Slusarz