idnits 2.17.1 draft-ietf-extra-imap-fetch-preview-03.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 (February 16, 2019) is 1896 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) == Unused Reference: 'RFC6648' is defined on line 441, but no explicit reference was found in the text ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 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 February 16, 2019 5 Expires: August 20, 2019 7 IMAP4 Extension: Message Preview Generation 8 draft-ietf-extra-imap-fetch-preview-03 10 Abstract 12 This document specifies an Internet Message Access Protocol (IMAP) 13 protocol extension allowing a client to request a server-generated 14 abbreviated representation of message data useful as a contextual 15 preview of the entire message. 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 August 20, 2019. 34 Copyright Notice 36 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . 6 59 5.1. LAZY . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 62 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 63 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 64 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 66 10.2. Informative References . . . . . . . . . . . . . . . . . 11 67 Appendix A. Change History (To be removed by RFC Editor before 68 publication) . . . . . . . . . . . . . . . . . . . . 11 69 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 13 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 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 contents. 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 global generation once per 111 message, and then cached indefinitely. Retrieval of message data may 112 be expensive within a server, for example, so a server can be 113 configured to reduce its storage retrieval load by pre-generating 114 preview data. 116 A server indicates support for this extension by listing one or more 117 capability names consisting of "PREVIEW=" followed by a supported 118 preview algorithm name. This format provides for future upwards- 119 compatible extensions and/or the ability to use locally-defined 120 preview algorithms and priority modifiers. 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 Example: Retrieving preview information in a SELECTed mailbox 177 C: A1 FETCH 1 (PREVIEW) 178 S: * 1 FETCH (PREVIEW (FUZZY "Preview text!")) 179 S: A1 OK FETCH complete. 181 A server SHOULD strive to generate the same string for a given 182 message for each request. However, since previews are understood to 183 be a representation of the message data and not a canonical view of 184 its contents, a client MUST NOT assume that a message preview is 185 immutable for a given message. This relaxed requirement permits a 186 server to offer previews as an option without requiring potentially 187 burdensome storage and/or processing requirements to guarantee 188 immutability for a use case that does not require this strictness. 190 If the preview is not available, the server MUST return NIL as the 191 PREVIEW response. A NIL response indicates to the client that 192 preview information MAY become available in a future PREVIEW FETCH 193 request. Note that this is semantically different than returning a 194 zero-length string, which indicates an empty preview. 196 4. PREVIEW Algorithms 198 4.1. FUZZY 200 The FUZZY algorithm directs the server to use any internal algorithm 201 it desires, subject to the below limitations, to generate a textual 202 preview for a message. 204 The FUZZY algorithm MUST be implemented by any server that supports 205 the PREVIEW extension. 207 The generated string MUST NOT be content transfer encoded and MUST be 208 encoded in UTF-8 [RFC3629]. For purposes of this section, a "preview 209 character" is defined as a single UCS character encoded in UTF-8. 211 The preview text MUST be treated as text/plain MIME data by the 212 client. 214 The server SHOULD limit the length of the preview text to 200 preview 215 characters. This length should provide sufficient data to generally 216 support both various languages (and their different average word 217 lengths) and different client display size requirements. 219 The server MUST NOT output preview text longer than 256 preview 220 characters. 222 The server SHOULD remove any formatting markup that exists in the 223 original text. 225 If the FUZZY algorithm generates a preview that is not based on the 226 body content of the message and the LANGUAGE [RFC5255] extension is 227 supported by the server, the preview text SHOULD be generated 228 according to the the language rules that apply to human-readable 229 text. For example, a message that consists of a single image MIME 230 part has no human-readable text to generate preview information from. 231 Instead, the server may wish to output a description that the message 232 contains an image and describe some attributes of the image, such as 233 image format, size, and filename. This descriptive text is not a 234 product of the message body itself but is rather auto-generated data 235 by the server, and should thus use the rules defined for human- 236 generated text described in the LANGUAGE extension (if supported on 237 the server). 239 5. PREVIEW Priority Modifiers 241 5.1. LAZY 243 The LAZY modifier directs the server to return the preview 244 representation only if that data can be returned without undue delay 245 to the client. 247 This modifier allows a client to inform the server that preview data 248 is nice-to-have, but the server SHOULD NOT block the return of other 249 FETCH information at the expense of generating the preview data. 251 For example, a client displaying the initial mailbox listing to a 252 user may want to display preview information associated with messages 253 in that listing. However, this information is secondary to providing 254 the mailbox listing, with message details, and the client is willing 255 to load any unavailable previews in the background and display them 256 as they are provided by the server. In this case, the client would 257 apply the LAZY modifier to the desired algorithm(s) to direct the 258 server to only return pre-generated preview data so that retrieval of 259 the other FETCH information is not blocked by possibly expensive 260 preview generation. 262 Generally, the LAZY modifier will only be used once per mailbox load 263 during the initial listing. If preview information is not available 264 during this initial FETCH, the expectation is that a second non-LAZY 265 FETCH will take place after mailbox listing activities are complete. 266 Thus, a maximum of 2 PREVIEW FETCH queries should occur for any 267 message in a selected mailbox. A client SHOULD NOT continually issue 268 LAZY PREVIEW FETCH commands in a selected mailbox as the server is 269 under no requirement to return preview information for this command, 270 which could lead to an unnecessary waste of system and network 271 resources. See Example 4 in the Examples section for how this can be 272 implemented. 274 The LAZY modifier MUST be implemented by any server that supports the 275 PREVIEW extension. 277 6. Examples 278 Example 1: Requesting FETCH without explicit algorithm selection. 280 C: A1 CAPABILITY 281 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 282 S: A1 OK Capability command completed. 283 [...a mailbox is SELECTed...] 284 C: A2 FETCH 1 (RFC822.SIZE PREVIEW) 285 S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW (FUZZY {200} 286 S: Lorem ipsum dolor sit amet, consectetur adipiscing elit. 287 S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue. 288 S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla 289 S: ligula nullam 290 S: )) 291 S: A2 OK FETCH complete. 293 Example 2: Requesting FETCH with explicit algorithm selection. 295 C: B1 FETCH 1 (RFC822.SIZE PREVIEW (FUZZY)) 296 S: * 1 FETCH (RFC822.SIZE 91377 PREVIEW (FUZZY {53} 297 S: Preview text generated from message body text data. 298 S: )) 299 S: B1 OK FETCH complete. 301 Example 3: Requesting FETCH with invalid explicit algorithm 302 selection. 304 C: C1 CAPABILITY 305 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 306 S: C1 OK Capability command completed. 307 [...a mailbox is SELECTed...] 308 C: C2 FETCH 1 (RFC822.SIZE PREVIEW (UNKNOWN-PREVIEW-ALGO)) 309 S: C2 BAD FETCH contains invalid preview algorithm name. 311 Example 4: Use explicit algorithm priority selection, with LAZY 312 modifier, to obtain previews during initial mailbox listing if 313 readily available; otherwise, load previews in background. 315 C: D1 FETCH 1:3 (ENVELOPE PREVIEW (LAZY=FUZZY)) 316 S: * 1 FETCH (ENVELOPE ("Wed, 25 Oct 2017 15:03:11 +0000" [...]) 317 PREVIEW (FUZZY "Preview text for message 1.")) 318 S: * 2 FETCH (PREVIEW (FUZZY "") ENVELOPE 319 ("Thu, 26 Oct 2017 12:17:23 +0000" [...])) 320 S: * 3 FETCH (ENVELOPE ("Fri, 27 Oct 2017 22:19:21 +0000" [...]) 321 PREVIEW (FUZZY NIL)) 322 S: D1 OK FETCH completed. 323 [...Client knows that message 2 has a preview that is empty; 324 therefore, client only needs to request message 3 preview again 325 (e.g. in background)...] 326 C: D2 FETCH 3 (PREVIEW (FUZZY)) 327 S: * 3 FETCH (PREVIEW (FUZZY {30} 328 S: Message data from message 3. 329 S: )) 330 S: D2 OK Fetch completed. 332 Example 5: Retrieve preview information for search results within a 333 single mailbox. Use SEARCHRES [RFC5182] extension to save a round- 334 trip. 336 C: E1 CAPABILITY 337 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY SEARCHRES 338 S: E1 OK Capability command completed. 339 [...a mailbox is SELECTed...] 340 C: E2 SEARCH RETURN (SAVE) FROM "FOO" 341 C: E3 FETCH $ (UID PREVIEW (LAZY=FUZZY)) 342 S: E2 OK SEARCH completed. 343 S: * 5 FETCH (UID 13 PREVIEW (FUZZY "Preview!")) 344 S: * 9 FETCH (UID 23 PREVIEW (FUZZY NIL)) 345 S: E3 OK FETCH completed. 346 [...Retrieve message 9 preview in background...] 347 C: E4 UID FETCH 23 (PREVIEW (FUZZY)) 348 S: * 9 FETCH (UID 23 PREVIEW (FUZZY "Another preview!")) 349 S: E4 OK FETCH completed. 351 7. Formal Syntax 353 The following syntax specification uses the augmented Backus-Naur 354 Form (BNF) as described in ABNF [RFC5234]. It includes definitions 355 from IMAP [RFC3501]. 357 capability =/ "PREVIEW=" (preview-alg / preview-mod-ext) 359 fetch-att =/ "PREVIEW" [SP "(" preview-alg-fetch *(SP 360 preview-alg-fetch) ")"] 362 msg-att-dynamic =/ "PREVIEW" SP "(" preview-alg SP nstring ")" 364 preview-alg = "FUZZY" / preview-alg-ext 366 preview-alg-ext = preview-atom ; New algorithm names SHOULD be 367 ; registered with IANA and MUST 368 ; conform with the 369 ; recommendations described in 370 ; RFC 6648, Section 3 372 preview-alg-fetch = preview-alg / preview-mod "=" preview-alg 374 preview-atom = 1*. 423 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 424 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 425 . 427 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 428 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 429 2003, . 431 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 432 Specifications: ABNF", STD 68, RFC 5234, 433 DOI 10.17487/RFC5234, January 2008, 434 . 436 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet 437 Message Access Protocol Internationalization", RFC 5255, 438 DOI 10.17487/RFC5255, June 2008, 439 . 441 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 442 "Deprecating the "X-" Prefix and Similar Constructs in 443 Application Protocols", BCP 178, RFC 6648, 444 DOI 10.17487/RFC6648, June 2012, 445 . 447 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 448 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 449 May 2017, . 451 10.2. Informative References 453 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 454 Extensions (MIME) Part One: Format of Internet Message 455 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 456 . 458 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media 459 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000, 460 . 462 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 463 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March 464 2008, . 466 Appendix A. Change History (To be removed by RFC Editor before 467 publication) 469 Changes from draft-slusarz-imap-fetch-snippet-00: 471 o Added standardized language to Section 2 regarding IMAP ABNF 472 conventions 474 o Changed draft name to draft-ietf-extra-imap-fetch-snippet-## 476 Changes from draft-ietf-extra-imap-fetch-snippet-00: 478 o Changed nomenclature from "snippet" to "preview" 480 o Changed draft name to draft-ietf-extra-imap-fetch-preview-## 482 o Update to RFC 8174 boilerplate 484 o Updated length requirements for PREVIEW=FUZZY 486 o Added preview-atom ABNF to limit use of "=" character 488 o UTF-8 is a normative reference 490 o Clarify that characters for purpose of length limitations are 491 defined as UCS characters as encoded by UTF-8 493 o Fix some incorrect literal lengths in examples 495 Changes from draft-ietf-extra-imap-fetch-preview-00: 497 o Updated postal address 498 o Added example to FETCH response section 500 o Added example on how LANGUAGE extension may influence preview 501 generation 503 o Added recommendation that only one LAZY FETCH be executed for a 504 message per mailbox 506 o Added request to create algorithm and modifier registries 508 o Added requirement that algorithm and modifier names conform to RFC 509 6648 511 o Added DoS attack info to security considerations 513 o Distinguish between NIL response and zero-length string 515 o Don't use deprecated "X-" convention in example 517 o Spelling and nits 519 Changes from draft-ietf-extra-imap-fetch-preview-01: 521 o Fix capability ABNF 523 o Removed CAPABILITY string for examples where it did not add 524 valuable context 526 o Altered preview data in examples to cover a variety of potential 527 server return scenarios 529 o Added "SHOULD be registered" language to algorithm names and 530 priority modifiers 532 Changes from draft-ietf-extra-imap-fetch-preview-02: 534 o Move Acknowledgments to un-numbered appendix 536 o Improved abstract text 538 o Consistently use "priority modifiers" instead of "modifiers" 540 o Update example to conform with RFC 3501 UID FETCH requirements 542 Acknowledgments 544 The author would like to thank the following people for their 545 comments and contributions to this document: Stephan Bosch, Bron 546 Gondwana, Teemu Huovila, Steffen Lehmann, Alexey Melnikov, Chris 547 Newman, Jeff Sipek, Timo Sirainen, Steffen Templin, and Aki Tuomi. 549 Author's Address 551 Michael M. Slusarz 552 Open-Xchange Inc. 553 530 Lytton Avenue 554 Palo Alto, California 94301 555 US 557 Email: michael.slusarz@open-xchange.com