idnits 2.17.1 draft-ietf-extra-imap-fetch-preview-01.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 (January 22, 2019) is 1914 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 456, 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 January 22, 2019 5 Expires: July 26, 2019 7 IMAP4 Extension: Message Preview Generation 8 draft-ietf-extra-imap-fetch-preview-01 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 July 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9 62 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 63 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 10. Security Considerations . . . . . . . . . . . . . . . . . . . 11 65 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 67 11.2. Informative References . . . . . . . . . . . . . . . . . 12 68 Appendix A. Change History (To be removed by RFC Editor before 69 publication) . . . . . . . . . . . . . . . . . . . . 12 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 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 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 20000 PREVIEW (FUZZY {58} 286 S: This is the first line of text from the first text part. 287 S: )) 288 S: A2 OK FETCH complete. 290 Example 2: Requesting FETCH with explicit algorithm selection. 292 C: B1 CAPABILITY 293 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 294 S: B1 OK Capability command completed. 295 [...a mailbox is SELECTed...] 296 C: B2 FETCH 1 (RFC822.SIZE PREVIEW (FUZZY)) 297 S: * 1 FETCH (RFC822.SIZE 20000 PREVIEW (FUZZY {58} 298 S: This is the first line of text from the first text part. 299 S: )) 300 S: B2 OK FETCH complete. 302 Example 3: Requesting FETCH with invalid explicit algorithm 303 selection. 305 C: C1 CAPABILITY 306 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 307 S: C1 OK Capability command completed. 308 [...a mailbox is SELECTed...] 309 C: C2 FETCH 1 (RFC822.SIZE PREVIEW (UNKNOWN-PREVIEW-ALGO)) 310 S: C2 BAD FETCH contains invalid preview algorithm name. 312 Example 4: Use explicit algorithm priority selection, with LAZY 313 modifier, to obtain previews during initial mailbox listing if 314 readily available; otherwise, load previews in background. 316 C: D1 CAPABILITY 317 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY 318 S: D1 OK Capability command completed. 319 [...a mailbox is SELECTed...] 320 C: D2 FETCH 1:3 (ENVELOPE PREVIEW (LAZY=FUZZY)) 321 S: * 1 FETCH (ENVELOPE ("Wed, 25 Oct 2017 15:03:11 +0000" [...]) 322 PREVIEW (FUZZY {58} 323 S: This is the first line of text from the first text part. 324 S: )) 325 S: * 2 FETCH (PREVIEW (FUZZY "") ENVELOPE 326 ("Thu, 26 Oct 2017 12:17:23 +0000" [...])) 327 S: * 3 FETCH (ENVELOPE ("Fri, 27 Oct 2017 22:19:21 +0000" [...]) 328 PREVIEW (FUZZY NIL)) 329 S: D2 OK FETCH completed. 330 [...Client knows that message 2 has a preview that is empty; 331 therefore, client only needs to request message 3 preview again 332 (e.g. in background)...] 333 C: D3 FETCH 3 (PREVIEW (FUZZY)) 334 S: * 3 FETCH (PREVIEW (FUZZY {27} 335 S: First sentence of mail 3. 336 S: )) 337 S: D3 OK Fetch completed. 339 Example 5: Retrieve preview information for search results within a 340 single mailbox. Use SEARCHRES [RFC5182] extension to save a round- 341 trip. 343 C: E1 CAPABILITY 344 S: * CAPABILITY IMAP4rev1 PREVIEW=FUZZY SEARCHRES 345 S: E1 OK Capability command completed. 346 [...a mailbox is SELECTed...] 347 C: E2 SEARCH RETURN (SAVE) FROM "FOO" 348 C: E3 FETCH $ (UID PREVIEW (LAZY=FUZZY)) 349 S: E2 OK SEARCH completed. 350 S: * 5 FETCH (UID 13 PREVIEW (FUZZY {10} 351 S: Preview! 352 S: )) 353 S: * 9 FETCH (UID 23 PREVIEW (FUZZY NIL)) 354 S: E3 OK FETCH completed. 355 [...Retrieve message 9 preview in background...] 356 C: E4 UID FETCH 23 (PREVIEW (FUZZY)) 357 S: * 9 FETCH (PREVIEW (FUZZY {18} 358 S: Another preview! 359 S: )) 360 S: E4 OK FETCH completed. 362 7. Formal Syntax 364 The following syntax specification uses the augmented Backus-Naur 365 Form (BNF) as described in ABNF [RFC5234]. It includes definitions 366 from IMAP [RFC3501]. 368 capability =/ "PREVIEW=FUZZY" 370 fetch-att =/ "PREVIEW" [SP "(" preview-alg-fetch *(SP 371 preview-alg-fetch) ")"] 373 msg-att-dynamic =/ "PREVIEW" SP "(" preview-alg SP nstring ")" 375 preview-alg = "FUZZY" / preview-alg-ext 377 preview-alg-ext = preview-atom ; New algorithm names MUST 378 ; conform with the 379 ; recommendations described in 380 ; RFC 6648, Section 3 382 preview-alg-fetch = preview-alg / preview-mod "=" preview-alg 384 preview-atom = 1*. 438 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 439 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 440 . 442 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 443 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 444 2003, . 446 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 447 Specifications: ABNF", STD 68, RFC 5234, 448 DOI 10.17487/RFC5234, January 2008, 449 . 451 [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet 452 Message Access Protocol Internationalization", RFC 5255, 453 DOI 10.17487/RFC5255, June 2008, 454 . 456 [RFC6648] Saint-Andre, P., Crocker, D., and M. Nottingham, 457 "Deprecating the "X-" Prefix and Similar Constructs in 458 Application Protocols", BCP 178, RFC 6648, 459 DOI 10.17487/RFC6648, June 2012, 460 . 462 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 463 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 464 May 2017, . 466 11.2. Informative References 468 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 469 Extensions (MIME) Part One: Format of Internet Message 470 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 471 . 473 [RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media 474 Type", RFC 2854, DOI 10.17487/RFC2854, June 2000, 475 . 477 [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last 478 SEARCH Result", RFC 5182, DOI 10.17487/RFC5182, March 479 2008, . 481 Appendix A. Change History (To be removed by RFC Editor before 482 publication) 484 Changes from draft-slusarz-imap-fetch-snippet-00: 486 o Added standardized language to Section 2 regarding IMAP ABNF 487 conventions 489 o Changed draft name to draft-ietf-extra-imap-fetch-snippet-## 491 Changes from draft-ietf-extra-imap-fetch-snippet-00: 493 o Changed nomenclature from "snippet" to "preview" 495 o Changed draft name to draft-ietf-extra-imap-fetch-preview-## 497 o Update to RFC 8174 boilerplate 499 o Updated length requirements for PREVIEW=FUZZY 501 o Added preview-atom ABNF to limit use of "=" character 503 o UTF-8 is a normative reference 505 o Clarify that characters for purpose of length limitations are 506 defined as UCS characters as encoded by UTF-8 508 o Fix some incorrect literal lengths in examples 509 Changes from draft-ietf-extra-imap-fetch-preview-00: 511 o Updated postal address 513 o Added example to FETCH response section 515 o Added example on how LANGUAGE extension may influence preview 516 generation 518 o Added recommendation that only one LAZY FETCH be executed for a 519 message per mailbox 521 o Added request to create algorithm and modifier registries 523 o Added requirement that algorithm and modifier names conform to RFC 524 6648 526 o Added DoS attack info to security considerations 528 o Distinguish between NIL response and zero-length string 530 o Don't use deprecated "X-" convention in example 532 o Spelling and nits 534 Author's Address 536 Michael M. Slusarz 537 Open-Xchange Inc. 538 530 Lytton Avenue 539 Palo Alto, California 94301 540 US 542 Email: michael.slusarz@open-xchange.com