idnits 2.17.1 draft-ietf-extra-imap-fetch-preview-04.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 (April 24, 2019) is 1829 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 April 24, 2019 5 Expires: October 26, 2019 7 IMAP4 Extension: Message Preview Generation 8 draft-ietf-extra-imap-fetch-preview-04 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 October 26, 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 8 62 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 63 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 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. 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 list is provided, the server decides which of its 152 built-in algorithms to use to generate the preview text. 154 The client may explicitly indicate which algorithm(s) should be used 155 to generate the preview list via a parenthesized list of algorithm 156 names output after the PREVIEW attribute. Unsupported algorithms in 157 the list MUST be ignored. If the list contains no supported 158 algorithms, the server MUST return a tagged BAD response to the FETCH 159 command. 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 A server should return preview data for the first algorithm that 168 returns non-empty preview text. Non-empty preview text is defined as 169 either the NIL response or an empty string. If no algorithm produces 170 non-empty preview text, the server should respond with the preview 171 data generated by the final algorithm in the list. 173 3.2. Response 175 The algorithm used by the server to generate the preview is returned 176 preceding the preview string. 178 The server returns a variable-length string that is the generated 179 preview for that message. 181 Example: Retrieving preview information in a SELECTed mailbox 183 C: A1 FETCH 1 (PREVIEW) 184 S: * 1 FETCH (PREVIEW (FUZZY "Preview text!")) 185 S: A1 OK FETCH complete. 187 A server SHOULD strive to generate the same string for a given 188 message for each request. However, since previews are understood to 189 be a representation of the message data and not a canonical view of 190 its contents, a client MUST NOT assume that a message preview is 191 immutable for a given message. This relaxed requirement permits a 192 server to offer previews as an option without requiring potentially 193 burdensome storage and/or processing requirements to guarantee 194 immutability for a use case that does not require this strictness. 196 If the preview is not available, the server MUST return NIL as the 197 PREVIEW response. A NIL response indicates to the client that 198 preview information MAY become available in a future PREVIEW FETCH 199 request. 201 Examples why a preview may not be available include: the preview 202 generation process is not available due to transient server resource 203 limitations, the message body text is unavailable, or a server- 204 imposed timeout was reached during generation. 206 A NIL response is semantically different than returning a zero-length 207 string, which indicates that no meaningful preview text can be 208 generated for the message. 210 4. PREVIEW Algorithms 212 4.1. FUZZY 214 The FUZZY algorithm directs the server to use any internal algorithm 215 it desires, subject to the below limitations, to generate a textual 216 preview for a message. 218 The FUZZY algorithm MUST be implemented by any server that supports 219 the PREVIEW extension. 221 The preview text MUST be treated as text/plain [RFC2046] MIME data by 222 the client. 224 The generated string MUST NOT be content transfer encoded and MUST be 225 encoded in UTF-8 [RFC3629]. The server SHOULD remove any formatting 226 markup and do what other processing might be useful in rendering the 227 preview as plain text. 229 For purposes of this section, a "preview character" is defined as a 230 single UCS character encoded in UTF-8. Note: a single preview 231 character may compromise multiple octets, so any buffers implemented 232 to conform to the string limitations identified in this document 233 should be sized to prevent possible overflow errors. 235 The server SHOULD limit the length of the preview text to 200 preview 236 characters. This length should provide sufficient data to generally 237 support both various languages (and their different average word 238 lengths) and different client display size requirements. 240 The server MUST NOT output preview text longer than 256 preview 241 characters. 243 If the FUZZY algorithm generates a preview that is not based on the 244 body content of the message and the LANGUAGE [RFC5255] extension is 245 supported by the server, the preview text SHOULD be generated 246 according to the language rules that apply to human-readable text. 247 For example, a message that consists of a single image MIME part has 248 no human-readable text from which to generate preview information. 249 Instead, the server may wish to output a description that the message 250 contains an image and describe some attributes of the image, such as 251 image format, size, and filename. This descriptive text is not a 252 product of the message body itself but is rather auto-generated data 253 by the server, and should thus use the rules defined for human- 254 generated text described in the LANGUAGE extension (if supported on 255 the server). 257 5. PREVIEW Priority Modifiers 259 5.1. LAZY 261 The LAZY modifier directs the server to return the preview 262 representation only if that data can be returned without undue delay 263 to the client. 265 This modifier allows a client to inform the server that preview data 266 is nice-to-have, but the server SHOULD NOT block the return of other 267 FETCH information at the expense of generating the preview data. 269 For example, a client displaying the initial mailbox listing to a 270 user may want to display preview information associated with messages 271 in that listing. However, this information is secondary to providing 272 the mailbox listing, with message details, and the client is willing 273 to load any unavailable previews in the background and display them 274 as they are provided by the server. In this case, the client would 275 apply the LAZY modifier to the desired algorithm(s) to direct the 276 server to only return pre-generated preview data so that retrieval of 277 the other FETCH information is not blocked by possibly expensive 278 preview generation. 280 Generally, the LAZY modifier will only be used once per mailbox load 281 during the initial listing. If preview information is not available 282 during this initial FETCH, the expectation is that a second non-LAZY 283 FETCH will take place after mailbox listing activities are complete. 284 Thus, a maximum of 2 PREVIEW FETCH queries should occur for any 285 message in a selected mailbox. A client SHOULD NOT continually issue 286 LAZY PREVIEW FETCH commands in a selected mailbox as the server is 287 under no requirement to return preview information for this command, 288 which could lead to an unnecessary waste of system and network 289 resources. See Example 4 in the Examples section for how this can be 290 implemented. 292 The LAZY modifier MUST be implemented by any server that supports the 293 PREVIEW extension. 295 6. Examples 297 Example 1: Requesting FETCH without explicit algorithm selection. 299 C: A1 CAPABILITY 300 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 301 S: A1 OK Capability command completed. 302 [...a mailbox is SELECTed...] 303 C: A2 FETCH 1 (RFC822.SIZE PREVIEW) 304 S: * 1 FETCH (RFC822.SIZE 5647 PREVIEW (FUZZY {200} 305 S: Lorem ipsum dolor sit amet, consectetur adipiscing elit. 306 S: Curabitur aliquam turpis et ante dictum, et pulvinar dui congue. 307 S: Maecenas hendrerit, lorem non imperdiet pellentesque, nulla 308 S: ligula nullam 309 S: )) 310 S: A2 OK FETCH complete. 312 Example 2: Requesting FETCH with explicit algorithm selection. 314 C: B1 FETCH 1 (RFC822.SIZE PREVIEW (FUZZY)) 315 S: * 1 FETCH (RFC822.SIZE 91377 PREVIEW (FUZZY {53} 316 S: Preview text generated from message body text data. 317 S: )) 318 S: B1 OK FETCH complete. 320 Example 3: Requesting FETCH with invalid explicit algorithm 321 selection. 323 C: C1 CAPABILITY 324 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 325 S: C1 OK Capability command completed. 326 [...a mailbox is SELECTed...] 327 C: C2 FETCH 1 (RFC822.SIZE PREVIEW (UNKNOWN-PREVIEW-ALGO)) 328 S: C2 BAD FETCH contains invalid preview algorithm name. 330 Example 4: Use explicit algorithm priority selection, with LAZY 331 modifier, to obtain previews during initial mailbox listing if 332 readily available; otherwise, load previews in background. 334 C: D1 FETCH 1:3 (ENVELOPE PREVIEW (LAZY=FUZZY)) 335 S: * 1 FETCH (ENVELOPE ("Wed, 25 Oct 2017 15:03:11 +0000" [...]) 336 PREVIEW (FUZZY "Preview text for message 1.")) 337 S: * 2 FETCH (PREVIEW (FUZZY "") ENVELOPE 338 ("Thu, 26 Oct 2017 12:17:23 +0000" [...])) 339 S: * 3 FETCH (ENVELOPE ("Fri, 27 Oct 2017 22:19:21 +0000" [...]) 340 PREVIEW (FUZZY NIL)) 341 S: D1 OK FETCH completed. 342 [...Client knows that message 2 has a preview that is empty; 343 therefore, client only needs to request message 3 preview again 344 (e.g. in background)...] 345 C: D2 FETCH 3 (PREVIEW (FUZZY)) 346 S: * 3 FETCH (PREVIEW (FUZZY {30} 347 S: Message data from message 3. 348 S: )) 349 S: D2 OK Fetch completed. 351 Example 5: Retrieve preview information for search results within a 352 single mailbox. Use SEARCHRES [RFC5182] extension to save a round- 353 trip. 355 C: E1 CAPABILITY 356 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY SEARCHRES 357 S: E1 OK Capability command completed. 358 [...a mailbox is SELECTed...] 359 C: E2 SEARCH RETURN (SAVE) FROM "FOO" 360 C: E3 FETCH $ (UID PREVIEW (LAZY=FUZZY)) 361 S: E2 OK SEARCH completed. 362 S: * 5 FETCH (UID 13 PREVIEW (FUZZY "Preview!")) 363 S: * 9 FETCH (UID 23 PREVIEW (FUZZY NIL)) 364 S: E3 OK FETCH completed. 365 [...Retrieve message 9 preview in background...] 366 C: E4 UID FETCH 23 (PREVIEW (FUZZY)) 367 S: * 9 FETCH (UID 23 PREVIEW (FUZZY "Another preview!")) 368 S: E4 OK FETCH completed. 370 7. Formal Syntax 372 The following syntax specification uses the augmented Backus-Naur 373 Form (BNF) as described in ABNF [RFC5234]. It includes definitions 374 from IMAP [RFC3501]. 376 capability =/ "PREVIEW=" preview-alg 378 fetch-att =/ "PREVIEW" [SP "(" preview-alg-fetch *(SP 379 preview-alg-fetch) ")"] 381 msg-att-dynamic =/ "PREVIEW" SP "(" preview-alg SP nstring ")" 383 preview-alg = "FUZZY" / preview-alg-ext 385 preview-alg-ext = preview-atom ; New algorithm names SHOULD be 386 ; registered with IANA and MUST 387 ; conform with the 388 ; recommendations described in 389 ; [RFC6648], Section 3 391 preview-alg-fetch = preview-alg / preview-mod "=" preview-alg 393 preview-atom = 1*. 440 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 441 Requirement Levels", BCP 14, RFC 2119, 442 DOI 10.17487/RFC2119, March 1997, 443 . 445 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 446 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 447 . 449 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 450 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 451 2003, . 453 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 454 Specifications: ABNF", STD 68, RFC 5234, 455 DOI 10.17487/RFC5234, January 2008, 456 . 458 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet 459 Message Access Protocol Internationalization", RFC 5255, 460 DOI 10.17487/RFC5255, June 2008, 461 . 463 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 464 "Deprecating the "X-" Prefix and Similar Constructs in 465 Application Protocols", BCP 178, RFC 6648, 466 DOI 10.17487/RFC6648, June 2012, 467 . 469 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 470 Writing an IANA Considerations Section in RFCs", BCP 26, 471 RFC 8126, DOI 10.17487/RFC8126, June 2017, 472 . 474 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 475 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 476 May 2017, . 478 10.2. Informative References 480 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 481 Extensions (MIME) Part One: Format of Internet Message 482 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 483 . 485 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media 486 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000, 487 . 489 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 490 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March 491 2008, . 493 Appendix A. Change History (To be removed by RFC Editor before 494 publication) 496 Changes from draft-slusarz-imap-fetch-snippet-00: 498 o Added standardized language to Section 2 regarding IMAP ABNF 499 conventions 501 o Changed draft name to draft-ietf-extra-imap-fetch-snippet-## 503 Changes from draft-ietf-extra-imap-fetch-snippet-00: 505 o Changed nomenclature from "snippet" to "preview" 507 o Changed draft name to draft-ietf-extra-imap-fetch-preview-## 509 o Update to RFC 8174 boilerplate 511 o Updated length requirements for PREVIEW=FUZZY 513 o Added preview-atom ABNF to limit use of "=" character 515 o UTF-8 is a normative reference 516 o Clarify that characters for purpose of length limitations are 517 defined as UCS characters as encoded by UTF-8 519 o Fix some incorrect literal lengths in examples 521 Changes from draft-ietf-extra-imap-fetch-preview-00: 523 o Updated postal address 525 o Added example to FETCH response section 527 o Added example on how LANGUAGE extension may influence preview 528 generation 530 o Added recommendation that only one LAZY FETCH be executed for a 531 message per mailbox 533 o Added request to create algorithm and modifier registries 535 o Added requirement that algorithm and modifier names conform to RFC 536 6648 538 o Added DoS attack info to security considerations 540 o Distinguish between NIL response and zero-length string 542 o Don't use deprecated "X-" convention in example 544 o Spelling and nits 546 Changes from draft-ietf-extra-imap-fetch-preview-01: 548 o Fix capability ABNF 550 o Removed CAPABILITY string for examples where it did not add 551 valuable context 553 o Altered preview data in examples to cover a variety of potential 554 server return scenarios 556 o Added "SHOULD be registered" language to algorithm names and 557 priority modifiers 559 Changes from draft-ietf-extra-imap-fetch-preview-02: 561 o Move Acknowledgments to un-numbered appendix 563 o Improved abstract text 564 o Consistently use "priority modifiers" instead of "modifiers" 566 o Update example to conform with RFC 3501 UID FETCH requirements 568 Changes from draft-ietf-extra-imap-fetch-preview-03: 570 o Remove preview modifier registry request 572 o Improve instructions for registration of algorithms 574 o Add storage information to security considerations 576 o Clarify parsing of algorithm list in FETCH command 578 o Clarify difference between NIL response and zero-length string 580 o Add normative reference for text/plain 582 o Add warning regarding buffers and multiple octet preview 583 characters 585 o Clarify how to handle preview data return when using an explicit 586 algorithm list 588 o Various editorial fixes 590 Acknowledgments 592 The author would like to thank the following people for their 593 comments and contributions to this document: Stephan Bosch, Bron 594 Gondwana, Teemu Huovila, Steffen Lehmann, Alexey Melnikov, Chris 595 Newman, Jeff Sipek, Timo Sirainen, Steffen Templin, and Aki Tuomi. 597 Author's Address 599 Michael M. Slusarz 600 Open-Xchange Inc. 601 530 Lytton Avenue 602 Palo Alto, California 94301 603 US 605 Email: michael.slusarz@open-xchange.com