1
2
3
4
5
6
7Internet Engineering Task Force (IETF) A. Melnikov
8Request for Comments: 7162 Isode Ltd
9Obsoletes: 4551, 5162 D. Cridland
10Updates: 2683 Surevine Ltd
11Category: Standards Track May 2014
12ISSN: 2070-1721
13
14
15 IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE)
16 and Quick Mailbox Resynchronization (QRESYNC)
17
18Abstract
19
20 Often, multiple IMAP (RFC 3501) clients need to coordinate changes to
21 a common IMAP mailbox. Examples include different clients working on
22 behalf of the same user and multiple users accessing shared
23 mailboxes. These clients need a mechanism to efficiently synchronize
24 state changes for messages within the mailbox.
25
26 Initially defined in RFC 4551, the Conditional Store facility
27 provides a protected update mechanism for message state information
28 and a mechanism for requesting only changes to the message state.
29 This memo updates that mechanism and obsoletes RFC 4551, based on
30 operational experience.
31
32 This document additionally updates another IMAP extension, Quick
33 Resynchronization, which builds on the Conditional STORE extension to
34 provide an IMAP client the ability to fully resynchronize a mailbox
35 as part of the SELECT/EXAMINE command, without the need for
36 additional server-side state or client round trips. Hence, this memo
37 obsoletes RFC 5162.
38
39 Finally, this document also updates the line-length recommendation in
40 Section 3.2.1.5 of RFC 2683.
41
42Status of This Memo
43
44 This is an Internet Standards Track document.
45
46 This document is a product of the Internet Engineering Task Force
47 (IETF). It represents the consensus of the IETF community. It has
48 received public review and has been approved for publication by the
49 Internet Engineering Steering Group (IESG). Further information on
50 Internet Standards is available in Section 2 of RFC 5741.
51
52 Information about the current status of this document, any errata,
53 and how to provide feedback on it may be obtained at
54 http://www.rfc-editor.org/info/rfc7162.
55
56
57
58Melnikov & Cridland Standards Track [Page 1]
59
60RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
61
62
63Copyright Notice
64
65 Copyright (c) 2014 IETF Trust and the persons identified as the
66 document authors. All rights reserved.
67
68 This document is subject to BCP 78 and the IETF Trust's Legal
69 Provisions Relating to IETF Documents
70 (http://trustee.ietf.org/license-info) in effect on the date of
71 publication of this document. Please review these documents
72 carefully, as they describe your rights and restrictions with respect
73 to this document. Code Components extracted from this document must
74 include Simplified BSD License text as described in Section 4.e of
75 the Trust Legal Provisions and are provided without warranty as
76 described in the Simplified BSD License.
77
78 This document may contain material from IETF Documents or IETF
79 Contributions published or made publicly available before November
80 10, 2008. The person(s) controlling the copyright in some of this
81 material may not have granted the IETF Trust the right to allow
82 modifications of such material outside the IETF Standards Process.
83 Without obtaining an adequate license from the person(s) controlling
84 the copyright in such materials, this document may not be modified
85 outside the IETF Standards Process, and derivative works of it may
86 not be created outside the IETF Standards Process, except to format
87 it for publication as an RFC or to translate it into languages other
88 than English.
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114Melnikov & Cridland Standards Track [Page 2]
115
116RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
117
118
119Table of Contents
120
121 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
122 2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 5
123 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 5
124 3.1. CONDSTORE Extension . . . . . . . . . . . . . . . . . . . 5
125 3.1.1. Advertising Support for CONDSTORE . . . . . . . . . . 8
126 3.1.2. New OK Untagged Responses for SELECT and EXAMINE . . 8
127 3.1.3. STORE and UID STORE Commands . . . . . . . . . . . . 10
128 3.1.4. FETCH and UID FETCH Commands . . . . . . . . . . . . 16
129 3.1.5. MODSEQ Search Criterion in SEARCH . . . . . . . . . . 19
130 3.1.6. Modified SEARCH Untagged Response . . . . . . . . . . 20
131 3.1.7. HIGHESTMODSEQ Status Data Items . . . . . . . . . . . 21
132 3.1.8. CONDSTORE Parameter to SELECT and EXAMINE . . . . . . 21
133 3.1.9. Interaction with IMAP SORT and THREAD Extensions . . 22
134 3.1.10. Interaction with IMAP ESORT and ESEARCH Extensions . 22
135 3.1.11. Additional Quality-of-Implementation Issues . . . . . 23
136 3.1.12. CONDSTORE Server Implementation Considerations . . . 23
137 3.2. QRESYNC Extension . . . . . . . . . . . . . . . . . . . . 24
138 3.2.1. Impact on CONDSTORE-only Clients . . . . . . . . . . 25
139 3.2.2. Advertising Support for QRESYNC . . . . . . . . . . . 25
140 3.2.3. Use of ENABLE . . . . . . . . . . . . . . . . . . . . 25
141 3.2.4. Additional Requirements on QRESYNC Servers . . . . . 26
142 3.2.5. QRESYNC Parameter to SELECT/EXAMINE . . . . . . . . . 26
143 3.2.6. VANISHED UID FETCH Modifier . . . . . . . . . . . . . 31
144 3.2.7. EXPUNGE Command . . . . . . . . . . . . . . . . . . . 32
145 3.2.8. CLOSE Command . . . . . . . . . . . . . . . . . . . . 33
146 3.2.9. UID EXPUNGE Command . . . . . . . . . . . . . . . . . 34
147 3.2.10. VANISHED Response . . . . . . . . . . . . . . . . . . 35
148 3.2.11. CLOSED Response Code . . . . . . . . . . . . . . . . 38
149 4. Long Command Lines (Update to RFC 2683) . . . . . . . . . . . 39
150 5. QRESYNC Server Implementation Considerations . . . . . . . . 39
151 5.1. Server Implementations That Don't Store Extra State . . . 39
152 5.2. Server Implementations Storing Minimal State . . . . . . 40
153 5.3. Additional State Required on the Server . . . . . . . . . 40
154 6. Updated Synchronization Sequence . . . . . . . . . . . . . . 41
155 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 44
156 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48
157 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
158 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
159 10.1. Normative References . . . . . . . . . . . . . . . . . . 48
160 10.2. Informative References . . . . . . . . . . . . . . . . . 49
161 Appendix A. Changes since RFC 4551 . . . . . . . . . . . . . . . 50
162 Appendix B. Changes since RFC 5162 . . . . . . . . . . . . . . . 50
163 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 51
164
165
166
167
168
169
170Melnikov & Cridland Standards Track [Page 3]
171
172RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
173
174
1751. Introduction
176
177 Often, multiple IMAP [RFC3501] clients need to coordinate changes to
178 a common IMAP mailbox. Examples include different clients working on
179 behalf of the same user and clients representing multiple users
180 accessing shared mailboxes. These clients need a mechanism to
181 synchronize state changes for messages within the mailbox. The
182 Conditional Store ("CONDSTORE") facility allows a client to quickly
183 resynchronize mailbox flag changes.
184
185 The Conditional Store facility also provides a protected update
186 mechanism for message state information that can detect and resolve
187 conflicts between multiple writing mail clients. The mechanism can
188 be used to guarantee that only one client can change the message
189 state at any given time. For example, this can be used by multiple
190 clients that treat a mailbox as a message queue.
191
192 The Conditional Store facility is provided by associating a
193 modification sequence (mod-sequence) with every IMAP message. This
194 is updated whenever metadata (such as a message flag) is modified.
195
196 The CONDSTORE extension is described in more detail in Section 3.1.
197
198 The CONDSTORE extension gives a disconnected client the ability to
199 quickly resynchronize IMAP flag changes for previously seen messages.
200 This can be done using the CHANGEDSINCE FETCH modifier once a mailbox
201 is opened. In order for the client to discover which messages have
202 been expunged, the client still has to issue a UID FETCH or a UID
203 SEARCH command. The Quick Mailbox Resynchronization (QRESYNC) IMAP
204 extension is an extension to CONDSTORE that allows a reconnecting
205 client to perform full resynchronization, including discovery of
206 expunged messages, in a single round trip. QRESYNC also introduces a
207 new response, VANISHED, that allows for a more compact representation
208 of a list of expunged messages.
209
210 QRESYNC can be useful for mobile clients that can experience frequent
211 disconnects caused by environmental factors (such as battery life,
212 signal strength, etc.). Such clients need a way to quickly reconnect
213 to the IMAP server, while minimizing delay experienced by the user as
214 well as the amount of traffic generated by resynchronization.
215
216 By extending the SELECT command to perform the additional
217 resynchronization, this also allows clients to reduce concurrent
218 connections to the IMAP server held purely for the sake of avoiding
219 the resynchronization.
220
221 The QRESYNC extension is described in more detail in Section 3.2.
222
223
224
225
226Melnikov & Cridland Standards Track [Page 4]
227
228RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
229
230
2312. Requirements Notation
232
233 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
234 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
235 document are to be interpreted as described in [RFC2119].
236
237 In the examples that follow, "C:" and "S:" indicate lines sent by the
238 client and server, respectively. If a single "C:" or "S:" label
239 applies to multiple lines, then the line breaks between those lines
240 are for editorial clarity only and are not part of the actual
241 protocol exchange. The five characters [...] means that something
242 has been elided.
243
244 Formal syntax is defined using ABNF [RFC5234].
245
246 The term "metadata" or "metadata item" is used throughout this
247 document. It refers to any system- or user-defined keyword. If the
248 server supports the IMAP ANNOTATE-EXPERIMENT-1 extension [RFC5257],
249 then metadata also includes message annotations. Future documents
250 may extend "metadata" to include other dynamic message data.
251
252 Some IMAP mailboxes are private, accessible only to the owning user.
253 Other mailboxes are not, either because the owner has set an Access
254 Control List [RFC4314] that permits access by other users or because
255 it is a shared mailbox. Let's call a metadata item "shared" for the
256 mailbox if any changes to the metadata items are persistent and
257 visible to all other users accessing the mailbox. Otherwise, the
258 metadata item is called "private". Note that private metadata items
259 are still visible to all sessions accessing the mailbox as the same
260 user. Also, note that different mailboxes may have different
261 metadata items as shared.
262
263 See Section 3.1 for the definition of a "CONDSTORE-aware client" and
264 a "CONDSTORE enabling command".
265
266 Understanding of the IMAP message sequence numbers and UIDs (see
267 Section 2.3.1 of [RFC3501]) and the EXPUNGE response (see
268 Section 7.4.1 of [RFC3501]) is essential when reading this document.
269
2703. IMAP Protocol Changes
271
2723.1. CONDSTORE Extension
273
274 An IMAP server that supports CONDSTORE MUST associate a positive
275 unsigned 63-bit (*) value, called a mod-sequence, with every IMAP
276 message. This is an opaque value updated by the server whenever a
277 metadata item is modified. The server MUST guarantee that each STORE
278 command performed on the same mailbox (including simultaneous stores
279
280
281
282Melnikov & Cridland Standards Track [Page 5]
283
284RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
285
286
287 to different metadata items from different connections) will get a
288 different mod-sequence value. Also, for any two successful STORE
289 operations performed in the same session on the same mailbox, the
290 mod-sequence of the second completed operation MUST be greater than
291 the mod-sequence of the first completed operation. Note that the
292 latter rule disallows the direct use of the system clock as a mod-
293 sequence because if system time changes (e.g., an NTP [NTP] client
294 adjusting the time), the next generated value might be less than the
295 previous one.
296
297 (*) Note: RFC 4551 defined mod-sequences as unsigned 64-bit values. 9051:6794 ../imapserver/parse.go:247
298 In order to make implementations on various platforms (such as Java)
299 easier, this version of the document redefines them as unsigned
300 63-bit values.
301
302 These rules allow a client to list all metadata changes since a well-
303 known point in time, as well as to perform conditional metadata
304 modifications based on an assumption that the metadata state hasn't
305 changed for a particular message.
306
307 In particular, mod-sequences allow a client that supports the
308 CONDSTORE extension to determine if a message metadata has changed
309 since some known moment. Whenever the state of a flag changes (i.e.,
310 the flag is added where previously it wasn't set, or the flag is
311 removed where previously it was set), the value of the modification
312 sequence for the message MUST be updated. Setting a flag that is 7162:1246 ../imapserver/server.go:3778
313 already set, or clearing a flag that is not set, SHOULD NOT change
314 the mod-sequence.
315
316 When a message is appended to a mailbox (via the IMAP APPEND command,
317 COPY to the mailbox, or using an external mechanism), the server
318 generates a new modification sequence that is higher than the highest
319 modification sequence of all messages in the mailbox and assigns it
320 to the appended message.
321
322 The server MAY store separate (per-message) modification sequence
323 values for different metadata items. If the server does so, per-
324 message mod-sequence is the highest mod-sequence of all metadata
325 items accessible to the currently logged-in user for the specified
326 message.
327
328 The server that supports CONDSTORE is not required to be able to
329 store mod-sequences for every available mailbox. Section 3.1.2.2
330 describes how the server may act if a particular mailbox doesn't
331 support the persistent storage of mod-sequences.
332
333
334
335
336
337
338Melnikov & Cridland Standards Track [Page 6]
339
340RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
341
342
343 CONDSTORE makes the following changes to the IMAP4 protocol:
344
345 a. adds the UNCHANGEDSINCE STORE modifier.
346
347 b. adds the MODIFIED response code that is used with an OK response
348 to the STORE command. (It can also be used in a NO response.)
349
350 c. adds a new MODSEQ message data item for use with the FETCH
351 command.
352
353 d. adds the CHANGEDSINCE FETCH modifier.
354
355 e. adds a new MODSEQ search criterion.
356
357 f. extends the syntax of untagged SEARCH and ESEARCH responses to
358 include mod-sequence.
359
360 g. adds new OK untagged responses (HIGHESTMODSEQ and NOMODSEQ) for
361 the SELECT and EXAMINE commands.
362
363 h. defines an additional CONDSTORE parameter to SELECT/EXAMINE ../imapserver/server.go:1959
364 commands.
365
366 i. adds the HIGHESTMODSEQ status data item to the STATUS command. ../imapserver/server.go:2658
367
368 A client supporting the CONDSTORE extension indicates its willingness ../imapserver/condstore_test.go:340 ../imapserver/server.go:1896
369 to receive mod-sequence updates in all untagged FETCH responses by
370 issuing one of the following, which are called "CONDSTORE enabling
371 commands":
372
373 o a SELECT or EXAMINE command with the CONDSTORE parameter, ../imapserver/condstore_test.go:369 ../imapserver/server.go:1960
374
375 o a STATUS (HIGHESTMODSEQ) command, ../imapserver/condstore_test.go:374 ../imapserver/parse.go:443
376
377 o a FETCH or SEARCH command that includes the MODSEQ message data ../imapserver/condstore_test.go:380 ../imapserver/condstore_test.go:386 ../imapserver/parse.go:606 ../imapserver/parse.go:902
378 item,
379
380 o a FETCH command with the CHANGEDSINCE modifier, ../imapserver/condstore_test.go:392 ../imapserver/fetch.go:109
381
382 o a STORE command with the UNCHANGEDSINCE modifier, or ../imapserver/condstore_test.go:398 ../imapserver/server.go:3661
383
384 o an ENABLE command containing "CONDSTORE" as one of the parameters. ../imapserver/condstore_test.go:404 ../imapserver/server.go:1876
385 (This option only applies when the client is communicating with a
386 server that also implements the ENABLE extension [RFC5161].)
387
388 Once a client issues a CONDSTORE enabling command, it has announced 7162:877 7162:909 7162:1426 7162:923 7162:852 ../imapserver/fetch.go:377 ../imapserver/parse.go:605 ../imapserver/server.go:3832
389 itself as a "CONDSTORE-aware client". The server MUST then include ../imapserver/fetch.go:370
390 mod-sequence data in all subsequent untagged FETCH responses (until
391
392
393
394Melnikov & Cridland Standards Track [Page 7]
395
396RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
397
398
399 the connection is closed), whether they were caused by a regular
400 STORE, a STORE with an UNCHANGEDSINCE modifier, or an external agent.
401
402 A future extension to this document may extend the list of CONDSTORE
403 enabling commands. A first CONDSTORE enabling command executed in
404 the session with a mailbox selected MUST cause the server to return
405 HIGHESTMODSEQ (Section 3.1.2.1) for the mailbox (if any is selected),
406 unless the server has sent a NOMODSEQ (Section 3.1.2.2) response code
407 when the currently selected mailbox was selected.
408
4093.1.1. Advertising Support for CONDSTORE
410
411 The Conditional STORE extension is present in any IMAP4 ../imapserver/server.go:154
412 implementation that returns "CONDSTORE" as one of the supported
413 capabilities in the CAPABILITY command response.
414
4153.1.2. New OK Untagged Responses for SELECT and EXAMINE
416
417 This document adds two new response codes: HIGHESTMODSEQ and ../imapserver/server.go:2068
418 NOMODSEQ. One of these two response codes MUST be returned in an OK
419 untagged response for any successful SELECT/EXAMINE command issued
420 after a CONDSTORE enabling command.
421
422 When opening a mailbox, the server must check if the mailbox supports
423 the persistent storage of mod-sequences. If the mailbox supports the
424 persistent storage of mod-sequences and the mailbox open operation
425 succeeds, the server MUST send an OK untagged response, including the
426 HIGHESTMODSEQ response code. If the persistent storage for the
427 mailbox is not supported, the server MUST send an OK untagged
428 response, including the NOMODSEQ response code instead.
429
4303.1.2.1. HIGHESTMODSEQ Response Code
431
432 This document adds a new response code that is returned in an OK
433 untagged response for the SELECT and EXAMINE commands. Once a
434 CONDSTORE enabling command is issued, a server supporting the
435 persistent storage of mod-sequences for the mailbox MUST send an OK
436 untagged response, including the HIGHESTMODSEQ response code with
437 every successful SELECT or EXAMINE command:
438
439 OK [HIGHESTMODSEQ <mod-sequence-value>]
440
441 where <mod-sequence-value> is the highest mod-sequence value of
442 all messages in the mailbox. When the server changes UIDVALIDITY
443 for a mailbox, it doesn't have to keep the same HIGHESTMODSEQ for
444 the mailbox.
445
446
447
448
449
450Melnikov & Cridland Standards Track [Page 8]
451
452RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
453
454
455 Note that some existing CONDSTORE servers don't start tracking mod-
456 sequences or don't report them until after a CONDSTORE enabling
457 command is issued. Because of that, a client wishing to receive
458 HIGHESTMODSEQ/NOMODSEQ information must first send a CONDSTORE
459 enabling command, for example, by using SELECT/EXAMINE with the
460 CONDSTORE parameter (see Section 3.1.8).
461
462 A disconnected client can use the value of HIGHESTMODSEQ to check if
463 it has to refetch metadata from the server. If the UIDVALIDITY value
464 has changed for the selected mailbox, the client MUST delete the
465 cached value of HIGHESTMODSEQ. If UIDVALIDITY for the mailbox is the
466 same, and if the HIGHESTMODSEQ value stored in the client's cache is
467 less than the value returned by the server, then some metadata items
468 on the server have changed since the last synchronization, and the
469 client needs to update its cache. The client MAY use SEARCH MODSEQ
470 (Section 3.1.5) to find out exactly which metadata items have
471 changed. Alternatively, the client MAY issue FETCH with the
472 CHANGEDSINCE modifier (Section 3.1.4.1) in order to fetch data for
473 all messages that have metadata items changed since some known
474 modification sequence.
475
476 C: A142 SELECT INBOX
477 S: * 172 EXISTS
478 S: * 1 RECENT
479 S: * OK [UNSEEN 12] Message 12 is first unseen
480 S: * OK [UIDVALIDITY 3857529045] UIDs valid
481 S: * OK [UIDNEXT 4392] Predicted next UID
482 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
483 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
484 S: * OK [HIGHESTMODSEQ 715194045007] 7162-eid5055:1 7162:1167 ../imapserver/server.go:2069
485 S: A142 OK [READ-WRITE] SELECT completed
486
487 Example 1
488
4893.1.2.2. NOMODSEQ Response Code
490
491 Once a CONDSTORE enabling command is issued, a server that doesn't
492 support the persistent storage of mod-sequences for the mailbox MUST
493 send an OK untagged response, including the NOMODSEQ response code
494 with every successful SELECT or EXAMINE command. Note that some
495 existing CONDSTORE servers don't return NOMODSEQ until after a
496 CONDSTORE enabling command is issued. Because of that, a client
497 wishing to receive HIGHESTMODSEQ/NOMODSEQ information must first send
498 a CONDSTORE enabling command, for example, by using SELECT/EXAMINE
499 with the CONDSTORE parameter (see Section 3.1.8).
500
501
502
503
504
505
506Melnikov & Cridland Standards Track [Page 9]
507
508RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
509
510
511 A server that returned the NOMODSEQ response code for a mailbox MUST
512 reject (with a tagged BAD response) any of the following commands
513 while the mailbox remains selected:
514
515 o a FETCH command with the CHANGEDSINCE modifier,
516
517 o a FETCH or SEARCH command that includes the MODSEQ message data
518 item, or
519
520 o a STORE command with the UNCHANGEDSINCE modifier.
521
522 C: A142 SELECT INBOX
523 S: * 172 EXISTS
524 S: * 1 RECENT
525 S: * OK [UNSEEN 12] Message 12 is first unseen
526 S: * OK [UIDVALIDITY 3857529045] UIDs valid
527 S: * OK [UIDNEXT 4392] Predicted next UID
528 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
529 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
530 S: * OK [NOMODSEQ] Sorry, this mailbox format doesn't support
531 modsequences
532 S: A142 OK [READ-WRITE] SELECT completed
533
534 Example 2
535
5363.1.3. STORE and UID STORE Commands
537
538 This document defines the following STORE modifier (see Section 2.5
539 of [RFC4466]):
540
541 UNCHANGEDSINCE <mod-sequence>
542
543 For each message specified in the message set, the server performs
544 the following. If the mod-sequence of every metadata item of the
545 message affected by the STORE/UID STORE is equal to or less than the
546 specified UNCHANGEDSINCE value, then the requested operation (as
547 described by the message data item) is performed. If the operation
548 is successful, the server MUST update the mod-sequence attribute of
549 the message. An untagged FETCH response MUST be sent, even if the ../imapserver/server.go:3833
550 .SILENT suffix is specified, and the response MUST include the MODSEQ
551 message data item. This is required to update the client's cache
552 with the correct mod-sequence values. See Section 3.1.4.2 for more
553 details.
554
555 However, if the mod-sequence of any metadata item of the message is ../imapserver/server.go:3762
556 greater than the specified UNCHANGEDSINCE value, then the requested
557 operation MUST NOT be performed. In this case, the mod-sequence
558
559
560
561
562Melnikov & Cridland Standards Track [Page 10]
563
564RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
565
566
567 attribute of the message is not updated, and the message number (or
568 unique identifier in the case of the UID STORE command) is added to
569 the list of messages that failed the UNCHANGEDSINCE test.
570
571 When the server finishes performing the operation on all the messages ../imapserver/server.go:3860
572 in the message set, it checks for a non-empty list of messages that
573 failed the UNCHANGEDSINCE test. If this list is non-empty, the
574 server MUST return in the tagged response a MODIFIED response code.
575 The MODIFIED response code includes the message set (for STORE) or
576 set of UIDs (for UID STORE) of all messages that failed the
577 UNCHANGEDSINCE test.
578
579 All messages pass the UNCHANGEDSINCE test.
580
581 C: a103 UID STORE 6,4,8 (UNCHANGEDSINCE 12121230045)
582 +FLAGS.SILENT (\Deleted)
583 S: * 1 FETCH (UID 4 MODSEQ (12121231000))
584 S: * 2 FETCH (UID 6 MODSEQ (12121230852))
585 S: * 4 FETCH (UID 8 MODSEQ (12121230956))
586 S: a103 OK Conditional Store completed
587
588 Example 3
589
590 C: a104 STORE * (UNCHANGEDSINCE 12121230045) +FLAGS.SILENT
591 (\Deleted $Processed)
592 S: * 50 FETCH (MODSEQ (12111230047))
593 S: a104 OK Store (conditional) completed
594
595 Example 4
596
597 C: c101 STORE 50 (UNCHANGEDSINCE 12121230045) -FLAGS.SILENT
598 (\Deleted)
599 S: * OK [HIGHESTMODSEQ 12111230047]
600 S: * 50 FETCH (MODSEQ (12111230048))
601 S: c101 OK Store (conditional) completed
602
603 The HIGHESTMODSEQ response code was sent by the server presumably ../imapserver/server.go:1904
604 because this was the first CONDSTORE enabling command.
605
606 Example 5
607
608 The failure of the conditional STORE operation for any particular
609 message or messages (7 in this example) does not stop the server from
610 finding all messages that fail the UNCHANGEDSINCE test. All such
611 messages are returned in the MODIFIED response code.
612
613
614
615
616
617
618Melnikov & Cridland Standards Track [Page 11]
619
620RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
621
622
623 C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338)
624 +FLAGS.SILENT (\Deleted)
625 S: * 5 FETCH (MODSEQ (320162350))
626 S: d105 OK [MODIFIED 7,9] Conditional STORE failed
627
628 Example 6
629
630 Same as above, but the server follows the SHOULD recommendation in 3501:3233 ../imapserver/server.go:3851
631 Section 6.4.6 of [RFC3501].
632
633 C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338)
634 +FLAGS.SILENT (\Deleted)
635 S: * 7 FETCH (MODSEQ (320162342) FLAGS (\Seen \Deleted))
636 S: * 5 FETCH (MODSEQ (320162350))
637 S: * 9 FETCH (MODSEQ (320162349) FLAGS (\Answered))
638 S: d105 OK [MODIFIED 7,9] Conditional STORE failed
639
640 Use of UNCHANGEDSINCE with a modification sequence of 0 always fails ../imapserver/condstore_test.go:202 ../imapserver/server.go:3766
641 if the metadata item exists. A system flag MUST always be considered
642 existent, whether it was set or not.
643
644 Example 7
645
646 C: a102 STORE 12 (UNCHANGEDSINCE 0)
647 +FLAGS.SILENT ($MDNSent)
648 S: a102 OK [MODIFIED 12] Conditional STORE failed
649
650 The client has tested the presence of the $MDNSent user-defined
651 keyword.
652
653 Example 8
654
655 Note: A client trying to make an atomic change to the state of a
656 particular metadata item (or a set of metadata items) MUST be
657 prepared to deal with the case when the server returns the MODIFIED
658 response code if the state of the metadata item being watched hasn't
659 changed (but the state of some other metadata item has). This is
660 necessary because some servers don't store separate mod-sequences for
661 different metadata items. However, a server implementation SHOULD
662 avoid generating spurious MODIFIED responses for +FLAGS/-FLAGS STORE
663 operations, even when the server stores a single mod-sequence per
664 message. Section 3.1.12 describes how this can be achieved.
665
666 Unless the server has included an unsolicited FETCH to update the
667 client's knowledge about messages that have failed the UNCHANGEDSINCE
668 test, upon receipt of the MODIFIED response code, the client SHOULD
669 try to figure out if the required metadata items have indeed changed
670
671
672
673
674Melnikov & Cridland Standards Track [Page 12]
675
676RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
677
678
679 by issuing the FETCH or NOOP command. It is RECOMMENDED that the ../imapserver/server.go:3859
680 server avoids the need for the client to do that by sending an
681 unsolicited FETCH response (see Examples 9 and 10).
682
683 If the required metadata items haven't changed, the client SHOULD
684 retry the command with the new mod-sequence. The client needs to
685 allow for a reasonable number of retries (at least 2).
686
687 In the example below, the server returns the MODIFIED response code
688 without sending information describing why the STORE UNCHANGEDSINCE
689 operation has failed.
690
691 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
692 +FLAGS.SILENT ($Processed)
693 S: * 100 FETCH (MODSEQ (303181230852))
694 S: * 102 FETCH (MODSEQ (303181230852))
695 ...
696 S: * 150 FETCH (MODSEQ (303181230852))
697 S: a106 OK [MODIFIED 101] Conditional STORE failed
698
699 The flag $Processed was set on the message 101...
700
701 C: a107 NOOP
702 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed))
703 S: a107 OK
704
705 Example 9
706
707 Or, the flag hasn't changed, but another has (note that this server
708 behavior is discouraged. Server implementers should also see
709 Section 3.1.12)...
710
711 C: b107 NOOP
712 S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered))
713 S: b107 OK
714
715 ...and the client retries the operation for the message 101 with
716 the updated UNCHANGEDSINCE value.
717
718 C: b108 STORE 101 (UNCHANGEDSINCE 303011130956)
719 +FLAGS.SILENT ($Processed)
720 S: * 101 FETCH (MODSEQ (303181230852))
721 S: b108 OK Conditional Store completed
722
723 Same as above, but the server avoids the need for the client to poll
724 for changes.
725
726
727
728
729
730Melnikov & Cridland Standards Track [Page 13]
731
732RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
733
734
735 The flag $Processed was set on the message 101 by another
736 client...
737
738 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
739 +FLAGS.SILENT ($Processed)
740 S: * 100 FETCH (MODSEQ (303181230852))
741 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed))
742 S: * 102 FETCH (MODSEQ (303181230852))
743 ...
744 S: * 150 FETCH (MODSEQ (303181230852))
745 S: a106 OK [MODIFIED 101] Conditional STORE failed
746
747 Example 10
748
749 Or, the flag hasn't changed, but another has (note that this server
750 behavior is discouraged. Server implementers should also see
751 Section 3.1.12)...
752
753
754 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
755 +FLAGS.SILENT ($Processed)
756 S: * 100 FETCH (MODSEQ (303181230852))
757 S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered))
758 S: * 102 FETCH (MODSEQ (303181230852))
759 ...
760 S: * 150 FETCH (MODSEQ (303181230852))
761 S: a106 OK [MODIFIED 101] Conditional STORE failed
762
763 ...and the client retries the operation for the message 101 with
764 the updated UNCHANGEDSINCE value.
765
766 C: b108 STORE 101 (UNCHANGEDSINCE 303011130956)
767 +FLAGS.SILENT ($Processed)
768 S: * 101 FETCH (MODSEQ (303181230852))
769 S: b108 OK Conditional Store completed
770
771 Or, the flag hasn't changed, but another has (nice server behavior.
772 Server implementers should also see Section 3.1.12)...
773
774 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
775 +FLAGS.SILENT ($Processed)
776 S: * 100 FETCH (MODSEQ (303181230852))
777 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed \Deleted
778 \Answered))
779 S: * 102 FETCH (MODSEQ (303181230852))
780 ...
781 S: * 150 FETCH (MODSEQ (303181230852))
782 S: a106 OK Conditional STORE completed
783
784
785
786Melnikov & Cridland Standards Track [Page 14]
787
788RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
789
790
791 The following example is based on the example from Section 4.2.3 of
792 [RFC2180] and demonstrates that the MODIFIED response code MAY also
793 be returned in the tagged NO response.
794
795 The client tries to conditionally STORE flags on a mixture of
796 expunged and non-expunged messages; one message fails the
797 UNCHANGEDSINCE test.
798
799 C: B001 STORE 1:7 (UNCHANGEDSINCE 320172338) +FLAGS (\SEEN)
800 S: * 1 FETCH (MODSEQ (320172342) FLAGS (\SEEN))
801 S: * 3 FETCH (MODSEQ (320172342) FLAGS (\SEEN))
802 S: B001 NO [MODIFIED 2] Some of the messages no longer exist.
803
804 C: B002 NOOP
805 S: * 4 EXPUNGE
806 S: * 4 EXPUNGE
807 S: * 4 EXPUNGE
808 S: * 4 EXPUNGE
809 S: * 2 FETCH (MODSEQ (320172340) FLAGS (\Deleted \Answered))
810 S: B002 OK NOOP Completed.
811
812 By receiving FETCH responses for messages 1 and 3, and EXPUNGE
813 responses that indicate that messages 4 through 7 have been
814 expunged, the client retries the operation only for message 2.
815 The updated UNCHANGEDSINCE value is used.
816
817 C: b003 STORE 2 (UNCHANGEDSINCE 320172340) +FLAGS (\Seen)
818 S: * 2 FETCH (MODSEQ (320180050) FLAGS (\SEEN \Flagged))
819 S: b003 OK Conditional Store completed
820
821 Example 11
822
823 Note: If a message is specified multiple times in the message set, ../imapserver/condstore_test.go:226 ../imapserver/server.go:3735
824 and the server doesn't internally eliminate duplicates from the
825 message set, it MUST NOT fail the conditional STORE operation for the
826 second (or subsequent) occurrence of the message if the operation
827 completed successfully for the first occurrence. For example, if the
828 client specifies:
829
830 e105 STORE 7,3:9 (UNCHANGEDSINCE 12121230045) +FLAGS.SILENT
831 (\Deleted)
832
833 the server must not fail the operation for message 7 as part of
834 processing "3:9" if it succeeded when message 7 was processed the
835 first time.
836
837
838
839
840
841
842Melnikov & Cridland Standards Track [Page 15]
843
844RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
845
846
847 As specified in Section 3.1, once the client specifies the
848 UNCHANGEDSINCE modifier in a STORE command, the server starts
849 including the MODSEQ FETCH response data items in all subsequent
850 unsolicited FETCH responses.
851
852 This document also changes the behavior of the server when it has 7162:388 ../imapserver/server.go:3832
853 performed a STORE or UID STORE command and the UNCHANGEDSINCE
854 modifier is not specified. If the operation is successful for a
855 message, the server MUST update the mod-sequence attribute of the
856 message. The server is REQUIRED to include the mod-sequence value
857 whenever it decides to send the unsolicited FETCH response to all
858 CONDSTORE-aware clients that have opened the mailbox containing the
859 message.
860
861 Server implementers should also see Section 3.1.11 for additional
862 quality of implementation issues related to the STORE command.
863
8643.1.4. FETCH and UID FETCH Commands 9051:4330 3501:2992 ../imapserver/fetch.go:71
865
8663.1.4.1. CHANGEDSINCE FETCH Modifier
867
868 This document defines the following FETCH modifier (see Section 2.4
869 of [RFC4466]):
870
871 CHANGEDSINCE <mod-sequence>: The CHANGEDSINCE FETCH modifier allows ../imapserver/condstore_test.go:191 ../imapserver/fetch.go:150
872 the client to further subset the list of messages described by the
873 sequence set. The information described by message data items is
874 only returned for messages that have a mod-sequence bigger than
875 <mod-sequence>.
876
877 When the CHANGEDSINCE FETCH modifier is specified, it implicitly 7162:388 7162:909 7162:1426 ../imapserver/condstore_test.go:192 ../imapserver/fetch.go:377
878 adds the MODSEQ FETCH message data item (Section 3.1.4.2).
879
880 C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345) 9051:4463 9051:4520 ../imapserver/fetch.go:72
881 S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen))
882 S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted))
883 S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk
884 $MDNSent))
885 S: s100 OK FETCH completed
886
887 Example 12
888
889
890
891
892
893
894
895
896
897
898Melnikov & Cridland Standards Track [Page 16]
899
900RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
901
902
9033.1.4.2. MODSEQ Message Data Item in FETCH Command
904
905 CONDSTORE adds a MODSEQ message data item to the FETCH command. The ../imapserver/parse.go:604
906 MODSEQ message data item allows clients to retrieve mod-sequence
907 values for a range of messages in the currently selected mailbox.
908
909 As specified in Section 3.1, once the client has specified the MODSEQ 7162:877 7162:388 7162:1426 ../imapserver/fetch.go:377
910 message data item in a FETCH request, the server starts including the
911 MODSEQ FETCH response data items in all subsequent unsolicited FETCH
912 responses.
913
914 Syntax: MODSEQ
915
916 The MODSEQ message data item causes the server to return MODSEQ
917 FETCH response data items.
918
919 Syntax: MODSEQ ( <permsg-modsequence> )
920
921 MODSEQ response data items contain per-message mod-sequences.
922
923 The MODSEQ response data item is returned if the client issued 7162:388 ../imapserver/parse.go:605
924 FETCH with the MODSEQ message data item. It also allows the
925 server to notify the client about mod-sequence changes caused by
926 conditional STOREs (Section 3.1.3) and/or changes caused by
927 external sources.
928
929 C: a FETCH 1:3 (MODSEQ)
930 S: * 1 FETCH (MODSEQ (624140003))
931 S: * 2 FETCH (MODSEQ (624140007))
932 S: * 3 FETCH (MODSEQ (624140005))
933 S: a OK Fetch complete
934
935 In this example, the client requests per-message mod-sequences for a
936 set of messages.
937
938 Example 13
939
940 Servers that only support the CONDSTORE extension (and not QRESYNC)
941 SHOULD comply with requirements from Section 3.2.4.
942
943 When a flag for a message is modified in a different session, the
944 server sends an unsolicited FETCH response containing the mod-
945 sequence for the message, as demonstrated in Example 14. Note that
946 when the server also supports the QRESYNC extension (Section 3.2.3)
947 and a CONDSTORE enabling command has been issued, all FETCH responses
948 in Example 14 must also include UID FETCH items as prescribed by
949 Section 3.2.4.
950
951
952
953
954Melnikov & Cridland Standards Track [Page 17]
955
956RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
957
958
959 (Session 1, authenticated as the user "alex".) The user adds a
960 shared flag \Deleted:
961
962 C: A142 SELECT INBOX
963 ...
964 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
965 S: * OK [PERMANENTFLAGS (\Answered \Deleted \Seen \*)] Limited
966 ...
967 C: A160 STORE 7 +FLAGS.SILENT (\Deleted)
968 S: * 7 FETCH (MODSEQ (2121231000))
969 S: A160 OK Store completed
970
971 (Session 2, also authenticated as the user "alex".) Any changes
972 to flags are always reported to all sessions authenticated as the
973 same user as in session 1.
974
975 C: C180 NOOP
976 S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
977 S: C180 OK Noop completed
978
979 (Session 3, authenticated as the user "andrew".) As \Deleted is a
980 shared flag, changes in session 1 are also reported in session 3:
981
982 C: D210 NOOP
983 S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
984 S: D210 OK Noop completed
985
986 The user modifies a private flag, \Seen, in session 1...
987
988 C: A240 STORE 7 +FLAGS.SILENT (\Seen)
989 S: * 7 FETCH (MODSEQ (12121231777))
990 S: A240 OK Store completed
991
992 ...which is only reported in session 2...
993
994 C: C270 NOOP
995 S: * 7 FETCH (FLAGS (\Deleted \Answered \Seen) MODSEQ
996 (12121231777))
997 S: C270 OK Noop completed
998
999 ...but not in session 3.
1000
1001 C: D300 NOOP
1002 S: D300 OK Noop completed
1003
1004
1005
1006
1007
1008
1009
1010Melnikov & Cridland Standards Track [Page 18]
1011
1012RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1013
1014
1015 And, finally, the user removes flags \Answered (shared) and \Seen
1016 (private) in session 1.
1017
1018 C: A330 STORE 7 -FLAGS.SILENT (\Answered \Seen)
1019 S: * 7 FETCH (MODSEQ (12121245160))
1020 S: A330 OK Store completed
1021
1022 Both changes are reported in session 2...
1023
1024 C: C360 NOOP
1025 S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
1026 S: C360 OK Noop completed
1027
1028 ...and only changes to shared flags are reported in session 3.
1029
1030 C: D390 NOOP
1031 S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
1032 S: D390 OK Noop completed
1033
1034 Example 14
1035
1036 Server implementers should also see Section 3.1.11 for additional
1037 quality of implementation issues related to the FETCH command.
1038
10393.1.5. MODSEQ Search Criterion in SEARCH
1040
1041 The MODSEQ criterion for the SEARCH (or UID SEARCH) command allows a
1042 client to search for the metadata items that were modified since a
1043 specified moment.
1044
1045 Syntax: MODSEQ [<entry-name> <entry-type-req>] <mod-sequence-valzer> 7162:2499 ../imapserver/parse.go:886 ../imapserver/search.go:515
1046
1047 Messages that have modification values that are equal to or
1048 greater than <mod-sequence-valzer>. This allows a client, for
1049 example, to find out which messages contain metadata items that
1050 have changed since the last time it updated its disconnected
1051 cache. The client may also specify <entry-name> (name of the
1052 metadata item) and <entry-type-req> (type of metadata item) before
1053 <mod-sequence-valzer>. <entry-type-req> can be one of "shared",
1054 "priv" (private), or "all". The last means that the server MUST
1055 use the biggest value among "priv" and "shared" mod-sequences for
1056 the metadata item. If the server doesn't store separate mod-
1057 sequences for different metadata items, it MUST ignore <entry-
1058 name> and <entry-type-req>. Otherwise, the server should use them
1059 to narrow down the search.
1060
1061
1062
1063
1064
1065
1066Melnikov & Cridland Standards Track [Page 19]
1067
1068RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1069
1070
1071 For a flag <flagname>, the corresponding <entry-name> has the form
1072 "/flags/<flagname>". Note that the leading "\" character that ../imapserver/parse.go:892
1073 denotes a system flag has to be escaped as per Section 4.3 of
1074 [RFC3501], as <entry-name> uses the syntax for quoted strings (see
1075 the examples below).
1076
1077 If the client specifies a MODSEQ criterion in a SEARCH (or UID 7162:1101 ../imapserver/search.go:201
1078 SEARCH) command and the server returns a non-empty SEARCH result, the
1079 server MUST also append (to the end of the untagged SEARCH response)
1080 the highest mod-sequence for all messages being returned. See also
1081 Section 3.1.6. Note that other IMAP extensions such as ESEARCH
1082 [RFC4731] can override this requirement (see Section 3.1.10 for more
1083 details.)
1084
1085 C: a SEARCH MODSEQ "/flags/\\draft" all 620162338
1086 S: * SEARCH 2 5 6 7 11 12 18 19 20 23 (MODSEQ 917162500)
1087 S: a OK Search complete
1088
1089 In the above example, the message numbers of any messages having a
1090 mod-sequence equal to or greater than 620162338 for the "\Draft" flag
1091 are returned in the search results.
1092
1093 Example 15
1094
1095 C: t SEARCH OR NOT MODSEQ 720162338 LARGER 50000
1096 S: * SEARCH
1097 S: t OK Search complete, nothing found
1098
1099 Example 16
1100
11013.1.6. Modified SEARCH Untagged Response 7162:1077 ../imapclient/protocol.go:220 ../imapserver/search.go:201
1102
1103 Data: zero or more numbers
1104 mod-sequence value (omitted if no match)
1105
1106 This document extends the syntax of the untagged SEARCH response to
1107 include the highest mod-sequence for all messages being returned. ../imapserver/search.go:198
1108
1109 If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH)
1110 command and the server returns a non-empty SEARCH result, the server
1111 MUST also append (to the end of the untagged SEARCH response) the
1112 highest mod-sequence for all messages being returned. See
1113 Section 3.1.5 for examples.
1114
1115
1116
1117
1118
1119
1120
1121
1122Melnikov & Cridland Standards Track [Page 20]
1123
1124RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1125
1126
11273.1.7. HIGHESTMODSEQ Status Data Items 9051:3328 3501:2424 ../imapserver/server.go:2603
1128
1129 This document defines a new status data item:
1130
1131 HIGHESTMODSEQ: The highest mod-sequence value of all messages in the
1132 mailbox. This is the same value that is returned by the server in
1133 the HIGHESTMODSEQ response code in an OK untagged response (see
1134 Section 3.1.2.1). If the server doesn't support the persistent
1135 storage of mod-sequences for the mailbox (see Section 3.1.2.2),
1136 the server MUST return 0 as the value of the HIGHESTMODSEQ status
1137 data item.
1138
1139 C: A042 STATUS blurdybloop (UIDNEXT MESSAGES HIGHESTMODSEQ) 9051:3400 3501:2501 ../imapserver/server.go:2604
1140 S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292
1141 HIGHESTMODSEQ 7011231777)
1142 S: A042 OK STATUS completed
1143
1144 Example 17
1145
11463.1.8. CONDSTORE Parameter to SELECT and EXAMINE 9051:1754 3501:1743 7162:1432 ../imapserver/server.go:1935
1147
1148 The CONDSTORE extension defines a single optional select parameter,
1149 "CONDSTORE", which tells the server that it MUST include the MODSEQ
1150 FETCH response data items in all subsequent unsolicited FETCH
1151 responses.
1152
1153 The CONDSTORE parameter to SELECT/EXAMINE helps avoid a race
1154 condition that might arise when one or more metadata items are
1155 modified in another session after the server has sent the
1156 HIGHESTMODSEQ response code and before the client was able to issue a
1157 CONDSTORE enabling command.
1158
1159 C: A142 SELECT INBOX (CONDSTORE) 9051:1831 3501:1826 7162:1479 ../imapserver/server.go:1937
1160 S: * 172 EXISTS
1161 S: * 1 RECENT
1162 S: * OK [UNSEEN 12] Message 12 is first unseen
1163 S: * OK [UIDVALIDITY 3857529045] UIDs valid
1164 S: * OK [UIDNEXT 4392] Predicted next UID
1165 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
1166 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
1167 S: * OK [HIGHESTMODSEQ 715194045007] 7162-eid5055:1 7162:484 ../imapserver/server.go:2069
1168 S: A142 OK [READ-WRITE] SELECT completed, CONDSTORE is now enabled
1169
1170 Example 18
1171
1172
1173
1174
1175
1176
1177
1178Melnikov & Cridland Standards Track [Page 21]
1179
1180RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1181
1182
11833.1.9. Interaction with IMAP SORT and THREAD Extensions
1184
1185 The MODSEQ Search Criterion (see Section 3.1.5) causes modifications
1186 to SORT [RFC5256] responses similar to modifications to SEARCH
1187 responses defined in Section 3.1.6:
1188
1189 SORT Response Data: zero or more numbers
1190 mod-sequence value (omitted if no match)
1191
1192 This document extends the syntax of the untagged SORT response to
1193 include the highest mod-sequence for all messages being returned.
1194
1195 If a client specifies a MODSEQ criterion in a SORT (or UID SORT)
1196 command and the server returns a non-empty SORT result, the server
1197 MUST also append (to the end of the untagged SORT response) the
1198 highest mod-sequence for all messages being returned. Note that
1199 other IMAP extensions such as ESORT [RFC5267] can override this
1200 requirement (see Section 3.1.10 for more details.)
1201
1202 THREAD commands that include a MODSEQ Search Criterion return THREAD
1203 responses as specified in [RFC5256], i.e., THREAD responses are
1204 unchanged by the CONDSTORE extension.
1205
12063.1.10. Interaction with IMAP ESORT and ESEARCH Extensions
1207
1208 If a client specifies a MODSEQ criterion in an extended SEARCH (or
1209 extended UID SEARCH) [RFC4731] command and the server returns a non-
1210 empty SEARCH result, the server MUST return the ESEARCH response
1211 containing the MODSEQ result option as defined in Section 3.2 of 4731:273 ../imapclient/parse.go:1236 ../imapserver/search.go:259
1212 [RFC4731].
1213
1214 C: a SEARCH RETURN (ALL) MODSEQ 1234
1215 S: * ESEARCH (TAG "a") ALL 1:3,5 MODSEQ 1236
1216 S: a OK Extended SEARCH completed
1217
1218 Example 19
1219
1220 If a client specifies a MODSEQ criterion in an extended SORT (or
1221 extended UID SORT) [RFC5267] command and the server returns a non-
1222 empty SORT result, the server MUST return the ESEARCH response
1223 containing the MODSEQ result option defined in Section 3.2 of
1224 [RFC4731].
1225
1226 C: a SORT RETURN (ALL) (DATE) UTF-8 MODSEQ 1234
1227 S: * ESEARCH (TAG "a") ALL 5,3,2,1 MODSEQ 1236
1228 S: a OK Extended SORT completed
1229
1230 Example 20
1231
1232
1233
1234Melnikov & Cridland Standards Track [Page 22]
1235
1236RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1237
1238
12393.1.11. Additional Quality-of-Implementation Issues
1240
1241 Server implementations should follow the following rule, which
1242 applies to any successfully completed STORE/UID STORE (with and
1243 without an UNCHANGEDSINCE modifier), as well as to a FETCH command
1244 that implicitly sets the \Seen flag:
1245
1246 Adding the flag when it is already present or removing it when it 7162:312 ../imapserver/server.go:3778
1247 is not present SHOULD NOT change the mod-sequence.
1248
1249 This will prevent spurious client synchronization requests.
1250
1251 However, note that client implementers MUST NOT rely on this server
1252 behavior. A client can't distinguish between the case when a server
1253 has violated the SHOULD mentioned above and when one or more clients
1254 set and unset (or unset and set) the flag in another session.
1255
12563.1.12. CONDSTORE Server Implementation Considerations
1257
1258 This section describes how a server implementation that doesn't store ../imapserver/server.go:3772
1259 separate per-metadata mod-sequences for different metadata items can
1260 avoid sending the MODIFIED response to any of the following
1261 conditional STORE operations:
1262
1263 +FLAGS
1264
1265 -FLAGS
1266
1267 +FLAGS.SILENT
1268
1269 -FLAGS.SILENT
1270
1271 Note that the optimization described in this section can't be
1272 performed in case of a conditional STORE FLAGS (without "+" or "-")
1273 operation.
1274
1275 Let's use the following example. The client has issued:
1276
1277 C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
1278 +FLAGS.SILENT ($Processed)
1279
1280 When the server receives the command and parses it successfully, it
1281 iterates through the message set and tries to execute the conditional
1282 STORE command for each message.
1283
1284
1285
1286
1287
1288
1289
1290Melnikov & Cridland Standards Track [Page 23]
1291
1292RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1293
1294
1295 Each server internally works as a client, i.e., it has to cache the
1296 current state of all IMAP flags as it is known to the client. In
1297 order to report flag changes to the client, the server compares the
1298 cached values with the values in its database for IMAP flags.
1299
1300 Imagine that another client has changed the state of a flag \Deleted
1301 on the message 101 and that the change updated the mod-sequence for
1302 the message. The server knows that the mod-sequence for the mailbox
1303 has changed; however, it also knows that:
1304
1305 a. the client is not interested in the \Deleted flag, as it hasn't
1306 included it in the +FLAGS.SILENT operation and
1307
1308 b. the state of the flag $Processed hasn't changed (the server can
1309 determine this by comparing the cached flag state with the state
1310 of the flag in the database).
1311
1312 Therefore, the server doesn't have to report MODIFIED to the client.
1313 Instead, the server may set the $Processed flag, update the mod-
1314 sequence for the message 101 once again, and send an untagged FETCH
1315 response with a new mod-sequence and flags:
1316
1317 S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed \Deleted
1318 \Answered))
1319
1320 See also Section 3.1.11 for additional quality-of-implementation
1321 issues.
1322
13233.2. QRESYNC Extension ../imapserver/server.go:155
1324
1325 All protocol changes and requirements specified for the CONDSTORE
1326 extension are also a part of the QRESYNC extension.
1327
1328 The QRESYNC extension puts additional requirements on a server
1329 implementing the CONDSTORE extension. Each mailbox that supports
1330 persistent storage of mod-sequences, i.e., for which the server would
1331 send a HIGHESTMODSEQ untagged OK response code on a successful
1332 SELECT/EXAMINE, MUST increment the per-mailbox mod-sequence when one
1333 or more messages are expunged due to EXPUNGE, UID EXPUNGE, CLOSE, or
1334 MOVE [RFC6851]; the server MUST associate the incremented mod- 9051:6744 ../imapserver/server.go:3635
1335 sequence with the UIDs of the expunged messages. Additionally, if
1336 the server also supports the IMAP METADATA extension [RFC5464], it
1337 MUST increment the per-mailbox mod-sequence when SETMETADATA
1338 successfully changes an annotation on the corresponding mailbox.
1339
1340 A server implementing QRESYNC MUST send untagged events to a client ../imapserver/server.go:2120
1341 in a way that the client doesn't lose any changes in case of
1342 connectivity loss. In particular, this means that if the server
1343
1344
1345
1346Melnikov & Cridland Standards Track [Page 24]
1347
1348RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1349
1350
1351 sends MODSEQ FETCH data items while EXPUNGE (or VANISHED) replies
1352 with lower mod-sequences being delayed, the server MUST send the
1353 HIGHESTMODSEQ response code with a lower value than the EXPUNGE's
1354 mod-sequence. See the example in Section 6.
1355
13563.2.1. Impact on CONDSTORE-only Clients
1357
1358 A client that supports CONDSTORE but not QRESYNC might resynchronize
1359 a mailbox and discover that its HIGHESTMODSEQ has increased from the
1360 value cached by the client. If the increase is only due to messages
1361 having been expunged since the client last synchronized, the client
1362 is likely to send a FETCH ... CHANGEDSINCE command that returns no
1363 data. Thus, a client that supports CONDSTORE but not QRESYNC might
1364 incur a penalty of an unneeded round trip when resynchronizing some
1365 mailboxes (those that have had messages expunged but no flag changes
1366 since the last synchronization).
1367
1368 This extra round trip is only incurred by clients that support
1369 CONDSTORE but not QRESYNC and only when a mailbox has had messages
1370 expunged but no flag changes to non-expunged messages. Since
1371 CONDSTORE is a relatively new extension, it is strongly encouraged
1372 that clients that support it also support QRESYNC.
1373
13743.2.2. Advertising Support for QRESYNC
1375
1376 The quick resync IMAP extension is present if an IMAP4 server returns
1377 "QRESYNC" as one of the supported capabilities to the CAPABILITY
1378 command.
1379
1380 For compatibility with clients that only support the CONDSTORE IMAP
1381 extension, servers SHOULD also advertise "CONDSTORE" in the
1382 CAPABILITY response.
1383
13843.2.3. Use of ENABLE
1385
1386 Servers supporting QRESYNC MUST implement and advertise support for
1387 the ENABLE [RFC5161] IMAP extension. Also, the presence of the
1388 "QRESYNC" capability implies support for the CONDSTORE IMAP extension
1389 even if the "CONDSTORE" capability isn't advertised. A server
1390 compliant with this specification is REQUIRED to support "ENABLE ../imapserver/condstore_test.go:410
1391 QRESYNC" and "ENABLE QRESYNC CONDSTORE" (which are "CONDSTORE ../imapserver/server.go:1885
1392 enabling commands", see Section 3.1, and have identical results).
1393 Note that the order of parameters is not significant, but there is no
1394 requirement for a compliant server to support "ENABLE CONDSTORE" by
1395 itself. The "ENABLE QRESYNC"/"ENABLE QRESYNC CONDSTORE" command also
1396 tells the server that it MUST start sending VANISHED responses (see
1397
1398
1399
1400
1401
1402Melnikov & Cridland Standards Track [Page 25]
1403
1404RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1405
1406
1407 Section 3.2.10) instead of EXPUNGE responses for all mailboxes for
1408 which the server doesn't return the NOMODSEQ response code. This
1409 change remains in effect until the connection is closed.
1410
1411 A client making use of QRESYNC MUST issue "ENABLE QRESYNC" once it is
1412 authenticated. A server MUST respond with a tagged BAD response if
1413 the QRESYNC parameter to the SELECT/EXAMINE command or the VANISHED
1414 UID FETCH modifier is specified and the client hasn't issued "ENABLE
1415 QRESYNC", or the server has not positively responded (in the current
1416 connection) to that command with the untagged ENABLED response
1417 containing QRESYNC.
1418
14193.2.4. Additional Requirements on QRESYNC Servers
1420
1421 Once a CONDSTORE enabling command is issued by the client, the server ../imapserver/fetch.go:368
1422 MUST automatically include both UID and mod-sequence data in all
1423 subsequent untagged FETCH responses (until the connection is closed),
1424 whether they were caused by a regular STORE/UID STORE, a STORE/UID
1425 STORE with an UNCHANGEDSINCE modifier, a FETCH/UID FETCH that
1426 implicitly set the \Seen flag, or an external agent. Note that this 7162:877 7162:388 7162:909 ../imapserver/fetch.go:377
1427 rule doesn't affect untagged FETCH responses caused by a FETCH ../imapserver/condstore_test.go:180
1428 command that doesn't include UID and/or a MODSEQ FETCH data item (and
1429 doesn't implicitly set the \Seen flag) or UID FETCH without the
1430 MODSEQ FETCH data item.
1431
14323.2.5. QRESYNC Parameter to SELECT/EXAMINE 9051:1754 3501:1743 7162:1146 ../imapserver/server.go:1935
1433
1434 The Quick Resynchronization parameter to SELECT/EXAMINE commands has
1435 four arguments:
1436
1437 o the last known UIDVALIDITY,
1438
1439 o the last known modification sequence,
1440
1441 o the optional set of known UIDs, and
1442
1443 o an optional parenthesized list of known sequence ranges and their
1444 corresponding UIDs.
1445
1446 A server MUST respond with a tagged BAD response if the Quick ../imapserver/condstore_test.go:554 ../imapserver/server.go:1966
1447 Resynchronization parameter to the SELECT/EXAMINE command is
1448 specified and the client hasn't issued "ENABLE QRESYNC" in the
1449 current connection, or the server has not positively responded to
1450 that command with the untagged ENABLED response containing QRESYNC.
1451
1452 Before opening the specified mailbox, the server verifies all
1453 arguments for syntactic validity. If any parameter is not
1454 syntactically valid, the server returns the tagged BAD response, and
1455
1456
1457
1458Melnikov & Cridland Standards Track [Page 26]
1459
1460RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1461
1462
1463 the mailbox remains unselected. Once the check is done, the server
1464 opens the mailbox as if no SELECT/EXAMINE parameters are specified
1465 (this is subject to the processing of other parameters as defined in
1466 other extensions). In particular, this means that the server MUST
1467 send all untagged responses as specified in Sections 6.3.1 and 6.3.2
1468 of [RFC3501].
1469
1470 After that, the server checks the UIDVALIDITY value provided by the
1471 client. If the provided UIDVALIDITY doesn't match the UIDVALIDITY
1472 for the mailbox being opened, then the server MUST ignore the
1473 remaining parameters and behave as if no dynamic message data
1474 changed. The client can discover this situation by comparing the
1475 UIDVALIDITY value returned by the server. This behavior allows the
1476 client not to synchronize the mailbox or decide on the best
1477 synchronization strategy.
1478
1479 Example: Attempting to resynchronize INBOX, but the provided 9051:1831 3501:1826 7162:1159 ../imapserver/server.go:1937
1480 UIDVALIDITY parameter doesn't match the current UIDVALIDITY
1481 value.
1482
1483 C: A02 SELECT INBOX (QRESYNC (67890007 20050715194045000
1484 41,43:211,214:541))
1485 S: * 464 EXISTS
1486 S: * 3 RECENT
1487 S: * OK [UIDVALIDITY 3857529045] UIDVALIDITY
1488 S: * OK [UIDNEXT 550] Predicted next UID
1489 S: * OK [HIGHESTMODSEQ 90060128194045007] Highest mailbox
1490 mod-sequence
1491 S: * OK [UNSEEN 12] Message 12 is first unseen
1492 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
1493 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft
1494 \Deleted \Seen \*)] Permanent flags
1495 S: A02 OK [READ-WRITE] Sorry, UIDVALIDITY mismatch
1496
1497 Remaining parameters are described in the following subsections.
1498
14993.2.5.1. Modification Sequence and UID Parameters
1500
1501 A server that doesn't support the persistent storage of mod-sequences
1502 for the mailbox MUST send an OK untagged response including the
1503 NOMODSEQ response code with every successful SELECT or EXAMINE
1504 command (see Section 3.1.2.2). Such a server doesn't need to
1505 remember mod-sequences for expunged messages in the mailbox. It MUST
1506 ignore the remaining parameters and behave as if no dynamic message
1507 data changed.
1508
1509 If the provided UIDVALIDITY matches that of the selected mailbox, the ../imapserver/server.go:2073
1510 server then checks the last known modification sequence.
1511
1512
1513
1514Melnikov & Cridland Standards Track [Page 27]
1515
1516RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1517
1518
1519 The server sends the client any pending flag changes (using FETCH
1520 responses that MUST contain UIDs) and expunges those that have
1521 occurred in this mailbox since the provided modification sequence.
1522
1523 If the list of known UIDs was also provided, the server should only ../imapserver/condstore_test.go:642 ../imapserver/server.go:2158
1524 report flag changes and expunges for the specified messages. If the ../imapserver/server.go:2178
1525 client did not provide the list of UIDs, the server acts as if the
1526 client has specified "1:<maxuid>", where <maxuid> is the mailbox's
1527 UIDNEXT value minus 1. If the mailbox is empty and never had any
1528 messages in it, then lack of the list of UIDs is interpreted as an
1529 empty set of UIDs.
1530
1531 Thus, the client can process just these pending events and need not
1532 perform a full resynchronization. Without the message sequence
1533 number matching information, the result of this step is semantically
1534 equivalent to the client issuing:
1535 tag1 UID FETCH "known-uids" (FLAGS) (CHANGEDSINCE "mod-sequence-
1536 value" VANISHED)
1537
1538 In particular, this means that all requirements specified in
1539 Section 3.2.6 apply.
1540
1541 Example:
1542
1543 C: A03 SELECT INBOX (QRESYNC (67890007
1544 90060115194045000 41:211,214:541))
1545 S: * OK [CLOSED]
1546 S: * 100 EXISTS
1547 S: * 11 RECENT
1548 S: * OK [UIDVALIDITY 67890007] UIDVALIDITY
1549 S: * OK [UIDNEXT 600] Predicted next UID
1550 S: * OK [HIGHESTMODSEQ 90060115205545359] Highest
1551 mailbox mod-sequence
1552 S: * OK [UNSEEN 7] There are some unseen
1553 messages in the mailbox
1554 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
1555 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft
1556 \Deleted \Seen \*)] Permanent flags
1557 S: * VANISHED (EARLIER) 41,43:116,118,120:211,214:540
1558 S: * 49 FETCH (UID 117 FLAGS (\Seen \Answered) MODSEQ
1559 (90060115194045001))
1560 S: * 50 FETCH (UID 119 FLAGS (\Draft $MDNSent) MODSEQ
1561 (90060115194045308))
1562 S: * 51 FETCH (UID 541 FLAGS (\Seen $Forwarded) MODSEQ
1563 (90060115194045001))
1564 S: A03 OK [READ-WRITE] mailbox selected
1565
1566
1567
1568
1569
1570Melnikov & Cridland Standards Track [Page 28]
1571
1572RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1573
1574
1575 In the above example, flag information for UID 42 is not returned,
1576 presumably because its flags haven't changed since the MODSEQ
1577 90060115194045000.
1578
15793.2.5.2. Message Sequence Match Data ../imapserver/condstore_test.go:658 ../imapserver/server.go:2084
1580
1581 A client MAY provide a parenthesized list of a message sequence set
1582 and the corresponding UID sets. Both MUST be provided in ascending
1583 order. The server uses this data to restrict the range for which it
1584 provides expunged message information.
1585
1586 Conceptually, the client provides a small sample of sequence numbers
1587 for which it knows the corresponding UIDs. The server then compares
1588 each sequence number and UID pair the client provides with the
1589 current state of the mailbox. If a pair matches, then the client
1590 knows of any expunges up to, and including, the message; thus, it
1591 will not include that range in the VANISHED response, even if the
1592 "mod-sequence-value" provided by the client is too old for the server
1593 to have data of when those messages were expunged.
1594
1595 Thus, if the Nth message number in the first set in the list is 4,
1596 and the Nth UID in the second set in the list is 8, and the mailbox's
1597 fourth message has UID 8, then no UIDs equal to or less than 8 are
1598 present in the VANISHED response. If the (N+1)th message number is
1599 12, and the (N+1)th UID is 24, and the (N+1)th message in the mailbox
1600 has UID 25, then the lowest UID included in the VANISHED response
1601 would be 9.
1602
1603 In the following two examples, the server is unable to remember
1604 expunges at all, and only UIDs with messages divisible by three are
1605 present in the mailbox. In the first example, the client does not
1606 use the fourth parameter; in the second, it provides it. This
1607 example is somewhat extreme, but it shows that judicious usage of the
1608 sequence match data can save a substantial amount of bandwidth.
1609
1610 Example:
1611
1612 C: A04 SELECT INBOX (QRESYNC (67890007
1613 90060115194045000 1:29997))
1614 S: * 10003 EXISTS
1615 S: * 4 RECENT
1616 S: * OK [UIDVALIDITY 67890007] UIDVALIDITY
1617 S: * OK [UIDNEXT 30013] Predicted next UID
1618 S: * OK [HIGHESTMODSEQ 90060115205545359] Highest mailbox
1619 mod-sequence
1620 S: * OK [UNSEEN 7] There are some unseen messages in the mailbox
1621 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
1622
1623
1624
1625
1626Melnikov & Cridland Standards Track [Page 29]
1627
1628RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1629
1630
1631 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft
1632 \Deleted \Seen \*)] Permanent flags
1633 S: * VANISHED (EARLIER) 1:2,4:5,7:8,10:11,13:14,[...],
1634 29668:29669,29671:29996
1635 S: * 1 FETCH (UID 3 FLAGS (\Seen \Answered $Important) MODSEQ
1636 (90060115194045001))
1637 S: ...
1638 S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ
1639 (90060115194045027))
1640 S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ
1641 (90060115194045028))
1642 S: ...
1643 S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ
1644 (90060115194045031))
1645 S: A04 OK [READ-WRITE] mailbox selected
1646
1647 Example:
1648
1649 C: B04 SELECT INBOX (QRESYNC (67890007
1650 90060115194045000 1:29997 (5000,7500,9000,9990:9999 15000,
1651 22500,27000,29970,29973,29976,29979,29982,29985,29988,29991,
1652 29994,29997)))
1653 S: * 10003 EXISTS
1654 S: * 4 RECENT
1655 S: * OK [UIDVALIDITY 67890007] UIDVALIDITY
1656 S: * OK [UIDNEXT 30013] Predicted next UID
1657 S: * OK [HIGHESTMODSEQ 90060115205545359] Highest mailbox mod-
1658 sequence
1659 S: * OK [UNSEEN 7] There are some unseen messages in the mailbox
1660 S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
1661 S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft
1662 \Deleted \Seen \*)] Permanent flags
1663 S: * 1 FETCH (UID 3 FLAGS (\Seen \Answered $Important) MODSEQ
1664 (90060115194045001))
1665 S: ...
1666 S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ
1667 (90060115194045027))
1668 S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ
1669 (90060115194045028))
1670 S: ...
1671 S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ
1672 (90060115194045031))
1673 S: B04 OK [READ-WRITE] mailbox selected
1674
1675
1676
1677
1678
1679
1680
1681
1682Melnikov & Cridland Standards Track [Page 30]
1683
1684RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1685
1686
16873.2.6. VANISHED UID FETCH Modifier
1688
1689 [RFC4466] has extended the syntax of the FETCH and UID FETCH commands
1690 to include an optional FETCH modifier. This document defines a new
1691 UID FETCH modifier: VANISHED.
1692
1693 Note that the VANISHED UID FETCH modifier is NOT allowed with a FETCH ../imapserver/condstore_test.go:524 ../imapserver/fetch.go:91
1694 command. The server MUST return a tagged BAD response if this
1695 response is specified as a modifier to the FETCH command.
1696
1697 A server MUST respond with a tagged BAD response if the VANISHED UID ../imapserver/condstore_test.go:530
1698 FETCH modifier is specified and the client hasn't issued "ENABLE
1699 QRESYNC" in the current connection.
1700
1701 The VANISHED UID FETCH modifier MUST only be specified together with ../imapserver/condstore_test.go:527 ../imapserver/fetch.go:121
1702 the CHANGEDSINCE UID FETCH modifier. If the VANISHED UID FETCH
1703 modifier is used without the CHANGEDSINCE UID FETCH modifier, the
1704 server MUST respond with a tagged BAD response.
1705
1706 The VANISHED UID FETCH modifier instructs the server to report those
1707 messages from the UID set parameter that have been expunged and whose
1708 associated mod-sequence is larger than the specified mod-sequence.
1709 That is, the client requests to be informed of messages from the
1710 specified set that were expunged since the specified mod-sequence.
1711 Note that the mod-sequence(s) associated with these messages was
1712 updated when the messages were expunged (as described above). The
1713 expunged messages are reported using the VANISHED (EARLIER) response
1714 as described in Section 3.2.10.1. Any VANISHED (EARLIER) responses ../imapserver/fetch.go:220
1715 MUST be returned before any FETCH responses, otherwise the client
1716 might get confused about how message numbers map to UIDs.
1717
1718 Note: A server that receives a mod-sequence smaller than <minmodseq>, ../imapserver/fetch.go:178
1719 where <minmodseq> is the value of the smallest expunged mod-sequence
1720 it remembers minus one, MUST behave as if it was requested to report
1721 all expunged messages from the provided UID set parameter.
1722
1723 Example 1: Without the VANISHED UID FETCH modifier, a CONDSTORE-aware
1724 client needs to issue separate commands to learn of flag changes and
1725 expunged messages since the last synchronization:
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738Melnikov & Cridland Standards Track [Page 31]
1739
1740RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1741
1742
1743 C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345)
1744 S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen))
1745 S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted))
1746 S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk
1747 $AutoJunk $MDNSent))
1748 S: s100 OK FETCH completed
1749 C: s101 UID SEARCH 300:500
1750 S: * SEARCH 404 406 407 408 410 412
1751 S: s101 OK search completed
1752
1753 Where 300 and 500 are the lowest and highest UIDs from the client's
1754 cache. The second SEARCH response tells the client that the messages
1755 with UIDs 407, 410, and 412 are still present, but their flags
1756 haven't changed since the specified modification sequence.
1757
1758 Using the VANISHED UID FETCH modifier, it is sufficient to issue only
1759 a single command:
1760
1761 C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345
1762 VANISHED)
1763 S: * VANISHED (EARLIER) 300:310,405,411
1764 S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen))
1765 S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted))
1766 S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk
1767 $AutoJunk $MDNSent))
1768 S: s100 OK FETCH completed
1769
17703.2.7. EXPUNGE Command 9051:3687 3501:2695 ../imapserver/server.go:3141
1771
1772 Arguments: none
1773
1774 Responses: untagged responses: EXPUNGE or VANISHED
1775
1776 Result: OK - expunge completed
1777 NO - expunge failure: can't expunge (e.g., permission denied)
1778 BAD - command unknown or arguments invalid
1779
1780 This section updates the definition of the EXPUNGE command described
1781 in Section 6.4.3 of [RFC3501].
1782
1783 The EXPUNGE command permanently removes all messages that have the
1784 \Deleted flag set from the currently selected mailbox. Before
1785 returning an OK to the client, those messages that are removed are
1786 reported using a VANISHED response or EXPUNGE responses.
1787
1788 If the server is capable of storing modification sequences for the
1789 selected mailbox, it MUST increment the per-mailbox mod-sequence if
1790 at least one message was permanently removed due to the execution of
1791
1792
1793
1794Melnikov & Cridland Standards Track [Page 32]
1795
1796RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1797
1798
1799 the EXPUNGE command. For each permanently removed message, the
1800 server MUST remember the incremented mod-sequence and corresponding
1801 UID. If at least one message got expunged and QRESYNC was enabled,
1802 the server MUST send the updated per-mailbox modification sequence
1803 using the HIGHESTMODSEQ response code (see Section 3.1.2.1) in the
1804 tagged OK response.
1805
1806 Example: C: A202 EXPUNGE
1807 S: * 3 EXPUNGE
1808 S: * 3 EXPUNGE
1809 S: * 5 EXPUNGE
1810 S: * 8 EXPUNGE
1811 S: A202 OK [HIGHESTMODSEQ 20010715194045319] expunged
1812
1813 Note: In this example, the client hasn't enabled QRESYNC, so the
1814 server is still using untagged EXPUNGE responses. Note that the
1815 presence of the HIGHESTMODSEQ response code is optional in this case.
1816 If the selected mailbox returned NOMODSEQ, the HIGHESTMODSEQ response
1817 code will be absent. In this example, messages 3, 4, 7, and 11 had
1818 the \Deleted flag set. The first "* 3 EXPUNGE" reports message #3 as
1819 expunged. The second "* 3 EXPUNGE" reports message #4 as expunged
1820 (the message number was decremented due to the previous EXPUNGE
1821 response). See the description of the EXPUNGE response in [RFC3501]
1822 for further explanation.
1823
1824 Once the client enables QRESYNC, the server will always send VANISHED
1825 responses instead of EXPUNGE responses for mailboxes that support the
1826 storing of modification sequences, so the previous example might look
1827 like this:
1828
1829 Example: C: B202 EXPUNGE
1830 S: * VANISHED 405,407,410,425
1831 S: B202 OK [HIGHESTMODSEQ 20010715194045319] expunged
1832
1833 Here, messages with message numbers 3, 4, 7, and 11 have respective
1834 UIDs 405, 407, 410, and 425.
1835
18363.2.8. CLOSE Command 9051:3636 3501:2652 ../imapserver/server.go:2991
1837
1838 Arguments: none
1839
1840 Responses: no specific responses for this command
1841
1842 Result: OK - close completed, now in authenticated state
1843 BAD - command unknown or arguments invalid
1844
1845 This section updates the definition of the CLOSE command described in
1846 Section 6.4.2 of [RFC3501].
1847
1848
1849
1850Melnikov & Cridland Standards Track [Page 33]
1851
1852RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1853
1854
1855 The CLOSE command permanently removes all messages that have the
1856 \Deleted flag set from the currently selected mailbox and returns to
1857 the authenticated state from the selected state. No untagged EXPUNGE
1858 (or VANISHED) responses are sent.
1859
1860 If the server is capable of storing modification sequences for the
1861 selected mailbox, it MUST increment the per-mailbox mod-sequence if
1862 at least one message was permanently removed due to the execution of
1863 the CLOSE command. For each permanently removed message, the server
1864 MUST remember the incremented mod-sequence and corresponding UID.
1865 The server MUST NOT send the updated per-mailbox modification
1866 sequence using the HIGHESTMODSEQ response code (see Section 3.1.2.1)
1867 in the tagged OK response, as this might cause loss of
1868 synchronization on the client.
1869
1870 Example: C: A202 CLOSE
1871 S: A202 OK done
1872
18733.2.9. UID EXPUNGE Command 9051:4775 4315:75 ../imapserver/server.go:3158
1874
1875 Arguments: message set
1876
1877 Responses: untagged responses: EXPUNGE or VANISHED
1878
1879 Result: OK - expunge completed
1880 NO - expunge failure: can't expunge (e.g., permission denied)
1881 BAD - command unknown or arguments invalid
1882
1883 This section updates the definition of the UID EXPUNGE command
1884 described in Section 2.1 of [UIDPLUS], in the presence of QRESYNC.
1885 Servers that implement both [UIDPLUS] and QRESYNC extensions must
1886 implement UID EXPUNGE as described in this section.
1887
1888 The UID EXPUNGE command permanently removes from the currently
1889 selected mailbox all messages that have both the \Deleted flag set
1890 and a UID that is included in the specified message set. If a
1891 message either does not have the \Deleted flag set or has a UID that
1892 is not included in the specified message set, it is not affected.
1893
1894 This command is particularly useful for disconnected mode clients.
1895 By using UID EXPUNGE instead of EXPUNGE when resynchronizing with the
1896 server, the client can avoid inadvertently removing any messages that
1897 have been marked as \Deleted by other clients between the time that
1898 the client was last connected and the time the client resynchronizes.
1899
1900 Before returning an OK to the client, those messages that are removed
1901 are reported using a VANISHED response or EXPUNGE responses.
1902
1903
1904
1905
1906Melnikov & Cridland Standards Track [Page 34]
1907
1908RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1909
1910
1911 If the server is capable of storing modification sequences for the
1912 selected mailbox, it MUST increment the per-mailbox mod-sequence if
1913 at least one message was permanently removed due to the execution of
1914 the UID EXPUNGE command. For each permanently removed message, the
1915 server MUST remember the incremented mod-sequence and corresponding
1916 UID. If at least one message got expunged and QRESYNC was enabled,
1917 the server MUST send the updated per-mailbox modification sequence
1918 using the HIGHESTMODSEQ response code (see Section 3.1.2.1) in the
1919 tagged OK response.
1920
1921 Example: C: . UID EXPUNGE 3000:3002
1922 S: * 3 EXPUNGE
1923 S: * 3 EXPUNGE
1924 S: * 3 EXPUNGE
1925 S: . OK [HIGHESTMODSEQ 20010715194045319] Ok
1926
1927 Note: In this example, the client hasn't enabled QRESYNC, so the
1928 server is still using untagged EXPUNGE responses instead of VANISHED
1929 responses. Note that the presence of the HIGHESTMODSEQ response code
1930 is optional. If the selected mailbox returned NOMODSEQ, the
1931 HIGHESTMODSEQ response code will be absent. In this example, at
1932 least messages with message numbers 3, 4, and 5 (UIDs 3000 to 3002)
1933 had the \Deleted flag set. The first "* 3 EXPUNGE" reports message
1934 #3 as expunged. The second "* 3 EXPUNGE" reports message #4 as
1935 expunged (the message number was decremented due to the previous
1936 EXPUNGE response). See the description of the EXPUNGE response in
1937 [RFC3501] for further explanation.
1938
19393.2.10. VANISHED Response
1940
1941 The VANISHED response reports that the specified UIDs have been
1942 permanently removed from the mailbox. This response is similar to
1943 the EXPUNGE response [RFC3501]; however, it can return information
1944 about multiple messages, and it returns UIDs instead of message
1945 numbers. The first benefit saves bandwidth, while the second is more
1946 convenient for clients that only use UIDs to access the IMAP server.
1947
1948 The VANISHED response has the same restrictions on when it can be
1949 sent as does the EXPUNGE response (see below). Once a client has
1950 issued "ENABLE QRESYNC" (and the server has positively responded to
1951 that command with the untagged ENABLED response containing QRESYNC),
1952 the server MUST use the VANISHED response without the EARLIER tag
1953 instead of the EXPUNGE response for all mailboxes that don't return
1954 NOMODSEQ when selected. The server continues using VANISHED in lieu
1955 of EXPUNGE for the duration of the connection. In particular, this
1956 affects the EXPUNGE [RFC3501] and UID EXPUNGE [UIDPLUS] commands, as
1957 well as messages expunged in other connections. Such a VANISHED
1958 response MUST NOT contain the EARLIER tag.
1959
1960
1961
1962Melnikov & Cridland Standards Track [Page 35]
1963
1964RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
1965
1966
1967 The VANISHED response has two forms. The first form contains the
1968 EARLIER tag, which signifies that the response was caused by a UID
1969 FETCH (VANISHED) or a SELECT/EXAMINE (QRESYNC) command. The second
1970 form doesn't contain the EARLIER tag and is used for announcing
1971 message removals within an already selected mailbox.
1972
1973 Because clients handle the two different forms of the VANISHED
1974 response differently, servers MUST NOT combine them. Messages are
1975 reported in VANISHED responses with or without the EARLIER tag, as
1976 appropriate to the cause, and, if necessary, two VANISHED responses
1977 are sent (one with EARLIER and one without).
1978
19793.2.10.1. VANISHED (EARLIER) Response
1980
1981 Contents: an EARLIER tag
1982
1983 list of UIDs
1984
1985 The VANISHED (EARLIER) response is caused by a UID FETCH (VANISHED) ../imapserver/fetch.go:223 ../imapserver/server.go:2205
1986 or a SELECT/EXAMINE (QRESYNC) command. This response is sent if the
1987 UID set parameter to the UID FETCH (VANISHED) command includes UIDs
1988 of messages that are no longer in the mailbox. When the client sees
1989 a VANISHED EARLIER response, it MUST NOT decrement message sequence
1990 numbers for each successive message in the mailbox.
1991
19923.2.10.2. VANISHED Response without the (EARLIER) Tag
1993
1994 Contents: list of UIDs
1995
1996 Once a client has issued "ENABLE QRESYNC" (and the server has
1997 positively responded to that command with the untagged ENABLED
1998 response containing QRESYNC), the server MUST use the VANISHED
1999 response without the EARLIER tag instead of the EXPUNGE response for
2000 all mailboxes that don't return NOMODSEQ when selected. The server
2001 continues using VANISHED in lieu of EXPUNGE for the duration of the
2002 connection. In particular, this affects the EXPUNGE [RFC3501] and
2003 UID EXPUNGE [UIDPLUS] commands, as well as messages expunged in other
2004 connections. Such a VANISHED response MUST NOT contain the EARLIER ../imapserver/server.go:1299 ../imapserver/server.go:3201 ../imapserver/server.go:3628
2005 tag.
2006
2007 Unlike VANISHED (EARLIER), this response also decrements the number
2008 of messages in the mailbox and adjusts the message sequence numbers
2009 for the messages remaining in the mailbox to account for the expunged
2010 messages. Because of this housekeeping, it is not necessary for the
2011 server to send an EXISTS response to report the new message count.
2012 See the example at the end of this section.
2013
2014
2015
2016
2017
2018Melnikov & Cridland Standards Track [Page 36]
2019
2020RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2021
2022
2023 A VANISHED response without the EARLIER tag MUST refer only to
2024 messages that are visible to the client in the current session at the
2025 time the VANISHED response is sent. That is, servers MUST NOT send
2026 UIDs for previously expunged messages or messages that were not
2027 announced to the client via EXISTS. This means that each UID listed
2028 in a VANISHED response results in the client decrementing the message
2029 count by one. This is required to prevent a possible race condition
2030 where new arrivals for which the UID is not yet known by the client
2031 are immediately expunged.
2032
2033 A VANISHED response MUST NOT be sent when no command is in progress, 9051:5862 ../imapserver/server.go:556
2034 nor while responding to a FETCH, STORE, or SEARCH command. This rule
2035 is necessary to prevent a loss of synchronization of message sequence
2036 numbers between the client and server. A command is not "in
2037 progress" until the complete command has been received; in
2038 particular, a command is not "in progress" during the negotiation of
2039 command continuation.
2040
2041 Note: UID FETCH, UID STORE, and UID SEARCH are different commands
2042 from FETCH, STORE, and SEARCH. A VANISHED response MAY be sent
2043 during a UID command. However, the VANISHED response MUST NOT be
2044 sent during a UID SEARCH command that contains message numbers in the
2045 search criteria.
2046
2047 The update from the VANISHED response MUST be recorded by the client.
2048
2049 Example: Let's assume that there is the following mapping between
2050 message numbers and UIDs in the currently selected mailbox (here "D"
2051 marks messages with the \Deleted flag set, and "x" represents UIDs,
2052 which are not relevant for the example):
2053
2054 Message numbers: 1 2 3 4 5 6 7 8 9 10 11
2055 UIDs: x 504 505 507 508 x 510 x x x 625
2056 \Deleted messages: D D D D
2057
2058 In the presence of the extension defined in this document:
2059
2060 C: A202 EXPUNGE
2061 S: * VANISHED 505,507,510,625
2062 S: A202 OK EXPUNGE completed
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074Melnikov & Cridland Standards Track [Page 37]
2075
2076RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2077
2078
2079 Without the QRESYNC extension, the same example might look like:
2080
2081 C: A202 EXPUNGE
2082 S: * 3 EXPUNGE
2083 S: * 3 EXPUNGE
2084 S: * 5 EXPUNGE
2085 S: * 8 EXPUNGE
2086 S: A202 OK EXPUNGE completed
2087
2088 (Continuing from the previous example.) If subsequently messages
2089 with UIDs 504 and 508 got marked as \Deleted:
2090
2091 C: A210 EXPUNGE
2092 S: * VANISHED 504,508
2093 S: A210 OK EXPUNGE completed
2094
2095 For Example, the last VANISHED response only contains UIDs of
2096 messages expunged since the previous VANISHED response.
2097
2098 To illustrate the difference between VANISHED and VANISHED (EARLIER),
2099 suppose the mailbox contains UIDs 2 and 4. Any of the following
2100 responses would constitute a broken server implementation:
2101
2102 S: * VANISHED 1
2103 S: * VANISHED 3
2104 S: * VANISHED 5
2105
2106 However, any of these UIDs can easily be referenced by the VANISHED
2107 (EARLIER) response.
2108
21093.2.11. CLOSED Response Code
2110
2111 The CLOSED response code has no parameters. A server implementing 9051:1812 ../imapserver/server.go:2002
2112 the extension defined in this document MUST return the CLOSED
2113 response code when the currently selected mailbox is closed
2114 implicitly using the SELECT/EXAMINE command on another mailbox. The
2115 CLOSED response code serves as a boundary between responses for the
2116 previously opened mailbox (which was closed) and the newly selected
2117 mailbox; all responses before the CLOSED response code relate to the
2118 mailbox that was closed, and all subsequent responses relate to the
2119 newly opened mailbox.
2120
2121 A server that advertises "QRESYNC" or "CONDSTORE" in the capability
2122 string must return the CLOSED response code in this case, whether or
2123 not a CONDSTORE enabling command was issued.
2124
2125
2126
2127
2128
2129
2130Melnikov & Cridland Standards Track [Page 38]
2131
2132RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2133
2134
2135 There is no need to return the CLOSED response code on completion of
2136 the CLOSE or the UNSELECT [UNSELECT] command (or similar), whose
2137 purpose is to close the currently selected mailbox without opening a
2138 new one.
2139
21404. Long Command Lines (Update to RFC 2683)
2141
2142 While [RFC3501] doesn't specify a specific line-length limit, several
2143 server implementations chose to implement the recommended line-length
2144 limit suggested in Section 3.2.1.5 of [RFC2683] in order to protect
2145 from Denial-of-Service attacks. When the line-length limit is
2146 exceeded, such servers return a BAD response (as required by
2147 [RFC3501] in case of a syntactic error) and may even close the
2148 connection. Clients that support CONDSTORE/QRESYNC extensions can
2149 trigger this limit by sending a long UID sequence (previously
2150 returned by the server) in an extended SELECT or FETCH command.
2151
2152 This document updates recommended line-length limits specified in
2153 Section 3.2.1.5 of [RFC2683]. While the advice in the first
2154 paragraph of that section still applies (use compact message/UID set
2155 representations), the 1000-octet limit suggested in the second
2156 paragraph turns out to be quite problematic when the CONDSTORE and/or
2157 QRESYNC extension is used.
2158
2159 The updated recommendation is as follows: a client should limit the ../imapserver/server.go:471
2160 length of the command lines it generates to approximately 8192 octets
2161 (including all quoted strings but not including literals). If the
2162 client is unable to group things into ranges so that the command line
2163 is within that length, it should split the request into multiple
2164 commands. The client should use literals instead of long quoted
2165 strings in order to keep the command length down.
2166
21675. QRESYNC Server Implementation Considerations
2168
2169 This section describes a minimalist implementation, a moderate
2170 implementation, and an example of a full implementation.
2171
21725.1. Server Implementations That Don't Store Extra State
2173
2174 Strictly speaking, a server implementation that doesn't remember mod-
2175 sequences associated with expunged messages can be considered
2176 compliant with this specification. Such implementations return all
2177 expunged messages specified in the UID set of the UID FETCH
2178 (VANISHED) command every time, without paying attention to the
2179 specified CHANGEDSINCE mod-sequence. Such implementations are
2180 discouraged as they can end up returning VANISHED responses that are
2181 bigger than the result of a UID SEARCH command for the same UID set.
2182
2183
2184
2185
2186Melnikov & Cridland Standards Track [Page 39]
2187
2188RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2189
2190
2191 A client can substantially reduce the size of VANISHED responses by
2192 providing the server with message sequence match data (see
2193 Section 3.2.5.2). This is especially effective in the typical case
2194 where no messages have been expunged, or all expunges were toward the
2195 end of the mailbox.
2196
21975.2. Server Implementations Storing Minimal State
2198
2199 A server that stores the HIGHESTMODSEQ value at the time of the last
2200 EXPUNGE can omit the VANISHED response when a client provides a
2201 MODSEQ value that is equal to or higher than that HIGHESTMODSEQ value
2202 because there have been no messages expunged during the time period
2203 the client is concerned about.
2204
2205 A client providing message sequence match data can reduce the scope
2206 as above. In the case where there have been no expunges, the server
2207 can ignore this data.
2208
22095.3. Additional State Required on the Server
2210
2211 When compared to the CONDSTORE extension, QRESYNC requires servers to
2212 store an additional state associated with expunged messages. Note
2213 that implementations are not required to store this state in
2214 persistent storage; however, use of persistent storage is advisable.
2215
2216 One possible way to correctly implement QRESYNC is to store a queue
2217 of <UID set, mod-sequence> pairs. <UID set> can be represented as a
2218 sequence of <min UID, max UID> pairs.
2219
2220 When messages are expunged, one or more entries are added to the
2221 queue tail.
2222
2223 When the server receives a request to return messages expunged since
2224 a given mod-sequence, it will search the queue from the tail (i.e.,
2225 going from the highest expunged mod-sequence to the lowest) until it
2226 sees the first record with a mod-sequence less than or equal to the
2227 given mod-sequence or it reaches the head of the queue.
2228
2229 Note that indefinitely storing information about expunged messages
2230 can cause storage and related problems for an implementation. In the
2231 worst case, this could result in almost 64 GB of storage for each
2232 IMAP mailbox. For example, consider an implementation that stores
2233 <min UID, max UID, mod-sequence> triples for each range of messages
2234 expunged at the same time. Each triple requires 16 octets: 4 octets
2235 for each of the two UIDs and 8 octets for the mod-sequence. Assume
2236 that there is a mailbox containing a single message with a UID of
2237 2**32-1 (the maximum possible UID value), where messages had
2238 previously existed with UIDs starting at 1 and have been expunged one
2239
2240
2241
2242Melnikov & Cridland Standards Track [Page 40]
2243
2244RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2245
2246
2247 at a time. For this mailbox alone, storage is required for the
2248 triples <1, 1, modseq1>, <2, 2, modseq2>, ..., <2**32-2, 2**32-2,
2249 modseq4294967294>.
2250
2251 Hence, implementations are encouraged to adopt strategies to protect
2252 against such storage problems, such as limiting the size of the queue
2253 used to store mod-sequences for expunged messages and "expiring"
2254 older records when this limit is reached. When the selected
2255 implementation-specific queue limit is reached, the oldest record(s)
2256 is deleted from the queue (note that such records are located at the
2257 queue head). For all such "expired" records, the server needs to
2258 store a single mod-sequence, which is the highest mod-sequence for
2259 all "expired" expunged messages.
2260
2261 If the client provides the message sequence match data, this can
2262 heavily reduce the data cost of sending a complete set of missing
2263 UIDs; thus, it reduces the problems for clients if a server is unable
2264 to persist much of this queue. If the queue contains data back to
2265 the requested mod-sequence, this data can be ignored.
2266
2267 Also, note that if the UIDVALIDITY of the mailbox changes or if the
2268 mailbox is deleted, then any state associated with expunged messages
2269 doesn't need to be preserved and SHOULD be deleted.
2270
22716. Updated Synchronization Sequence
2272
2273 This section updates the description of optimized synchronization in
2274 Section 6.1 of [IMAP-DISC], in the presence of QRESYNC.
2275
2276 An advanced disconnected mail client SHOULD use the QRESYNC extension
2277 when it is supported by the server and SHOULD use CONDSTORE if it is
2278 supported and QRESYNC is not. The client uses the value from the
2279 HIGHESTMODSEQ OK response code received on the mailbox opening to
2280 determine if it needs to resynchronize. Once the synchronization is
2281 complete, it MUST cache the received value (unless the mailbox
2282 UIDVALIDITY value has changed; see below). The client MUST update
2283 its copy of the HIGHESTMODSEQ value whenever the server sends a
2284 subsequent HIGHESTMODSEQ OK response code.
2285
2286 After completing a full synchronization, the client MUST also take
2287 note of any unsolicited MODSEQ FETCH data items and HIGHESTMODSEQ
2288 response codes received from the server. Whenever the client
2289 receives a tagged response to a command, it checks the received
2290 unsolicited responses to calculate the new HIGHESTMODSEQ value. If
2291 the HIGHESTMODSEQ response code is received, the client MUST use it
2292 even if it has seen higher mod-sequences. Otherwise, the client
2293 calculates the highest value among all MODSEQ FETCH data items
2294
2295
2296
2297
2298Melnikov & Cridland Standards Track [Page 41]
2299
2300RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2301
2302
2303 received since the last tagged response. If this value is bigger
2304 than the client's copy of the HIGHESTMODSEQ value, then the client
2305 MUST use this value as its new HIGHESTMODSEQ value.
2306
2307 Example:
2308
2309 C: A150 STORE 1:2 (UNCHANGEDSINCE 96) +FLAGS.SILENT \Seen
2310 S: * 1 FETCH (UID 6 MODSEQ (103))
2311 S: * 2 FETCH (UID 7 MODSEQ (101))
2312 S: * OK [HIGHESTMODSEQ 99] VANISHED reply with MODSEQ 100 is delayed
2313 S: A150 OK [MODIFIED 3] done
2314
2315 C: A151 STORE 3 +FLAGS.SILENT \Seen
2316 S: * 3 FETCH (UID 8 MODSEQ (104))
2317 S: A151 OK [HIGHESTMODSEQ 99] Still delaying VANISHED
2318
2319 C: A152 NOOP
2320 S: * VANISHED 8
2321 S: A153 OK [HIGHESTMODSEQ 104] done
2322
2323 Note: It is not safe to update the client's copy of the HIGHESTMODSEQ ../imapserver/search.go:200
2324 value with a MODSEQ FETCH data item value as soon as it is received
2325 because servers are not required to send MODSEQ FETCH data items in
2326 increasing mod-sequence order. Some commands may also delay EXPUNGE
2327 (or VANISHED) replies with smaller mod-sequences. These can lead to
2328 the client missing some changes in case of connectivity loss.
2329
2330 When opening the mailbox for synchronization, the client uses the
2331 QRESYNC parameter to the SELECT/EXAMINE command. The QRESYNC
2332 parameter is followed by the UIDVALIDITY and mailbox HIGHESTMODSEQ
2333 values, as known to the client. It can be optionally followed by the
2334 set of UIDs, for example, if the client is only interested in partial
2335 synchronization of the mailbox. The client may also transmit a list
2336 containing its knowledge of message numbers.
2337
2338 If the SELECT/EXAMINE command is successful, the client compares
2339 UIDVALIDITY as described in step d-1 in Section 3 of the [IMAP-DISC].
2340 If the cached UIDVALIDITY value matches the one returned by the
2341 server and the server also returns the HIGHESTMODSEQ response code,
2342 then the server reports expunged messages and returns flag changes
2343 for all messages specified by the client in the UID set parameter (or
2344 for all messages in the mailbox, if the client omitted the UID set
2345 parameter). At this point, the client is synchronized, except for
2346 maybe the new messages.
2347
2348
2349
2350
2351
2352
2353
2354Melnikov & Cridland Standards Track [Page 42]
2355
2356RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2357
2358
2359 If upon a successful SELECT/EXAMINE (QRESYNC) command the client
2360 receives a NOMODSEQ OK untagged response (instead of the
2361 HIGHESTMODSEQ response code), it MUST remove the last known
2362 HIGHESTMODSEQ value from its cache and follow the more general
2363 instructions in Section 3 of the [IMAP-DISC].
2364
2365 At this point, the client is in sync with the server regarding old
2366 messages. This client can now fetch information about new messages
2367 (if requested by the user).
2368
2369 Step d ("Server-to-client synchronization") in Section 6.1 of
2370 [IMAP-DISC] in the presence of the QRESYNC & CONDSTORE extensions is
2371 amended as follows:
2372
2373 d) "Server-to-client synchronization" -- for each mailbox that
2374 requires synchronization, do the following:
2375
2376 1a) Check the mailbox UIDVALIDITY (see Section 4.1 of [IMAP-DISC] for
2377 more details) after issuing the SELECT/EXAMINE (QRESYNC) command.
2378
2379 If the UIDVALIDITY value returned by the server differs, the
2380 client MUST:
2381
2382 * empty the local cache of that mailbox;
2383
2384 * "forget" the cached HIGHESTMODSEQ value for the mailbox; and
2385
2386 * remove any pending "actions" that refer to UIDs in that
2387 mailbox. Note, this doesn't affect actions performed on
2388 client-generated fake UIDs (see Section 5 of the [IMAP-DISC]).
2389
2390 1b) This step is no longer required.
2391
2392 2) Fetch the current "descriptors".
2393
2394 I) Discover new messages.
2395
2396 3) Fetch the bodies of any "interesting" messages that the client
2397 doesn't already have.
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410Melnikov & Cridland Standards Track [Page 43]
2411
2412RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2413
2414
2415 Example: The UIDVALIDITY value is the same, but the HIGHESTMODSEQ
2416 value has changed on the server while the client was
2417 offline:
2418
2419 C: A142 SELECT INBOX (QRESYNC (3857529045 20010715194032001 1:198))
2420 S: * 172 EXISTS
2421 S: * 1 RECENT
2422 S: * OK [UNSEEN 12] Message 12 is first unseen
2423 S: * OK [UIDVALIDITY 3857529045] UIDs valid
2424 S: * OK [UIDNEXT 201] Predicted next UID
2425 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
2426 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
2427 S: * OK [HIGHESTMODSEQ 20010715194045007] Highest
2428 mailbox mod-sequence
2429 S: * VANISHED (EARLIER) 1:5,7:8,10:15
2430 S: * 2 FETCH (UID 6 MODSEQ (20010715205008000)
2431 FLAGS (\Deleted))
2432 S: * 5 FETCH (UID 9 MODSEQ (20010715195517000)
2433 FLAGS ($NoJunk $AutoJunk $MDNSent))
2434 ...
2435 S: A142 OK [READ-WRITE] SELECT completed
2436
24377. Formal Syntax
2438
2439 The following syntax specification uses the Augmented Backus-Naur
2440 Form (ABNF) notation as specified in [RFC5234].
2441
2442 Non-terminals referenced but not defined below are as defined by
2443 [RFC5234], [RFC3501], or [RFC4466].
2444
2445 Except as noted otherwise, all alphabetic characters are case-
2446 insensitive. The use of upper- or lower-case characters to define
2447 token strings is for editorial clarity only. Implementations MUST
2448 accept these strings in a case-insensitive fashion.
2449
2450 capability =/ "CONDSTORE" / "QRESYNC"
2451
2452 status-att =/ "HIGHESTMODSEQ" 9051:7056 3501:5047 7889:252 9208:696 ../imapserver/parse.go:439
2453 ;; Extends non-terminal defined in [RFC3501].
2454
2455 status-att-val =/ "HIGHESTMODSEQ" SP mod-sequence-valzer
2456 ;; Extends non-terminal defined in [RFC4466].
2457 ;; Value 0 denotes that the mailbox doesn't
2458 ;; support persistent mod-sequences
2459 ;; as described in Section 3.1.2.2.
2460
2461
2462
2463
2464
2465
2466Melnikov & Cridland Standards Track [Page 44]
2467
2468RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2469
2470
2471 store-modifier =/ "UNCHANGEDSINCE" SP mod-sequence-valzer 9051:7076 3501:5052 4466:691 ../imapserver/server.go:3648 ../imapserver/server.go:3654
2472 ;; Only a single "UNCHANGEDSINCE" may be
2473 ;; specified in a STORE operation.
2474
2475 fetch-modifier =/ chgsince-fetch-mod 9051:6553 3501:4748 4466:535 ../imapserver/fetch.go:75
2476 ;; Conforms to the generic "fetch-modifier"
2477 ;; syntax defined in [RFC4466].
2478
2479 chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value ../imapserver/fetch.go:85
2480 ;; CHANGEDSINCE FETCH modifier conforms to
2481 ;; the fetch-modifier syntax.
2482
2483 fetch-att =/ fetch-mod-sequence 9051:6557 3501:4751 ../imapserver/parse.go:579
2484 ;; Modifies original IMAP4 fetch-att.
2485
2486 fetch-mod-sequence = "MODSEQ"
2487
2488 fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")" ../imapclient/parse.go:689
2489
2490 msg-att-dynamic =/ fetch-mod-resp 9051:6742 3501:4864 9051:6749 3501:4869 ../imapserver/fetch.go:73 ../imapserver/server.go:3844
2491
2492 search-key =/ search-modsequence 9051:6923 3501:4957 ../imapserver/parse.go:783
2493 ;; Modifies original IMAP4 search-key.
2494 ;;
2495 ;; This change applies to all commands
2496 ;; referencing this non-terminal -- in
2497 ;; particular, SEARCH, SORT, and THREAD.
2498
2499 search-modsequence = "MODSEQ" [search-modseq-ext] SP 7162:1045 ../imapserver/parse.go:886
2500 mod-sequence-valzer
2501
2502 search-modseq-ext = SP entry-name SP entry-type-req
2503
2504 resp-text-code =/ "HIGHESTMODSEQ" SP mod-sequence-value /
2505 "NOMODSEQ" /
2506 "MODIFIED" SP sequence-set ../imapserver/server.go:3875
2507
2508 entry-name = entry-flag-name
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522Melnikov & Cridland Standards Track [Page 45]
2523
2524RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2525
2526
2527 entry-flag-name = DQUOTE "/flags/" attr-flag DQUOTE
2528 ;; Each system or user-defined flag <flag>
2529 ;; is mapped to "/flags/<flag>".
2530 ;;
2531 ;; <entry-flag-name> follows the escape rules
2532 ;; used by "quoted" string as described in
2533 ;; Section 4.3 of [RFC3501]; e.g., for the
2534 ;; flag \Seen, the corresponding <entry-name>
2535 ;; is "/flags/\\seen", and for the flag
2536 ;; $MDNSent, the corresponding <entry-name>
2537 ;; is "/flags/$mdnsent".
2538
2539 entry-type-resp = "priv" / "shared"
2540 ;; Metadata item type.
2541
2542 entry-type-req = entry-type-resp / "all"
2543 ;; Perform SEARCH operation on a private
2544 ;; metadata item, shared metadata item,
2545 ;; or both.
2546
2547 permsg-modsequence = mod-sequence-value
2548 ;; Per-message mod-sequence.
2549
2550 mod-sequence-value = 1*DIGIT
2551 ;; Positive unsigned 63-bit integer ../imapserver/fetch.go:106
2552 ;; (mod-sequence)
2553 ;; (1 <= n <= 9,223,372,036,854,775,807).
2554
2555 mod-sequence-valzer = "0" / mod-sequence-value
2556
2557 search-sort-mod-seq = "(" "MODSEQ" SP mod-sequence-value ")" ../imapclient/parse.go:431 ../imapserver/search.go:204
2558
2559 select-param =/ condstore-param 9051:7005 3501:4996 4466:652 7162:2598 ../imapserver/server.go:1939
2560 ;; Conforms to the generic "select-param"
2561 ;; non-terminal syntax defined in [RFC4466].
2562
2563 condstore-param = "CONDSTORE"
2564
2565 mailbox-data =/ "SEARCH" [1*(SP nz-number) SP
2566 search-sort-mod-seq]
2567
2568 sort-data = "SORT" [1*(SP nz-number) SP
2569 search-sort-mod-seq]
2570 ; Updates the SORT response from RFC 5256.
2571
2572
2573
2574
2575
2576
2577
2578Melnikov & Cridland Standards Track [Page 46]
2579
2580RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2581
2582
2583 attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" /
2584 "\\Seen" / "\\Draft" / attr-flag-keyword /
2585 attr-flag-extension
2586 ;; Does not include "\\Recent".
2587
2588 attr-flag-extension = "\\" atom
2589 ;; Future expansion. Client implementations
2590 ;; MUST accept flag-extension flags. Server
2591 ;; implementations MUST NOT generate
2592 ;; flag-extension flags, except as defined by
2593 ;; future standards or Standards Track
2594 ;; revisions of [RFC3501].
2595
2596 attr-flag-keyword = atom
2597
2598 select-param =/ "QRESYNC" SP "(" uidvalidity SP 9051:7005 3501:4996 4466:652 7162:2559 ../imapserver/server.go:1939 ../imapserver/server.go:1962
2599 mod-sequence-value [SP known-uids]
2600 [SP seq-match-data] ")"
2601 ;; Conforms to the generic select-param
2602 ;; syntax defined in [RFC4466].
2603
2604 seq-match-data = "(" known-sequence-set SP known-uid-set ")"
2605
2606 uidvalidity = nz-number ../imapserver/server.go:1971
2607
2608 known-uids = sequence-set ../imapserver/server.go:1977
2609 ;; Sequence of UIDs; "*" is not allowed.
2610
2611 known-sequence-set = sequence-set
2612 ;; Set of message numbers corresponding to
2613 ;; the UIDs in known-uid-set, in ascending order.
2614 ;; * is not allowed.
2615
2616 known-uid-set = sequence-set
2617 ;; Set of UIDs corresponding to the messages in
2618 ;; known-sequence-set, in ascending order.
2619 ;; * is not allowed.
2620
2621 message-data =/ expunged-resp
2622
2623 expunged-resp = "VANISHED" [SP "(EARLIER)"] SP known-uids ../imapclient/parse.go:481
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634Melnikov & Cridland Standards Track [Page 47]
2635
2636RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2637
2638
2639 rexpunges-fetch-mod = "VANISHED"
2640 ;; VANISHED UID FETCH modifier conforms
2641 ;; to the fetch-modifier syntax
2642 ;; defined in [RFC4466]. It is only
2643 ;; allowed in the UID FETCH command.
2644
2645 resp-text-code =/ "CLOSED"
2646
26478. Security Considerations
2648
2649 As always, it is important to thoroughly test clients and servers
2650 implementing QRESYNC, as it changes how the server reports expunged
2651 messages to the client.
2652
2653 It is believed that the CONDSTORE or the QRESYNC extensions don't
2654 raise any new security concerns that are not already discussed in
2655 [RFC3501]. However, the availability of CONDSTORE may make it
2656 possible for IMAP4 to be used in critical applications it could not
2657 be used for previously, making correct IMAP server implementation and
2658 operation even more important.
2659
26609. IANA Considerations
2661
2662 IMAP4 capabilities are registered by publishing a Standards Track or
2663 IESG-approved Experimental RFC. The registry is currently located
2664 at:
2665
2666 http://www.iana.org/assignments/imap-capabilities
2667
2668 This document defines the CONDSTORE and QRESYNC IMAP capabilities.
2669 IANA has updated references for both extensions to point to this
2670 document.
2671
267210. References
2673
267410.1. Normative References
2675
2676 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2677 Requirement Levels", BCP 14, RFC 2119, March 1997.
2678
2679 [RFC2683] Leiba, B., "IMAP4 Implementation Recommendations", RFC
2680 2683, September 1999.
2681
2682 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
2683 4rev1", RFC 3501, March 2003.
2684
2685 [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
2686 ABNF", RFC 4466, April 2006.
2687
2688
2689
2690Melnikov & Cridland Standards Track [Page 48]
2691
2692RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2693
2694
2695 [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE
2696 Extension", RFC 5161, March 2008.
2697
2698 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
2699 Specifications: ABNF", STD 68, RFC 5234, January 2008.
2700
2701 [RFC5256] Crispin, M. and K. Murchison, "Internet Message Access
2702 Protocol - SORT and THREAD Extensions", RFC 5256, June
2703 2008.
2704
2705 [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
2706 February 2009.
2707
2708 [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) -
2709 UIDPLUS extension", RFC 4315, December 2005.
2710
271110.2. Informative References
2712
2713 [IMAP-DISC]
2714 Melnikov, A., Ed., "Synchronization Operations For
2715 Disconnected Imap4 Clients", RFC 4549, June 2006.
2716
2717 [NTP] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network
2718 Time Protocol Version 4: Protocol and Algorithms
2719 Specification", RFC 5905, June 2010.
2720
2721 [RFC2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
2722 2180, July 1997.
2723
2724 [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
2725 RFC 4314, December 2005.
2726
2727 [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
2728 Command for Controlling What Kind of Information Is
2729 Returned", RFC 4731, November 2006.
2730
2731 [RFC5257] Daboo, C. and R. Gellens, "Internet Message Access
2732 Protocol - ANNOTATE Extension", RFC 5257, June 2008.
2733
2734 [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
2735 July 2008.
2736
2737 [RFC6851] Gulbrandsen, A. and N. Freed, "Internet Message Access
2738 Protocol (IMAP) - MOVE Extension", RFC 6851, January 2013.
2739
2740 [UNSELECT] Melnikov, A., "Internet Message Access Protocol (IMAP)
2741 UNSELECT command", RFC 3691, February 2004.
2742
2743
2744
2745
2746Melnikov & Cridland Standards Track [Page 49]
2747
2748RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2749
2750
2751Appendix A. Changes since RFC 4551
2752
2753 Changed mod-sequences to be unsigned 63-bit values (instead of
2754 unsigned 64-bit values).
2755
2756 Fixed the following errata, as posted on <http://www.rfc-editor.org>:
2757
2758 o Errata ID 3401 ("several typos in UNCHANGEDSINCE spelling")
2759 o Errata ID 3506 ("invalid ABNF for the MODIFIED response code")
2760 o Errata ID 3509 ("correction to an example")
2761
2762 Clarified that the returning of HIGHESTMODSEQ/NOMODSEQ response codes
2763 is only required once a CONDSTORE enabling command is issued.
2764
2765 Clarified that if multiple mod-sequences (for different metadata
2766 items) are associated with a message, then all of them affecting a
2767 particular STORE UNCHANGEDSINCE must be checked.
2768
2769 Updated references.
2770
2771 Made editorial corrections.
2772
2773Appendix B. Changes since RFC 5162
2774
2775 Changed mod-sequences to be unsigned 63-bit values (instead of
2776 unsigned 64-bit values).
2777
2778 Addressed the following errata, as posted on
2779 <http://www.rfc-editor.org>:
2780
2781 o Errata ID 1365 ("clarified that QRESYNC is only enabled when
2782 ENABLED QRESYNC is returned")
2783 o Errata ID 1807 ("unsolicited FETCH responses must include UID
2784 fetch response item")
2785 o Errata ID 1808 ("HIGHESTMODSEQ response code must not be returned
2786 for CLOSE")
2787 o Errata ID 1809 ("clarify how updated mailbox mod-sequence is
2788 calculated")
2789 o Errata ID 1810 ("server must send untagged events to client in a
2790 way that client doesn't lose any changes in case of connectivity
2791 loss")
2792 o Errata ID 3322 ("VANISHED responses must not reference non-
2793 existing UIDs")
2794
2795 Clarified that ENABLE QRESYNC CONDSTORE and ENABLE CONDSTORE QRESYNC
2796 are equivalent.
2797
2798
2799
2800
2801
2802Melnikov & Cridland Standards Track [Page 50]
2803
2804RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2805
2806
2807 Changed the requirement to return VANISHED from SHOULD to MUST as per
2808 the mailing list discussion. The only exception is for mailboxes
2809 that return the NOMODSEQ response code when they are selected.
2810
2811 Specified that IMAP SETMETADATA changes update per-mailbox
2812 HIGHESTMODSEQ.
2813
2814 Clarified that per-message annotations are also considered
2815 "metadata".
2816
2817 Fixed some examples to report data that match requirements specified
2818 in the document.
2819
2820 Clarified some text and made some requirements normative. Also,
2821 corrected a couple of SHOULDs to be MUSTs.
2822
2823 Updated references.
2824
2825 Made editorial corrections.
2826
2827Appendix C. Acknowledgements
2828
2829 Thank you to Steve Hole for co-editing RFC 4551.
2830
2831 In this revision of the document, the authors also acknowledge the
2832 feedback provided by Timo Sirainen, Jan Kundrat, Pete Maclean, Barry
2833 Leiba, Eliot Lear, Chris Newman, Claudio Allocchio, Michael Slusarz,
2834 Bron Gondwana, Arnt Gulbrandsen, David Black, Hoa V. DINH, and Nick
2835 Hudson.
2836
2837 Mark Crispin contributed to RFCs 4551 and 5162 that this document is
2838 replacing, and much of his contribution remains in this merged
2839 document.
2840
2841 See also the list of people who contributed to RFC 4551, which this
2842 document obsoletes.
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858Melnikov & Cridland Standards Track [Page 51]
2859
2860RFC 7162 IMAP CONDSTORE & QRESYNC May 2014
2861
2862
2863Authors' Addresses
2864
2865 Alexey Melnikov
2866 Isode Ltd
2867 5 Castle Business Village
2868 36 Station Road
2869 Hampton, Middlesex TW12 2BX
2870 UK
2871
2872 EMail: Alexey.Melnikov@isode.com
2873
2874
2875 Dave Cridland
2876 Surevine Ltd
2877 PO Box 1136
2878 Guildford, Surrey GU1 9ND
2879 UK
2880
2881 EMail: dave.cridland@surevine.com
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914Melnikov & Cridland Standards Track [Page 52]
2915
2916