idnits 2.17.00 (12 Aug 2021) /tmp/idnits18727/draft-melnikov-imap-partial-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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 7 characters in excess of 72. -- The draft header indicates that this document updates RFC4731, but the abstract doesn't seem to directly say this. It does mention RFC4731 though, so this could be OK. -- The draft header indicates that this document updates RFC5267, but the abstract doesn't seem to directly say this. It does mention RFC5267 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC4731, updated by this document, for RFC5378 checks: 2005-02-11) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (22 October 2021) is 210 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: 2 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Melnikov 3 Internet-Draft Isode 4 Updates: 5267, 4731 (if approved) A. P. Achuthan 5 Intended status: Standards Track V. Nagulakonda 6 Expires: 25 April 2022 Yahoo! 7 L. Alves 8 Verizon 9 22 October 2021 11 IMAP Paged SEARCH & FETCH Extension 12 draft-melnikov-imap-partial-00 14 Abstract 16 The PARTIAL extension of the Internet Message Access Protocol (RFC 17 3501/RFC 9051) allows clients to limit the number of search results 18 returned, as well as to perform incremental (paged) searches. This 19 also helps servers to optimize resource usage when performing 20 searches. 22 This document extends PARTIAL SEARCH return option originally 23 specified in RFC 5267. It also clarifies some interactions between 24 RFC 5267 and RFC 4731/RFC 9051. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on 25 April 2022. 43 Copyright Notice 45 Copyright (c) 2021 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 50 license-info) in effect on the date of publication of this document. 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. Code Components 53 extracted from this document must include Simplified BSD License text 54 as described in Section 4.e of the Trust Legal Provisions and are 55 provided without warranty as described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 72 2. Document Conventions . . . . . . . . . . . . . . . . . . . . 3 73 3. Incremental SEARCH and partial results . . . . . . . . . . . 3 74 4. Interaction between PARTIAL, MIN, MAX and SAVE SEARCH return 75 options . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 5. Extension to FETCH . . . . . . . . . . . . . . . . . . . . . 6 77 6. Expressing limits on a number of messages used in 78 SEARCH/FETCH/STORE/COPY/MOVE . . . . . . . . . . . . . . 6 79 7. Formal syntax . . . . . . . . . . . . . . . . . . . . . . . . 7 80 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 81 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 82 9.1. Changes/additions to the IMAP4 capabilities registry . . 8 83 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 84 11. Normative References . . . . . . . . . . . . . . . . . . . . 9 85 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 88 1. Introduction and Overview 90 This document defines an extension to the Internet Message Access 91 Protocol [RFC3501] for performing incremental searches and fetches. 92 This extension is compatible with both IMAP4rev1 [RFC3501] and 93 IMAP4rev2 [RFC9051]. 95 The PARTIAL extension of the Internet Message Access Protocol (RFC 96 3501/RFC 9051) allows clients to limit the number of search results 97 returned, as well as to perform incremental (paged) searches. This 98 also helps servers to optimize resource usage when performing 99 searches. 101 This document extends PARTIAL SEARCH return option originally 102 specified in RFC 5267. 104 2. Document Conventions 106 In protocol examples, this document uses a prefix of "C: " to denote 107 lines sent by the client to the server, and "S: " for lines sent by 108 the server to the client. Lines prefixed with "// " are comments 109 explaining the previous protocol line. These prefixes and comments 110 are not part of the protocol. Lines without any of these prefixes 111 are continuations of the previous line, and no line break is present 112 in the protocol unless specifically mentioned. 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in BCP 117 14 [RFC2119] [RFC8174] when, and only when, they appear in all 118 capitals, as shown here. 120 Other capitalised words are IMAP keywords [RFC3501][RFC9051] or 121 keywords from this document. 123 3. Incremental SEARCH and partial results 125 The PARTIAL search return option causes the server to provide in an 126 ESEARCH response a subset of the results denoted by the sequence 127 range given as the mandatory argument. The first result (message 128 with the lowest matching UID) is 1; thus, the first 500 results would 129 be obtained by a return option of "PARTIAL 1:500", and the second 500 130 by "PARTIAL 501:1000". This intentionally mirrors message sequence 131 numbers. 133 It is also possible to direct the server to start SEARCH from the 134 latest matching (with the highest UID) message. This can be done by 135 prepeding "-" to the index. For example -1 is the last message, -2 136 is next to the last and so on. Using this syntax helps server 137 implementations to optimize their SEARCHes. 139 A single command MUST NOT contain more than one PARTIAL or ALL search 140 return option -- that is, either one PARTIAL, one ALL, or neither 141 PARTIAL nor ALL is allowed. 143 For SEARCH results, the entire result list MUST be ordered in mailbox 144 order, that is, in UID or message sequence number order. 146 Where a PARTIAL search return option references results that do not 147 exist, by using a range which starts or ends higher (or lower) than 148 the current number of results, then the server returns the results 149 that are in the set. This yields a PARTIAL return data item that 150 has, as payload, the original range and a potentially missing set of 151 results that may be shorter than the extent of the range. If the 152 whole range references results that do not exist, a special value 153 "NIL" is returned by the server instead of the sequence set. 155 Clients need not request PARTIAL results in any particular order. 156 Because mailboxes may change, clients might wish to use PARTIAL in 157 combination with UPDATE (see [RFC5267] if the server also advertises 158 CONTEXT=SEARCH capability, especially if the intent is to walk a 159 large set of results; however, these return options do not interact 160 -- the UPDATE will provide notifications for all matching results. 162 // Let's assume that the A01 SEARCH without PARTIAL would return 163 // 23764 results. 164 C: A01 UID SEARCH RETURN (PARTIAL -1:-100) UNDELETED 165 UNKEYWORD $Junk 166 S: * ESEARCH (TAG "A01") UID PARTIAL (-1:-100 ...) 167 // 100 most recent results in set syntax elided. 168 S: A01 OK Completed. 170 // Let's assume that the A02 SEARCH without PARTIAL would return 171 // 23764 results. 172 C: A02 UID SEARCH RETURN (PARTIAL 23500:24000) UNDELETED 173 UNKEYWORD $Junk 174 C: A03 UID SEARCH RETURN (PARTIAL 1:500) UNDELETED 175 UNKEYWORD $Junk 176 C: A04 UID SEARCH RETURN (PARTIAL 24000:24500) UNDELETED 177 UNKEYWORD $Junk 178 S: * ESEARCH (TAG "A02") UID PARTIAL (23500:24000 ...) 179 // 264 results in set syntax elided, 180 // this spans the end of the results. 181 S: A02 OK Completed. 182 S: * ESEARCH (TAG "A03") UID PARTIAL (1:500 ...) 183 // 500 results in set syntax elided. 184 S: A03 OK Completed. 185 S: * ESEARCH (TAG "A04") UID PARTIAL (24000:24500 NIL) 186 // No results are present, this is beyond the end of the results. 187 S: A04 OK Completed. 189 4. Interaction between PARTIAL, MIN, MAX and SAVE SEARCH return options 191 This section only applies if the server advertises PARTIAL IMAP 192 capability or CONTEXT=SEARCH [RFC5267], together with ESEARCH 193 [RFC4731] and/or IMAP4rev2"[RFC9051]. 195 The SAVE result option doesn't change whether the server would return 196 items corresponding to PARTIAL SEARCH result options. 198 As specified in Section 3, it is an error to specify both PARTIAL and 199 ALL result options in the same SEARCH command. 201 When the SAVE result option is combined with the PARTIAL result 202 option, and none of MIN/MAX/COUNT result options is present, the 203 corresponding PARTIAL is returned, and the "$" marker would contain 204 all messages returned by the PARTIAL result option. 206 When the SAVE + PARTIAL result options are combined with the MIN or 207 the MAX result option, and the COUNT result option is absent, the 208 corresponding PARTIAL result and MIN/MAX is returned (if the search 209 result is not empty), and the "$" marker would contain all messages 210 returned by the PARTIAL result option + the corresponding MIN/MAX 211 message. 213 If the SAVE + PARTIAL result options are combined with both MIN and 214 MAX result options, and the COUNT result options is absent, the 215 PARTIAL, MIN and MAX are returned (if the search result is not 216 empty), and the "$" marker would contain all messages returned by the 217 PARTIAL result option plus MIN and MAX messages. 219 If the SAVE + PARTIAL result options are combined with the COUNT 220 result option, the PARTIAL and COUNT are returned, and the "$" marker 221 would always contain all messages found by the SEARCH or UID SEARCH 222 command. 224 The following table summarizes the additional requirement on ESEARCH 225 server implementations described in this section. 227 +==============================+=====================+ 228 | Combination of Result option | "$" marker value | 229 +==============================+=====================+ 230 | SAVE PARTIAL | PARTIAL | 231 +------------------------------+---------------------+ 232 | SAVE PARTIAL MIN | PARTIAL & MIN | 233 +------------------------------+---------------------+ 234 | SAVE PARTIAL MAX | PARTIAL & MAX | 235 +------------------------------+---------------------+ 236 | SAVE PARTIAL MIN MAX | PARTIAL & MIN & MAX | 237 +------------------------------+---------------------+ 238 | SAVE PARTIAL COUNT [m] | all found messages | 239 +------------------------------+---------------------+ 241 Table 1 243 where '[m]' means optional "MIN" and/or "MAX" 245 5. Extension to FETCH 247 The PARTIAL extension also extends the FETCH command with a PARTIAL 248 FETCH modifier. The PARTIAL FETCH modifier has the same syntax as 249 the PARTIAL SEARCH result option. Presence of the PARTIAL FETCH 250 modifier instructs the server to only return FETCH results for 251 messages in the specified range. It is useful when the sequence-set 252 (first) parameter to FETCH/UID FETCH command includes unknown number 253 of messages. 255 // Returning information for the last 3 messages in the UID range 256 C: 10 UID FETCH 25900:26600 (UID FLAGS) (PARTIAL -1:-3) 257 S: * 12888 FETCH (FLAGS (\Seen) UID 25996) 258 S: * 12889 FETCH (FLAGS (\Flagged \Answered) UID 25997) 259 S: * 12890 FETCH (FLAGS () UID 26600) 260 S: 10 OK FETCH completed 262 // Returning information for the first 5 messages in the UID range 263 C: 11 UID FETCH 25900:26600 (UID FLAGS) (PARTIAL 1:5) 264 S: * 12591 FETCH (FLAGS (\Seen) UID 25900) 265 S: * 12592 FETCH (FLAGS (\Flagged) UID 25902) 266 S: * 12593 FETCH (FLAGS (\Answered) UID 26310) 267 S: * 12594 FETCH (FLAGS () UID 26311) 268 S: * 12595 FETCH (FLAGS (\Answered) UID 26498) 269 S: 11 OK FETCH completed 271 6. Expressing limits on a number of messages used in 272 SEARCH/FETCH/STORE/COPY/MOVE 274 // Should this be a separate IMAP capability? 275 // Also, should this also affect SEARCH? If yes, do we need a way to 276 // specify SEARCH criterion for "all UIDs after" or "all UIDs before" 277 // a specific UID? 279 If a server implementation doesn't allow more than messages to be 280 operated on by a single FETCH/STORE/COPY/MOVE command, it MUST return 281 the MESSAGELIMIT response code defined below: 283 MESSAGELIMIT The server doesn't allow more than messages to be operated 284 on by a single SEARCH/FETCH/STORE/COPY/MOVE command. The last 285 processed UID is . The client needs to repeat the 286 operation for remaining messages. 288 C: 03 FETCH 10000:14589 (UID FLAGS) 289 S: * 14589 FETCH (FLAGS (\Seen) UID 25000) 290 S: * 14588 FETCH (FLAGS (\Answered) UID 24998) 291 S: ... further 997 fetch responses 292 S: * 13590 FETCH (FLAGS () UID 23221) 293 S: 03 OK [MESSAGELIMIT 1000 23221] FETCH completed with 1000 partial 294 results 296 In the above example the value is 1000 and the last 297 processed UID is 23221. 299 7. Formal syntax 301 The following syntax specification uses the Augmented Backus-Naur 302 Form (ABNF) notation as specified in [ABNF]. 304 Non-terminals referenced but not defined below are as defined by 305 IMAP4 [RFC3501]. 307 Except as noted otherwise, all alphabetic characters are case- 308 insensitive. The use of upper or lower case characters to define 309 token strings is for editorial clarity only. Implementations MUST 310 accept these strings in a case-insensitive fashion. 312 SP = 313 MINUS = "-" 315 capability =/ "PARTIAL" 316 ;; from [RFC3501] 318 modifier-partial = "PARTIAL" SP partial-range 320 partial-range-first = nz-number ":" nz-number 321 ;; Request to search from oldest (lowest UIDs) to 322 ;; more recent messages. 323 ;; A range 500:400 is the same as 400:500. 324 ;; This is similar to from [RFC3501], 325 ;; but cannot contain "*". 327 partial-range-last = MINUS nz-number ":" MINUS nz-number 328 ;; Request to search from newest (highest UIDs) to 329 ;; oldest messages. 331 ;; A range -500:-400 is the same as -400:-500. 333 partial-range = partial-range-first / partial-range-last 335 search-return-opt =/ modifier-partial 336 ;; All conform to , from [IMAP-ABNF]/[RFC9051] 338 search-return-data =/ ret-data-partial 340 ret-data-partial = "PARTIAL" 341 SP "(" partial-range SP partial-results ")" 342 ;; is the requested range. 344 partial-results = sequence-set / "NIL" 345 ;; from [RFC3501]. 346 ;; NIL indicates no results correspond to the requested range. 348 tagged-ext-simple =/ partial-range-last 350 fetch-modifier =/ modifier-partial 352 resp-text-code =/ "MESSAGELIMIT" SP nz-number SP uniqueid 353 ;; No more than nz-number messages can be processed 354 ;; by any command at a time. The last processed 355 ;; UID is uniqueid. 357 8. Security Considerations 359 TBD. 361 9. IANA Considerations 363 9.1. Changes/additions to the IMAP4 capabilities registry 365 IMAP4 capabilities are registered by publishing a standards track or 366 IESG approved Informational or Experimental RFC. The registry is 367 currently located at: 369 https://www.iana.org/assignments/imap4-capabilities 371 IANA is requested to add definition of the PARTIAL extension to point 372 to this document. 374 10. Acknowledgments 376 This document was motivated by Yahoo! team and their questions about 377 best client practices for dealing with large mailboxes. 379 This document uses lots of text from RFC 5267. Thus work of the RFC 380 5267 authors Dave Cridland and Curtis King is appreciated. 382 11. Normative References 384 [ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for 385 Syntax Specifications: ABNF", RFC 5234, January 2008, 386 . 388 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 389 Requirement Levels", BCP 14, RFC 2119, 390 DOI 10.17487/RFC2119, March 1997, 391 . 393 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 394 4rev1", RFC 3501, DOI 10.17487/RFC3501, March 2003, 395 . 397 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH 398 Command for Controlling What Kind of Information Is 399 Returned", RFC 4731, DOI 10.17487/RFC4731, November 2006, 400 . 402 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267, 403 DOI 10.17487/RFC5267, July 2008, 404 . 406 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 407 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 408 May 2017, . 410 [RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message 411 Access Protocol (IMAP) - Version 4rev2", RFC 9051, 412 DOI 10.17487/RFC9051, August 2021, 413 . 415 Index 417 M 419 M 421 MESSAGELIMIT (response code) 422 Section 6, Paragraph 3.2.1 424 Authors' Addresses 426 Alexey Melnikov 427 Isode Limited 429 Email: alexey.melnikov@isode.com 430 URI: https://www.isode.com 432 Arun Prakash Achuthan 433 Yahoo! 435 Email: arunprakash@myyahoo.com 437 Vikram Nagulakonda 438 Yahoo! 440 Email: nvikram_imap@yahoo.com 442 Luis Alves 443 Verizon Media 445 Email: luis.alves@lafaspot.com