IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization
obsoleted by
- rfc-7162 — IMAP Extensions: Quick Flag Changes Resynchronization (CONDSTORE) and Quick Mailbox Resynchronization (QRESYNC)
updates
- rfc-3501 — INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
Extracted elements (29)
Servers that store only a single mod-sequence per message (rather than per metadata item) can avoid spurious MODIFIED responses for +FLAGS/-FLAGS operations by checking whether the client's requested flag was actually changed by the competing STORE, and proceeding with the operation if only an unrelated flag changed.
The CONDSTORE parameter to SELECT/EXAMINE was introduced to avoid a race condition: metadata could be modified by another session after the server sent HIGHESTMODSEQ but before the client issued its first CONDSTORE-enabling command, causing the client to miss mod-sequence updates.
The system clock MUST NOT be used as a source of mod-sequence values because NTP or other time adjustments can cause the clock to go backwards, which would violate the requirement that each successive STORE on the same mailbox yields a strictly increasing mod-sequence.
Client implementers MUST NOT rely on the server SHOULD NOT behavior of leaving the mod-sequence unchanged for no-op flag operations (adding a flag already set, or removing one already absent). A client cannot distinguish between a server violating this recommendation and the case where another session toggled the flag.
Upon receipt of a MODIFIED response code, the client SHOULD issue a FETCH or NOOP to determine whether the watched metadata items actually changed; it is RECOMMENDED that servers send unsolicited FETCH responses to avoid this polling. If the items have not changed, the client SHOULD retry with the updated mod-sequence, allowing at least 2 retries.
A client becomes a CONDSTORE-aware client by issuing any CONDSTORE-enabling command (SELECT/EXAMINE with CONDSTORE, STATUS HIGHESTMODSEQ, FETCH or SEARCH with MODSEQ, FETCH with CHANGEDSINCE, or STORE with UNCHANGEDSINCE). The server MUST then include mod-sequence data in all subsequent unsolicited FETCH responses until the connection is closed.
After processing all messages in a STORE UNCHANGEDSINCE command, if any messages failed the UNCHANGEDSINCE test, the server MUST return a MODIFIED response code in the tagged response listing those message numbers (or UIDs for UID STORE).
An IMAP server supporting CONDSTORE MUST associate a positive unsigned 64-bit modification sequence (mod-sequence) with every IMAP message, and MUST guarantee that each STORE command on the same mailbox receives a different mod-sequence value. For any two successful STORE operations in the same session on the same mailbox, the mod-sequence of the second completed operation MUST be greater than that of the first.
If a client specifies a MODSEQ criterion and the server returns a non-empty SEARCH result, the server MUST append the highest mod-sequence of all returned messages at the end of the untagged SEARCH response: `* SEARCH <numbers> (MODSEQ <value>)`.
If a message appears multiple times in a STORE message set, the server MUST NOT fail the conditional STORE for a subsequent occurrence if the operation already completed successfully for an earlier occurrence of the same message.
If a server does not store separate mod-sequences per metadata item, it MUST ignore the entry-name and entry-type-req parameters in a MODSEQ search criterion rather than returning an error.
If the client's cached UIDVALIDITY differs from the server's, the client MUST delete its cached HIGHESTMODSEQ value, as the server is not required to preserve HIGHESTMODSEQ across UIDVALIDITY changes.
One of the two new response codes HIGHESTMODSEQ or NOMODSEQ MUST be returned in the OK untagged response for every successful SELECT or EXAMINE command, depending on whether the mailbox supports persistent storage of mod-sequences.
The first CONDSTORE-enabling command in a session MUST cause the server to return HIGHESTMODSEQ, unless the server had already sent NOMODSEQ for the currently selected mailbox.
Using UNCHANGEDSINCE with a mod-sequence value of 0 always fails if the metadata item exists. System flags MUST always be considered existent, whether currently set or not, meaning UNCHANGEDSINCE 0 will always fail for system flags.
When a STORE UNCHANGEDSINCE operation succeeds for a message, the server MUST update the mod-sequence and MUST send an untagged FETCH response including the MODSEQ data item, even if the .SILENT suffix was specified.
Whenever the state of a flag actually changes (added where not set, or removed where set), the mod-sequence for the message MUST be updated. Adding a flag already present or removing one already absent SHOULD NOT change the mod-sequence.
HIGHESTMODSEQ is defined as a new STATUS data item that returns the highest mod-sequence value of all messages in the mailbox. If the mailbox does not support persistent mod-sequences, the server MUST return 0 as its value.
The CHANGEDSINCE FETCH modifier restricts the FETCH result to only those messages whose mod-sequence is greater than the specified value. It implicitly adds the MODSEQ message data item to the response: `FETCH <set> (<data-items>) (CHANGEDSINCE <mod-sequence>)`.
The CONDSTORE parameter to SELECT and EXAMINE instructs the server to include MODSEQ fetch response data items in all subsequent unsolicited FETCH responses for that session, closing the race window between the server sending HIGHESTMODSEQ and the client issuing its first CONDSTORE-enabling command.
The HIGHESTMODSEQ response code is returned in the OK untagged response to SELECT/EXAMINE when the mailbox supports persistent mod-sequence storage. Its value is the highest mod-sequence of all messages in the mailbox: `OK [HIGHESTMODSEQ <mod-sequence-value>]`.
The MODIFIED response code is included in the tagged OK (or NO) response to a STORE command when one or more messages failed the UNCHANGEDSINCE test. It carries the set of message sequence numbers or UIDs that were not updated: `OK [MODIFIED <set>]`.
The MODSEQ message data item, when requested in a FETCH command, causes the server to return per-message mod-sequence values in the fetch response: `MODSEQ (<permsg-modsequence>)`. Once requested, the server MUST include MODSEQ in all subsequent unsolicited FETCH responses for that session.
The MODSEQ search criterion selects messages whose mod-sequence is equal to or greater than the specified value. An optional entry-name (e.g., `"/flags/\\draft"`) and entry-type-req (`priv`, `shared`, or `all`) may be specified to narrow the search to a particular metadata item type.
The NOMODSEQ response code is returned in the OK untagged response to SELECT/EXAMINE when the mailbox does not support persistent storage of mod-sequences: `OK [NOMODSEQ]`. After sending NOMODSEQ, the server MUST reject FETCH CHANGEDSINCE, FETCH/SEARCH MODSEQ, and STORE UNCHANGEDSINCE commands with a tagged BAD response.
The UNCHANGEDSINCE STORE modifier specifies a mod-sequence threshold. For each message in the set, the requested flag operation is performed only if the message's mod-sequence is equal to or less than the specified value; if any metadata item's mod-sequence exceeds the threshold, the operation MUST NOT be performed for that message.
This document registers the CONDSTORE capability in the IMAP4 capabilities registry maintained by IANA at http://www.iana.org/assignments/imap4-capabilities. The capability string is "CONDSTORE".
The Conditional STORE extension is believed not to introduce new security concerns beyond those already present in IMAP4 (RFC 3501). However, its availability may enable use of IMAP4 in critical applications (such as multi-client message queues) where correct server implementation and operation become significantly more important.
The mod-sequence-value field is a positive unsigned 64-bit integer encoded as 1 or more decimal digits (ABNF: `1*DIGIT`), with a valid range of 1 to 18,446,744,073,709,551,614. The special form mod-sequence-valzer also permits the value 0 to represent "no mod-sequence support".