idnits 2.17.1 draft-ietf-extra-imap-fetch-preview-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 5, 2018) is 1993 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 EXTRA M. Slusarz 3 Internet-Draft Open-Xchange Inc. 4 Intended status: Standards Track November 5, 2018 5 Expires: May 9, 2019 7 IMAP4 Extension: Message Preview Generation 8 draft-ietf-extra-imap-fetch-preview-00 10 Abstract 12 This document specifies an IMAP protocol extension which allows a 13 client to request that a server provide an abbreviated representation 14 of a message that can be used by a client to provide a useful 15 contextual preview of the message contents. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on May 9, 2019. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used In This Document . . . . . . . . . . . . . . 3 53 3. FETCH Data Item . . . . . . . . . . . . . . . . . . . . . . . 4 54 3.1. Command . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4. PREVIEW Algorithms . . . . . . . . . . . . . . . . . . . . . 5 57 4.1. FUZZY . . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 5. PREVIEW Priority Modifiers . . . . . . . . . . . . . . . . . 5 59 5.1. LAZY . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 62 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 63 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 64 10. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 66 11.1. Normative References . . . . . . . . . . . . . . . . . . 10 67 11.2. Informative References . . . . . . . . . . . . . . . . . 10 68 Appendix A. Change History (To be removed by RFC Editor before 69 publication) . . . . . . . . . . . . . . . . . . . . 11 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 Many modern mail clients display small extracts of the body text as 75 an aid to allow a user to quickly decide whether they are interested 76 in viewing the full message contents. Mail clients implementing the 77 Internet Message Access Protocol [RFC3501] would benefit from a 78 standardized, consistent way to generate these brief previews of 79 messages. 81 Generation of a preview on the server has several benefits. First, 82 it allows consistent representation of previews across all clients. 83 This standardized display can reduce user confusion when using 84 multiple clients, as abbreviated message representations in clients 85 will show identical message details. 87 Second, server-side preview generation is more efficient. A client- 88 based algorithm needs to issue, at a minimum, a FETCH BODYSTRUCTURE 89 command in order to determine which MIME [RFC2045] body part(s) 90 should be represented in the preview. Subsequently, at least one 91 FETCH BODY command may be needed to retrieve body data used in 92 preview generation. These FETCH commands cannot be pipelined since 93 the BODYSTRUCTURE query must be parsed on the client before the list 94 of parts to be retrieved via the BODY command(s) can be determined. 96 Additionally, it may be difficult to predict the amount of body data 97 that must be retrieved to adequately represent the part via a 98 preview, therefore requiring inefficient fetching of excessive data 99 in order to account for this uncertainty. For example, a preview 100 algorithm to display data contained in a text/html [RFC2854] part 101 will likely strip the markup tags to obtain textual content. 102 However, without fetching the entire content of the part, there is no 103 way to guarantee that sufficient non-tag content will exist unless 104 either 1) the entire part is retrieved or 2) an additional partial 105 FETCH is executed when the client determines that it does not possess 106 sufficient data from a previous partial FETCH to display an adequate 107 representation of the preview. 109 Finally, server generation allows caching in a centralized location. 110 Using server generated previews allows them to be generated globally 111 once per message, and then cached indefinitely. Retrieval of message 112 data may be expensive within a server, for example, so a server can 113 be configured to reduce its storage retrieval load by pre-generating 114 preview data. 116 A server that supports the PREVIEW extension indicates this with one 117 or more capability names consisting of "PREVIEW=" followed by a 118 supported preview algorithm name. This format provides for future 119 upwards-compatible extensions and/or the ability to use locally- 120 defined preview algorithms. 122 2. Conventions Used In This Document 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 14 [RFC2119] [RFC8174] when, and only when, they appear in all 128 capitals, as shown here. 130 "User" is used to refer to a human user, whereas "client" refers to 131 the software being run by the user. 133 In examples, "C:" and "S:" indicate lines sent by the client and 134 server respectively. If a single "C:" or "S:" label applies to 135 multiple lines, then the line breaks between those lines are for 136 editorial clarity only and are not part of the actual protocol 137 exchange. 139 As with all IMAP extension documents, the case used in writing IMAP 140 protocol elements herein is chosen for editorial clarity, and 141 implementations must pay attention to the numbered rules at the 142 beginning of [RFC3501] Section 9. 144 3. FETCH Data Item 146 3.1. Command 148 To retrieve a preview for a message, the "PREVIEW" FETCH attribute is 149 used when issuing a FETCH command. 151 If no algorithm identifier is provided, the server decides which of 152 its built-in algorithms to use to generate the preview text. 154 Alternately, the client may explicitly indicate which algorithm(s) 155 should be used in a parenthesized list after the PREVIEW attribute 156 containing the name of the algorithm. These algorithms MUST be one 157 of the algorithms identified as supported in the PREVIEW capability 158 responses. If a client requests an algorithm that is unsupported, 159 the server MUST return a tagged BAD response. 161 The order of the algorithms in the parenthesized list (from left to 162 right) defines the client's priority decision. Duplicate algorithms 163 in the list SHOULD be ignored. For purposes of duplicate detection, 164 priority modifiers (Section 5) should be ignored. A server MUST 165 honor a client's algorithm priority decision. 167 3.2. Response 169 The algorithm used by the server to generate the preview is returned 170 preceding the preview string. 172 The server returns a variable-length string that is the generated 173 preview for that message. 175 A server SHOULD strive to generate the same string for a given 176 message for each request. However, since previews are understood to 177 be a representation of the message data and not a canonical view of 178 its contents, a client MUST NOT assume that a message preview is 179 immutable for a given message. This relaxed requirement permits a 180 server to offer previews as an option without requiring potentially 181 burdensome storage and/or processing requirements to guarantee 182 immutability for a use case that does not require this strictness. 184 If the preview is not available, the server MUST return NIL as the 185 PREVIEW response. A NIL response indicates to the client that 186 preview information MAY become available in a future PREVIEW FETCH 187 request. 189 4. PREVIEW Algorithms 191 4.1. FUZZY 193 The FUZZY algorithm directs the server to use any internal algorithm 194 it desires, subject to the below limitations, to generate a textual 195 preview for a message. 197 The FUZZY algorithm MUST be implemented by any server that supports 198 the PREVIEW extension. 200 The generated string MUST NOT be content transfer encoded and MUST be 201 encoded in UTF-8 [RFC3629]. For purposes of this section, a "preview 202 character" is defined as a single UCS character encoded in UTF-8. 204 The preview text MUST be treated as text/plain MIME data by the 205 client. 207 The server SHOULD limit the length of the preview text to 200 preview 208 characters. This length should provide sufficient data to generally 209 support both various languages (and their different average word 210 lengths) and different client display size requirements. 212 The server MUST NOT output preview text longer than 256 preview 213 characters. 215 The server SHOULD remove any formatting markup that exists in the 216 original text. 218 If the FUZZY algorithm generates a preview that is not based on the 219 body content of the message and the LANGUAGE [RFC5255] extension is 220 supported by the server, the preview text SHOULD be generated 221 according to the the language rules that apply to human-readable 222 text. 224 5. PREVIEW Priority Modifiers 226 5.1. LAZY 228 The LAZY modifier directs the server to return the preview 229 representation only if that data can be returned without undue delay 230 to the client. 232 This modifier allows a client to inform the server that preview data 233 is nice-to-have, but the server SHOULD NOT block the return of other 234 FETCH information at the expense of generating the preview data. 236 For example, a client displaying the initial mailbox listing to a 237 user may want to display preview information associated with messages 238 in that listing. However, this information is secondary to providing 239 the mailbox listing, with message details, and the client is willing 240 to load any unavailable previwes in the background and display them 241 as they are provided by the server. In this case, the client would 242 use the LAZY modifier to the desired algorithm(s) to direct the 243 server to only return pre-generated preview data so that retrieval of 244 the other FETCH information is not blocked by possibly expensive 245 preview generation. 247 The LAZY modifier MUST be implemented by any server that supports the 248 PREVIEW extension. 250 6. Examples 252 Example 1: Requesting FETCH without explicit algorithm selection 254 C: A1 CAPABILITY 255 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 256 S: A1 OK Capability command completed. 257 [...a mailbox is SELECTed...] 258 C: A2 FETCH 1 (RFC822.SIZE PREVIEW) 259 S: * 1 FETCH (RFC822.SIZE 20000 PREVIEW (FUZZY {58} 260 S: This is the first line of text from the first text part. 261 S: )) 262 S: A2 OK FETCH complete. 264 Example 2: Requesting FETCH with explicit algorithm selection 266 C: B1 CAPABILITY 267 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 268 S: B1 OK Capability command completed. 269 [...a mailbox is SELECTed...] 270 C: B2 FETCH 1 (RFC822.SIZE PREVIEW (FUZZY)) 271 S: * 1 FETCH (RFC822.SIZE 20000 PREVIEW (FUZZY {58} 272 S: This is the first line of text from the first text part. 273 S: )) 274 S: B2 OK FETCH complete. 276 Example 3: Requesting FETCH with invalid explicit algorithm selection 278 C: C1 CAPABILITY 279 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 280 S: C1 OK Capability command completed. 281 [...a mailbox is SELECTed...] 282 C: C2 FETCH 1 (RFC822.SIZE PREVIEW (X-PREVIEW-ALGO)) 283 S: C2 BAD FETCH contains invalid preview algorithm name. 285 Example 4: Use explicit algorithm priority selection, with LAZY 286 modifier, to obtain previews during initial mailbox listing if 287 readily available; otherwise, load previews in background 289 C: D1 CAPABILITY 290 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 291 S: D1 OK Capability command completed. 292 [...a mailbox is SELECTed...] 293 C: D2 FETCH 1:3 (ENVELOPE PREVIEW (LAZY=FUZZY)) 294 S: * 1 FETCH (ENVELOPE ("Wed, 25 Oct 2017 15:03:11 +0000" [...]) 295 PREVIEW (FUZZY {58} 296 S: This is the first line of text from the first text part. 297 S: )) 298 S: * 2 FETCH (PREVIEW (FUZZY "") ENVELOPE 299 ("Thu, 26 Oct 2017 12:17:23 +0000" [...])) 300 S: * 3 FETCH (ENVELOPE ("Fri, 27 Oct 2017 22:19:21 +0000" [...]) 301 PREVIEW (FUZZY NIL)) 302 S: D2 OK FETCH completed. 303 [...Client knows that message 2 has a preview that is empty; 304 therefore, client only needs to request message 3 preview again 305 (e.g. in background)...] 306 C: D3 FETCH 3 (PREVIEW (FUZZY)) 307 S: * 3 FETCH (PREVIEW (FUZZY {27} 308 S: First sentence of mail 3. 309 S: )) 310 S: D3 OK Fetch completed. 312 Example 5: Retrieve preview information for search results within a 313 single mailbox. Use SEARCHRES [RFC5182] extension to save a round- 314 trip. 316 C: E1 CAPABILITY 317 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY SEARCHRES 318 S: E1 OK Capability command completed. 319 [...a mailbox is SELECTed...] 320 C: E2 SEARCH RETURN (SAVE) FROM "FOO" 321 C: E3 FETCH $ (UID PREVIEW (LAZY=FUZZY)) 322 S: E2 OK SEARCH completed. 323 S: * 5 FETCH (UID 13 PREVIEW (FUZZY {10} 324 S: Preview! 325 S: )) 326 S: * 9 FETCH (UID 23 PREVIEW (FUZZY NIL)) 327 S: E3 OK FETCH completed. 328 [...Retrieve message 9 preview in background...] 329 C: E4 UID FETCH 23 (PREVIEW (FUZZY)) 330 S: * 9 FETCH (PREVIEW (FUZZY {18} 331 S: Another preview! 332 S: )) 333 S: E4 OK FETCH completed. 335 7. Formal Syntax 337 The following syntax specification uses the augmented Backus-Naur 338 Form (BNF) as described in ABNF [RFC5234]. It includes definitions 339 from IMAP [RFC3501]. 341 capability =/ "PREVIEW=FUZZY" 343 fetch-att =/ "PREVIEW" [SP "(" preview-alg-fetch *(SP 344 preview-alg-fetch) ")"] 346 msg-att-dynamic =/ "PREVIEW" SP "(" preview-alg SP nstring ")" 348 preview-alg = "FUZZY" / preview-alg-ext 350 preview-alg-ext = preview-atom ; New algorithms MUST be 351 ; registered with IANA 353 preview-alg-fetch = preview-alg / preview-mod "=" preview-alg 355 preview-atom = 1*. 395 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 396 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 397 . 399 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 400 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 401 2003, . 403 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 404 Specifications: ABNF", STD 68, RFC 5234, 405 DOI 10.17487/RFC5234, January 2008, 406 . 408 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet 409 Message Access Protocol Internationalization", RFC 5255, 410 DOI 10.17487/RFC5255, June 2008, 411 . 413 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 414 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 415 May 2017, . 417 11.2. Informative References 419 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 420 Extensions (MIME) Part One: Format of Internet Message 421 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 422 . 424 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media 425 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000, 426 . 428 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 429 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March 430 2008, . 432 Appendix A. Change History (To be removed by RFC Editor before 433 publication) 435 Changes from draft-slusarz-imap-fetch-snippet-00: 437 o Added standardized language to Section 2 regarding IMAP ABNF 438 conventions 440 o Changed draft name to draft-ietf-extra-imap-fetch-snippet-## 442 Changes from draft-ietf-extra-imap-fetch-snippet-00: 444 o Changed nomenclature from "snippet" to "preview" 446 o Changed draft name to draft-ietf-extra-imap-fetch-preview-## 448 o Update to RFC 8174 boilerplate 450 o Updated length requirements for PREVIEW=FUZZY 452 o Added preview-atom ABNF to limit use of "=" character 454 o UTF-8 is a normative reference 456 o Clarify that characters for purpose of length limitations are 457 defined as UCS characters as encoded by UTF-8 459 o Fix some incorrect literal lengths in examples 461 Author's Address 463 Michael Slusarz 464 Open-Xchange Inc. 465 Denver, Colorado 466 US 468 Email: michael.slusarz@open-xchange.com