draft-ietf-imapext-condstore-02.txt   draft-ietf-imapext-condstore-03.txt 
Internet Draft: IMAP Extension for Conditional STORE A. Melnikov Internet Draft: IMAP Extension for Conditional STORE A. Melnikov
Document: draft-ietf-imapext-condstore-02.txt S. Hole Document: draft-ietf-imapext-condstore-03.txt Isode Ltd.
Expires: December 2003 ACI WorldWide/MessagingDirect Expires: February 2004 S. Hole
June 2003 ACI WorldWide/MessagingDirect
August 2003
IMAP Extension for Conditional STORE operation IMAP Extension for Conditional STORE operation
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. Internet-Drafts are all provisions of Section 10 of RFC2026. Internet-Drafts are
working documents of the Internet Engineering Task Force (IETF), its working documents of the Internet Engineering Task Force (IETF), its
areas, and its working groups. Note that other groups may also areas, and its working groups. Note that other groups may also
distribute working documents as Internet-Drafts. distribute working documents as Internet-Drafts.
skipping to change at line 57 skipping to change at line 58
Table of Contents Table of Contents
1 Conventions Used in This Document ......................... X 1 Conventions Used in This Document ......................... X
2 Introduction and Overview ................................. X 2 Introduction and Overview ................................. X
3 IMAP Protocol Changes ..................................... X 3 IMAP Protocol Changes ..................................... X
3.1 New OK untagged responses for SELECT and EXAMINE ......... X 3.1 New OK untagged responses for SELECT and EXAMINE ......... X
3.1.1 HIGHESTMODSEQ response code ............................ X 3.1.1 HIGHESTMODSEQ response code ............................ X
3.1.2 NOMODSEQ response code ................................. X 3.1.2 NOMODSEQ response code ................................. X
3.2 STORE and UID STORE Commands ............................. X 3.2 STORE and UID STORE Commands ............................. X
3.3 MODSEQ message data item in FETCH Command ................ X 3.3 FETCH and UID FETCH Commands ............................. X
3.3.1 FETCH modifiers ........................................ X
3.3.2 MODSEQ message data item in FETCH Command .............. X
3.4 MODSEQ search criterion in SEARCH ........................ X 3.4 MODSEQ search criterion in SEARCH ........................ X
3.5 MODSEQ Sort Criterion .................................... X 3.5 MODSEQ Sort Criterion .................................... X
3.6 Modified SEARCH and SORT untagged responses .............. X 3.6 Modified SEARCH and SORT untagged responses .............. X
3.7 HIGHESTMODSEQ status data items .......................... X 3.7 HIGHESTMODSEQ status data items .......................... X
3.8 CONDSTORE parameter to SELECT and EXAMINE ................ X 3.8 CONDSTORE parameter to SELECT and EXAMINE ................ X
4 Formal Syntax ............................................. X 4 Formal Syntax ............................................. X
5 Security Considerations ................................... X 5 Security Considerations ................................... X
6 References ................................................ X 6 References ................................................ X
6.1 Normative References ..................................... X 6.1 Normative References ..................................... X
6.2 Informative References ................................... X 6.2 Informative References ................................... X
skipping to change at line 160 skipping to change at line 163
This extension makes the following changes to the IMAP4 protocol: This extension makes the following changes to the IMAP4 protocol:
a) extends the syntax of the STORE command to allow STORE a) extends the syntax of the STORE command to allow STORE
modifiers modifiers
b) adds the MODIFIED response code which should be used with b) adds the MODIFIED response code which should be used with
an OK response to the STORE command an OK response to the STORE command
c) adds a new MODSEQ message data item for use with the FETCH command c) adds a new MODSEQ message data item for use with the FETCH command
d) adds a new MODSEQ search criterion d) extends the syntax of the FETCH command to allow FETCH
modifiers
e) extends the syntax of untagged SEARCH responses to include mod-sequence e) adds a new MODSEQ search criterion
f) adds new OK untagged responses for the SELECT and EXAMINE commands f) extends the syntax of untagged SEARCH responses to include mod-sequence
g) defines an additional parameter to SELECT/EXAMINE commands g) adds new OK untagged responses for the SELECT and EXAMINE commands
h) adds the HIGHESTMODSEQ status data item to the STATUS command h) defines an additional parameter to SELECT/EXAMINE commands
i) adds the HIGHESTMODSEQ status data item to the STATUS command
A client supporting CONDSTORE extension indicates its willingness to receive A client supporting CONDSTORE extension indicates its willingness to receive
mod-sequence updates in all untagged FETCH responses by issuing a SELECT or mod-sequence updates in all untagged FETCH responses by issuing a SELECT or
EXAMINE command with the CONDSTORE parameter, or a FETCH, SEARCH, or SORT EXAMINE command with the CONDSTORE parameter, or a FETCH, SEARCH, or SORT
(if it also supports SORT=MODSEQ extension, see below) command that includes (if it also supports SORT=MODSEQ extension, see below) command that includes
the MODSEQ message data item, or a STORE command with the UNCHANGEDSINCE modifier. the MODSEQ message data item, a FETCH command with the CHANGEDSINCE modifier,
or a STORE command with the UNCHANGEDSINCE modifier.
The server will include mod-sequence data in all FETCH responses, whether they The server will include mod-sequence data in all FETCH responses, whether they
were caused by a regular STORE, STORE with UNCHANGEDSINCE modifier, or an external were caused by a regular STORE, STORE with UNCHANGEDSINCE modifier, or an external
agent, until the connection is closed. agent, until the connection is closed.
This document uses the term "CONSTORE-aware client" to refer to a client This document uses the term "CONSTORE-aware client" to refer to a client
that announces its willingness to receive mod-sequence updates as described that announces its willingness to receive mod-sequence updates as described
above. The term "CONDSTORE enabling command" will refer any of the commands above. The term "CONDSTORE enabling command" will refer any of the commands
listed above. listed above. A first CONDSTORE enabling command executed in the session
MUST cause the server to return HIGHESTMODSEQ (section 3.1.1) unless the
server has sent NOMODSEQ (section 3.1.2) response code when the currently
selected mailbox was selected.
This document also defines a new SORT extension with a capability name This document also defines a new SORT extension with a capability name
"SORT=MODSEQ". This extension is upwards compatible with the SORT extension "SORT=MODSEQ". This extension is upwards compatible with the SORT extension
defined in [SORT]. Server implementations that support both the CONDSTORE and defined in [SORT]. Server implementations that support both the CONDSTORE and
SORT extensions SHOULD also support the SORT=MODSEQ extension. The SORT extensions SHOULD also support the SORT=MODSEQ extension. The
SORT=MODSEQ extension makes the following additions to the SORT extension: SORT=MODSEQ extension makes the following additions to the SORT extension:
a) extends syntax of untagged SORT responses to include mod-sequence a) extends syntax of untagged SORT responses to include mod-sequence
(see section 3.6) (see section 3.6)
skipping to change at line 237 skipping to change at line 247
A disconnected client can use the value of HIGHESTMODSEQ to check if A disconnected client can use the value of HIGHESTMODSEQ to check if
it has to refetch flags and/or annotations from the server. If the it has to refetch flags and/or annotations from the server. If the
UIDVALIDITY value has changed for the selected mailbox, the client UIDVALIDITY value has changed for the selected mailbox, the client
MUST delete the cached value of HIGHESTMODSEQ. If UIDVALIDITY for MUST delete the cached value of HIGHESTMODSEQ. If UIDVALIDITY for
the mailbox is the same and if the HIGHESTMODSEQ value stored in the mailbox is the same and if the HIGHESTMODSEQ value stored in
the client's cache is less than the value returned by the server, the client's cache is less than the value returned by the server,
then some metadata items on the server have changed since the last then some metadata items on the server have changed since the last
synchronization, and the client needs to update its cache. The client synchronization, and the client needs to update its cache. The client
MAY use SEARCH MODSEQ as described in section 3.4 to find out exactly MAY use SEARCH MODSEQ as described in section 3.4 to find out exactly
which metadata items have changed. which metadata items have changed. Alternatively the client MAY issue
FETCH with CHANGEDSINCE modifier (section 3.3.1) in order to fetch data
for all messages that have metadata items changed since some known
modification sequence.
Example: C: A142 SELECT INBOX Example: C: A142 SELECT INBOX
S: * 172 EXISTS S: * 172 EXISTS
S: * 1 RECENT S: * 1 RECENT
S: * OK [UNSEEN 12] Message 12 is first unseen S: * OK [UNSEEN 12] Message 12 is first unseen
S: * OK [UIDVALIDITY 3857529045] UIDs valid S: * OK [UIDVALIDITY 3857529045] UIDs valid
S: * OK [UIDNEXT 4392] Predicted next UID S: * OK [UIDNEXT 4392] Predicted next UID
S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
S: * OK [HIGHESTMODSEQ 20010715194045007] S: * OK [HIGHESTMODSEQ 20010715194045007]
skipping to change at line 284 skipping to change at line 297
Responses: untagged responses: FETCH Responses: untagged responses: FETCH
Result: OK - store completed Result: OK - store completed
NO - store error: can't store that data NO - store error: can't store that data
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
This document extends the syntax of the STORE and UID STORE This document extends the syntax of the STORE and UID STORE
commands (see section 6.4.6 of [IMAP4]) to include an optional STORE commands (see section 6.4.6 of [IMAP4]) to include an optional STORE
modifier. The document defines the following modifier: modifier. The document defines the following modifier:
UNCHANGEDSINCE UNCHANGEDSINCE <mod-sequence>
For each message specified in the message set the server performs For each message specified in the message set the server performs
the following. If the mod-sequence of any metadata item of the the following. If the mod-sequence of any metadata item of the
message is equal or less than the specified UNCHANGEDSINCE value, message is equal or less than the specified UNCHANGEDSINCE value,
then the requested operation (as described by the then the requested operation (as described by the
message data item) is performed. If the operation is successful message data item) is performed. If the operation is successful
the server MUST update the mod-sequence attribute of the message. the server MUST update the mod-sequence attribute of the message.
An untagged FETCH response MUST be sent (even if the .SILENT suffix An untagged FETCH response MUST be sent (even if the .SILENT suffix
is specified) and the response MUST include the MODSEQ message data is specified or ANNOTATION message data item is used; the latter
changes the behavior described in Section 9.4 of [ANNOTATE])
and the response MUST include the MODSEQ message data
item. This is required to update the client's cache with the correct item. This is required to update the client's cache with the correct
mod-sequence values. See section 3.3 for more details. mod-sequence values. See section 3.3.2 for more details.
However, if the mod-sequence of any metadata item of the However, if the mod-sequence of any metadata item of the
message is greater than the specified UNCHANGEDSINCE value, than message is greater than the specified UNCHANGEDSINCE value, than
the requested operation MUST NOT be performed. In this case, the requested operation MUST NOT be performed. In this case,
the mod-sequence attribute of the message is not updated, and the the mod-sequence attribute of the message is not updated, and the
message number (or unique identifier in the case of the UID STORE message number (or unique identifier in the case of the UID STORE
command) is added to the list of messages that failed the UNCHANGESINCE test. command) is added to the list of messages that failed the UNCHANGESINCE test.
When the server finished performing the operation on all the messages When the server finished performing the operation on all the messages
in the message set, it checks for a non-empty list of messages that in the message set, it checks for a non-empty list of messages that
skipping to change at line 325 skipping to change at line 340
+FLAGS.SILENT (\Deleted) +FLAGS.SILENT (\Deleted)
S: * 1 FETCH (UID 4 MODSEQ (200012121231000)) S: * 1 FETCH (UID 4 MODSEQ (200012121231000))
S: * 2 FETCH (UID 6 MODSEQ (200012101230852)) S: * 2 FETCH (UID 6 MODSEQ (200012101230852))
S: * 4 FETCH (UID 8 MODSEQ (200012121130956)) S: * 4 FETCH (UID 8 MODSEQ (200012121130956))
S: a103 OK Conditional Store completed S: a103 OK Conditional Store completed
Example: Example:
C: a104 STORE * (UNCHANGEDSINCE 200012121230045) +FLAGS.SILENT C: a104 STORE * (UNCHANGEDSINCE 200012121230045) +FLAGS.SILENT
(\Deleted $Processed) (\Deleted $Processed)
S: * 50 FETCH (MODSEQ (200012111230045)) S: * 50 FETCH (MODSEQ (200012111230047))
S: a104 OK Store (conditional) completed S: a104 OK Store (conditional) completed
Example: Example:
C: c101 STORE 1 (UNCHANGEDSINCE 200012121230045) ANNOTATION
("/message/comment" ("value.priv" "My new comment"))
S: * OK [HIGHESTMODSEQ 200012111230047]
S: * 50 FETCH (MODSEQ (200012111230048))
S: c101 OK Store (conditional) completed
HIGHESTMODSEQ response code was sent by the server
presumably because this was the first CONDSTORE enabling
command.
Example:
In spite of the failure of the conditional STORE operation In spite of the failure of the conditional STORE operation
for message 7, the server continues to process the conditional for message 7, the server continues to process the conditional
STORE in order to find all messages which fail the test. STORE in order to find all messages which fail the test.
C: a105 STORE 7,5,9 (UNCHANGEDSINCE 20000320162338) C: a105 STORE 7,5,9 (UNCHANGEDSINCE 20000320162338)
+FLAGS.SILENT (\Deleted) +FLAGS.SILENT (\Deleted)
S: * 5 FETCH (MODSEQ (20000320162350)) S: * 5 FETCH (MODSEQ (20000320162350))
S: a105 OK [MODIFIED 7,9] Conditional STORE failed S: a105 OK [MODIFIED 7,9] Conditional STORE failed
skipping to change at line 412 skipping to change at line 438
Example: Example:
The following example is based on the example from the section 4.2.3 of The following example is based on the example from the section 4.2.3 of
[RFC-2180] and demonstrates that the MODIFIED response code may be also [RFC-2180] and demonstrates that the MODIFIED response code may be also
returned in the tagged NO response. returned in the tagged NO response.
Client tries to conditionally STORE flags on a mixture of expunged Client tries to conditionally STORE flags on a mixture of expunged
and non-expunged messages, one message fails the UNCHANGEDSINCE test. and non-expunged messages, one message fails the UNCHANGEDSINCE test.
C: B001 STORE 1:7 (UNCHANGEDSINCE 20000320172338) +FLAGS (\SEEN) C: B001 STORE 1:7 (UNCHANGEDSINCE 20000320172338) +FLAGS (\SEEN)
S: * 1 FETCH FLAGS (MODSEQ (20000320172342) \SEEN) S: * 1 FETCH (MODSEQ (20000320172342) FLAGS (\SEEN))
S: * 3 FETCH FLAGS (MODSEQ (20000320172342) \SEEN) S: * 3 FETCH (MODSEQ (20000320172342) FLAGS (\SEEN))
S: B001 NO [MODIFIED 2] Some of the messages no longer exist. S: B001 NO [MODIFIED 2] Some of the messages no longer exist.
C: B002 NOOP C: B002 NOOP
S: * 4 EXPUNGE S: * 4 EXPUNGE
S: * 4 EXPUNGE S: * 4 EXPUNGE
S: * 4 EXPUNGE S: * 4 EXPUNGE
S: * 4 EXPUNGE S: * 4 EXPUNGE
S: * 2 FETCH (MODSEQ (20000320172340) FLAGS (\Deleted \Answered)) S: * 2 FETCH (MODSEQ (20000320172340) FLAGS (\Deleted \Answered))
S: B002 OK NOOP Completed. S: B002 OK NOOP Completed.
skipping to change at line 459 skipping to change at line 485
subsequent unsolicited FETCH responses. subsequent unsolicited FETCH responses.
This document also changes the behaviour of the server when it has performed This document also changes the behaviour of the server when it has performed
a STORE or UID STORE command and the UNCHANGEDSINCE modifier is not specified. a STORE or UID STORE command and the UNCHANGEDSINCE modifier is not specified.
If the operation is successful for a message, the server MUST update If the operation is successful for a message, the server MUST update
the mod-sequence attribute of the message. The server is REQUIRED to the mod-sequence attribute of the message. The server is REQUIRED to
include the mod-sequence value whenever it decides to send the include the mod-sequence value whenever it decides to send the
unsolicited FETCH response to all CONDSTORE-aware clients that have opened unsolicited FETCH response to all CONDSTORE-aware clients that have opened
the mailbox containing the message. the mailbox containing the message.
3.3. MODSEQ message data item in FETCH Command 3.3 FETCH and UID FETCH Commands
3.3.1 FETCH modifiers
Arguments: sequence set
message data item names or macro
Responses: untagged responses: FETCH
Result: OK - fetch completed
NO - fetch error: can't fetch that data
BAD - command unknown or arguments invalid
This document extends the syntax of the FETCH and UID FETCH
commands (see section 6.4.5 of [IMAP4]) to include an optional FETCH
modifier. The document defines the following modifier:
CHANGEDSINCE <mod-sequence>
CHANGEDSINCE FETCH modifier allows to further subset the list of
messages described by sequence set. The information described by
message data items is only returned for messages that have
mod-sequence bigger than <mod-sequence>.
When CHANGEDSINCE FETCH modifier is specified, it implicitly adds
MODSEQ FETCH message data item (section 3.3.2).
Example:
C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345)
S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen))
S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted))
S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk $MDNSent))
S: s100 OK FETCH completed
3.3.2 MODSEQ message data item in FETCH Command
This extension adds a MODSEQ message data item to the FETCH command. This extension adds a MODSEQ message data item to the FETCH command.
The MODSEQ message data item allows clients to retrieve mod-sequence The MODSEQ message data item allows clients to retrieve mod-sequence
values for a range of messages in the currently selected mailbox. values for a range of messages in the currently selected mailbox.
Once the client specified the MODSEQ message data item in a FETCH request, Once the client specified the MODSEQ message data item in a FETCH request,
the server MUST include the MODSEQ fetch response data items in all the server MUST include the MODSEQ fetch response data items in all
subsequent unsolicited FETCH responses. subsequent unsolicited FETCH responses.
Syntax: MODSEQ Syntax: MODSEQ
skipping to change at line 733 skipping to change at line 794
status-att-req = status-att / "HIGHESTMODSEQ" status-att-req = status-att / "HIGHESTMODSEQ"
status-rsp-info = status-att SP number / status-rsp-info = status-att SP number /
"HIGHESTMODSEQ" SP mod-sequence-value "HIGHESTMODSEQ" SP mod-sequence-value
store = "STORE" SP set store-modifiers SP store-att-flags store = "STORE" SP set store-modifiers SP store-att-flags
store-modifiers = [ SP "(" store-modifier *(SP store-modifier) ")" ] store-modifiers = [ SP "(" store-modifier *(SP store-modifier) ")" ]
store-modifier = "UNCHANGEDSINCE" SP mod-sequence-valzer store-modifier = "UNCHANGEDSINCE" SP mod-sequence-valzer
;; Only single "UNCHANGEDSINCE" may be specified ;; Only a single "UNCHANGEDSINCE" may be specified
;; in a STORE operation ;; in a STORE operation
fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" /
"FAST" / fetch-att /
"(" fetch-att *(SP fetch-att) ")") [SP fetch-modifiers]
;; modifies the original IMAP4 fetch command to
;; accept optional modifiers
fetch-modifiers = "(" fetch-modifier *(SP fetch-modifier) ")"
fetch-modifier = fetch-modifier-name / fetch-modifier-name SP astring /
fetch-modifier-name SP "(" fetch-modif-params ")"
;; modifiers to FETCH may contain a modifier name
;; followed by zero or more atoms or strings - multiple
;; items are always parenthesised, nesting is allowed
fetch-modif-params = astring *(SP astring) /
"(" fetch-modif-params *(SP fetch-modif-params) ")"
fetch-modifier-name = atom
chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value
;; CHANGEDSINCE FETCH modifier conforms to
;; the fetch-modifier syntax
fetch-att =/ fetch-mod-sequence fetch-att =/ fetch-mod-sequence
;; modifies original IMAP4 fetch-att ;; modifies original IMAP4 fetch-att
fetch-mod-sequence = "MODSEQ" fetch-mod-sequence = "MODSEQ"
fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")" fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")"
search-key =/ search-modsequence search-key =/ search-modsequence
;; modifies original IMAP4 search-key ;; modifies original IMAP4 search-key
;; ;;
skipping to change at line 801 skipping to change at line 885
mod-sequence-valzer = "0" | mod-sequence-value mod-sequence-valzer = "0" | mod-sequence-value
search_sort_mod_seq = "(" "MODSEQ" SP mod-sequence-value ")" search_sort_mod_seq = "(" "MODSEQ" SP mod-sequence-value ")"
sort-key =/ "MODSEQ" sort-key =/ "MODSEQ"
condstore-param = "CONDSTORE" condstore-param = "CONDSTORE"
;; defines the select parameter used with ;; defines the select parameter used with
;; CONDSTORE extension ;; CONDSTORE extension
;;Borrowed from IMAP4rev1 and modified accordingly:
mailbox-data =/ "STATUS" SP mailbox SP "(" mailbox-data =/ "STATUS" SP mailbox SP "("
[status-rsp-info *(SP status-rsp-info)] ")" / [status-rsp-info *(SP status-rsp-info)] ")" /
"SEARCH" [1*(SP nz-number) SP search_sort_mod_seq] / "SEARCH" [1*(SP nz-number) SP search_sort_mod_seq] /
"SORT" [1*(SP nz-number) SP search_sort_mod_seq] "SORT" [1*(SP nz-number) SP search_sort_mod_seq]
attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" / attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" /
"\\Seen" / "\\Draft" / attr-flag-keyword / "\\Seen" / "\\Draft" / attr-flag-keyword /
attr-flag-extension attr-flag-extension
;; Does not include "\\Recent" ;; Does not include "\\Recent"
skipping to change at line 966 skipping to change at line 1048
Acknowledgement Acknowledgement
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
Appendix A. Open Issues and Change History Appendix A. Open Issues and Change History
Note that this appendix will be removed before publication. Note that this appendix will be removed before publication.
0.1. Change History 0.1. Change History
Changes from draft-ietf-imapext-condstore-02
1. Added FETCH modifiers.
2. Added example for using ANNOTATE with UNCHANGEDSINCE STORE
modifier.
3. Added a new requirement to send HIGHESTMODSEQ response code
when implicit enabling is used.
4. Fixed syntax in an example in section 3.2.
Changes from draft-ietf-imapext-condstore-01 Changes from draft-ietf-imapext-condstore-01
1. Fixed missing \\ in one example. 1. Fixed missing \\ in one example.
2. Added explanatory comment that search-key modifications apply at 2. Added explanatory comment that search-key modifications apply at
least to SEARCH and SORT command. least to SEARCH and SORT command.
3. Don't require from a conditional store operation to be atomic accross 3. Don't require from a conditional store operation to be atomic accross
message set, updated text and examples. message set, updated text and examples.
4. Added SORT=MODSEQ extension and reworked text in the Introduction section. 4. Added SORT=MODSEQ extension and reworked text in the Introduction section.
5. Added Conditional STORE example based on suggestions from RFC 2180. 5. Added Conditional STORE example based on suggestions from RFC 2180.
6. Removed the paragraph about DOS attack from the Security considerations 6. Removed the paragraph about DOS attack from the Security considerations
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/