idnits 2.17.1 draft-neystadt-imap-status-counters-01.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2002) is 7979 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'VPIM' is defined on line 384, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) -- Possible downref: Non-RFC (?) normative reference: ref. 'ABNF' -- Possible downref: Normative reference to a draft: ref. 'UM-ISSUES' == Outdated reference: A later version (-08) exists of draft-ietf-vpim-hint-07 ** Obsolete normative reference: RFC 1911 (ref. 'VPIM') (Obsoleted by RFC 2421, RFC 2422, RFC 2423) -- No information found for draft-melnikov-imap-keywords-XX - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'IMAP-KEYWORDS' Summary: 6 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft J. Neystadt 3 draft-neystadt-imap-status-counters-01.txt Comverse Technology 4 Expires: December 2002 A. Melnikov 5 MessagingDirect 6 June 2002 8 IMAP4 rev1 - STATUS-COUNTERS Extension 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet-Drafts 23 as reference material or to cite them other than as "work in 24 progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 1. Abstract 33 The STATUS-COUNTERS extends IMAP4rev1�s STATUS command. This 34 extension adds the following functionality: 36 Enable MUA to get mailbox counters per groups of messages, grouped 37 according to the value of Message-Context header field. For 38 example, the MUA can find out that the Inbox contains 5 unseen fax 39 messages. 41 2. Table of Contents 43 1. Abstract......................................................1 44 2. Table of Contents.............................................2 45 3. Introduction and Overview.....................................2 46 4. Conventions Used in this Document.............................3 47 5. Features......................................................3 48 5.1 CAPABILITY................................................3 49 5.2 STATUS command............................................3 50 5.3 COUNTERS response.........................................4 51 6. Implementation Guidelines.....................................5 52 6.1 Server Issues.............................................5 53 6.2 Client Issues.............................................6 54 7. Formal Syntax.................................................7 55 8. Security Considerations.......................................8 56 9. References....................................................8 57 10. Author's Addresses...........................................9 58 11. Change Log...................................................9 59 12. Open Issues for Discussion..................................10 60 13. To Do.......................................................10 62 3. Introduction and Overview 64 [IMAP4] defines the STATUS command that allows a Mail User Agent 65 (MUA) to query status of a mailbox on the server. [UM-ISSUES] 66 outlines a number of additional requirements that are beyond 67 abilities of the standard STATUS command. Some extracts from these 68 requirements are listed below. 70 [UM-ISSUES] 2.2.1 Mailbox Summary (Per-context counters in mailbox 71 STATUS command): 73 The common TUI (Telephony User Interface) prompt "you have two new 74 voice messages, six unheard messages, and one new fax message" 75 requires more information than is made available by IMAP STATUS 76 command. The STATUS command provides only a count of new and total 77 messages and doesn't allow to extract standardized attributes from 78 message headers. Without an extension to the STATUS command, in 79 order to get any aggregate information about message types, a 80 client has to open the mailbox with SELECT/EXAMINE and then either 81 perform FETCH or one or more SEARCHes. Both scenarios are 82 computationally expensive on the server and may generate 83 unnecessary traffic. 85 The STATUS-COUNTERS IMAP extension proposed in this document 86 extends the STATUS command to return number of messages having an 87 arbitrary IMAP flag set as well as belonging to a particular 88 message-context class. A single extended STATUS command will be 89 able to extract enough data to count messages in various 90 categories. 92 A server supporting this extension MAY extract all the information 93 required to fulfil a particular client request on every request, 94 however for an adequate performance it is RECOMMENDED that the 95 server implements one of the following: 97 - an agent performing a message injection into the message store 98 (MDA or IMAP server in the injection is done via IMAP APPEND) 99 should parse the message and create indexes for the necessary 100 information; 101 - IMAP server should parse and cache the necessary information 102 after the first request. 104 STATUS-COUNTERS relies on a special support of $Important keyword 105 defined in [IMAP-KEYWORDS] by the IMAP server. In particular, the 106 server MUST automatically set $Important flag on injection of an 107 "important" message as described in [IMAP-KEYWORDS]. 109 4. Conventions Used in this Document 111 In examples, "C:" and "S:" indicate lines sent by the client and 112 server respectively. 113 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 114 in this document are to be interpreted as defined in "Key words for 115 use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 117 Space character may be represented in examples as "". 119 5. Features 121 5.1 CAPABILITY 123 The STATUS-COUNTERS extension is implemented by any IMAP4 server 124 returning "STATUS-COUNTERS" as one of the supported capabilities to 125 the CAPABILITY command. If the server does not advertise the 126 STATUS-COUNTERS capability, the client MUST NOT use the STATUS- 127 COUNTERS extension and continue to operate with multiple old STATUS 128 commands and FETCHes or SEARCHes as specified in the base IMAP 129 specification (see section 7.2 for some examples). 131 5.2 STATUS command 133 The existing [IMAP4] STATUS command is extended. 135 A new meta-data item named COUNTERS is added to the existing STATUS 136 data items. 138 COUNTERS (list of counter names (or "attributes")) 140 This will provide client with different numeric summaries of 141 messages grouped according to the value of Message-Context header 142 field. The empty list specifies that only the total number of 143 messages in a group should be returned. 145 If COUNTERS status data item was specified in the STATUS command, 146 the untagged STATUS response code must contain COUNTERS data item. 148 Response to COUNTERS request can be slow, since some server 149 implementations may need to go over whole mailbox and process all 150 message headers in order to calculate counters. 152 Example: 154 C: A CAPABILITY 155 S: * CAPABILITY ... IMAP4rev1 STATUS-COUNTERS ... 156 S: A OK CAPABILITY 157 ... 158 C: B STATUS Inbox (UIDNEXT UIDVALIDITY 159 COUNTERS (\Seen $Important "Unseen-Important" \Recent)) 160 S: * STATUS Inbox (UIDNEXT 850 UIDVALIDITY 1234 161 COUNTERS (All (100 \Seen 30 $Important 20 162 "Unseen-Important" 10 \Recent 5) 163 "Voice-Message" (10 \Seen 3 $Important 2 164 "Unseen-Important" 1 \Recent 5) 165 "Fax-Message" (10 \Seen 3 $Important 2 166 "Unseen-Important" 1 \Recent 5))) 167 S: B OK STATUS completed. 169 5.3 COUNTERS response 171 Contents: parenthesized list messages groups (by Message-Context) 172 each one including parenthesized list of counters 174 COUNTERS response list is of the following form: 176 (Group1 (Total Attrib1 Value Attrib2 Value) Group2 (...) ...) 178 Message-Context class of a message is determined by inspecting the 179 Message-Context header field of the message and extracting its 180 value. Group name is either a Message-Context class as defined in 181 [Message-Context] (e.g. "Voice-Message" or "Fax-Message") or a 182 special tag ALL. ALL is used to indicate aggregated counters of all 183 messages, ignoring Message-Context attribute. Also note, that 184 according to [Message-Context] all messages without Message-Context 185 header MUST be treated as if they have a Message-Context header 186 with the value of "none". Comparison on Message-Context values MUST 187 be case insensitive as per [Message-Context]. 189 If messages of a particular Message-Context class are not present 190 in the mailbox, the information for this class is not included in 191 COUNTERS response list (for example, the IMAP example in the 192 previous sections suggests that there are no SMS messages in the 193 mailbox). 195 Valid group attributes are COUNTERS STATUS data items. Here are the 196 details of the counters: 198 Any IMAP Flag Number of messages with given IMAP flag set 199 per given Message-Context class (or All). For 200 example, $Important or \Deleted. 202 "Unseen-Important" Number of messages per given Message-Context 203 class (or All) that have the $Important 204 keyword set and don't have the \Seen flag set. 206 This extension allows IMAP server to implement additional 207 attributes and provide it per message-context (i.e. "X-My-Special- 208 Counter") 210 See previous section for the example of COUNTERS response. 212 6. Implementation Guidelines 214 6.1 Server Issues 216 Since in order to calculate message counters, the MIME headers of 217 the messages are inspected, this calculation can consume 218 significant amount of processing time. It is recommended for server 219 implementations to generate the counters during the injection of 220 the message (in MDA) or persistently cache them after they are 221 calculated for the first time. 223 It is expected that MUAs, in order to display to the user the 224 important or unseen messages, will query all subscribed mailboxes 225 for several counters during every login. Thus it is recommended 226 that the counters are cached permanently in the mailbox and their 227 retrieval should be fast. 229 Contraversaly to [IMAP-KEYWORDS], server supporting STATUS-COUNTERS 230 MUST be able to auto-set $Important falg on every injected 231 �important� message. 233 In order to satisfy the last MUST requirement a mail server MAY do 234 one of the following: 236 1. Set the $Important flag in [every] delivery agent using 237 implementation specific delivery API. If the delivery agent is 238 an IMAP client, it should specify the $Important keyword in 239 APPEND command. 241 2. Set the $Important flag using Sieve script, if the mail server 242 supports Sieve and the Sieve extension for setting IMAP flags. 243 When message is added to mailbox using APPEND, IMAP server 244 should parse it and turn on the flag. 246 3. Implement the logic for setting $Important flag when message is 247 accessed first time by a MUA and persist this flag. 249 6.2 Client Issues 251 If an IMAP server implementation does not support this command, its 252 logic can be achieved by one of the following algorithms: 254 A. For a given mailbox do: 256 1. a SELECT mailbox 257 2. b FETCH 1:* (BODY[HEADER (Message-Context)] FLAGS) 258 3. Calculate the counters from FETCH responses. 260 or 262 B. For a given mailbox do: 264 1. a SELECT mailbox 265 2. b SEARCH HEADER "Message-Context" "Voice-Message" 266 Construct message set from the result; if is 267 empty, skip till step 5. 268 3. c SEARCH UNSEEN. 269 Construct message set from the result ( is the 270 list of all unseen voice messages); if is empty, skip 271 till step 5. 272 4. d SEARCH KEYWORD $Important. 273 Result is the list of all important unseen voice 274 messages; 275 5. Repeat steps 2-4 for each message class the client is 276 interested in 277 6. Calculate the counters from SEARCH responses. 279 Scenario A may generate a lot of traffic for large mailboxes. 280 Scenario B is more computationally expensive for the server than 281 scenario A, but generates less traffic. 283 Note that for scenario B, there is no way for MUA to learn about 284 available Message-Contexts, as it is expected it will have to have 285 this knowledge as part of its user-interface. 287 It is expected that MUAs will need to request STATUS-COUNTERS for 288 all mailboxes it is interested in in order to generate a list to 289 display. MUA should not request STATUS-COUNTERS for all mailboxes 290 on the server, since the number of accessible mailboxes can be 291 extremely large. Instead MUAs should request STATUS-COUNTERS only 292 for mailboxes that would fit on a single screen or for all 293 mailboxes the user is subscribed to (the latter may be obtained 294 with LSUB). 296 7. Formal Syntax 298 The following syntax specification uses the Augmented Backus-Naur 299 Form (ABNF) notation as specified in [ABNF]. 301 Non-terminals referenced but not defined below are as defined by 302 [IMAP4]. 304 Except as noted otherwise, all alphabetic characters are case- 305 insensitive. The use of upper or lower case characters to define 306 token strings is for editorial clarity only. Implementations MUST 307 accept these strings in a case-insensitive fashion. 309 status = "STATUS" SP mailbox SP "(" status-att-ext 310 *(SP status-att-ext) ")" 311 ;; redefine STATUS command syntax defined in 312 ;;[IMAP4] 314 status-att-ext = status-att / status-req-cnt 315 ;; status-att is defined in [IMAP4] 317 status-req-cnt = "COUNTERS" SP "(" [counter-type 318 *(SP counter-type)] ")" 320 mailbox-data =/ "STATUS" SP mailbox SP "(" 321 [status-rsp-info *(SP status-rsp-info)] ")" / 323 status-rsp-info = status-rsp-std / status-rsp-cnt 324 status-rsp-std = status-att SP number 326 counter-type = flag-fetch | counter-special 327 ;; note: per flag-fetch \Recent is allowed here 329 counter-special = <"> ("Unseen-Important" | cntr-special-ext <"> 331 cntr-special-ext= atom 332 ;; any special counter extension, private 333 ;; extensions MUST start with "X-" prefix 335 status-rsp-cnt = "COUNTERS" SP "(" sts-rsp-cnt-grp 336 *(SP sts-rsp-cnt-grp) ")" 338 sts-rsp-cnt-grp = msg-ctx-cls-all SP "(" total-value 339 *(SP counter-value) ")" 341 counter-value = counter-type SP number 342 ;; counter type with the associated value for 343 ;; the corresponding Message-Context class 345 total-value = number 347 msg-ctx-cls-all = <"> message-context-class <"> | "ALL" 348 ;; message-context-class is defined in 349 ;; [Message-Context] 351 8. Security Considerations 353 There is a potential inconsistency that may be introduced by server 354 between actual messages in the mailboxes and information reported 355 by STATUS-COUNTERS. This can happen if the server reports 356 inaccurate information. User Agents must not blindly rely on the 357 correspondence between STATUS-COUNTERS and messages themselves. 359 It can be resource consuming for some server implementations to 360 handle STATUS-COUNTERS command with a mailbox with many messages. 361 This can potentially facilitate a "Deny of Service" attack. It is 362 recommended for servers to implement artificial delay between two 363 subsequent STATUS-COUNTERS commands with a very short delay between 364 them. 366 9. References 368 [IMAP4], Crispin, M., "Internet Message Access Protocol - Version 369 4rev1", RFC 2060, December 1996. 371 [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF 372 for Syntax Specifications: ABNF", Work in Progress. 374 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 375 Requirement Levels", BCP 14, RFC 2119, March 1997. 377 [UM-ISSUES] Vaudreuil, G., "Messaging profile for telephone-based 378 Messaging clients", draft-vaudreuil-um-issues-00, February 21, 379 2002. 381 [Message-Context] Burger, E., et al, "Message Context for Internet 382 Mail", draft-ietf-vpim-hint-07, June 5, 2001. 384 [VPIM] Vaudreuil, G., "Voice Profile for Internet", RFC 1911, 385 February 1996. 387 [IMAP-KEYWORDS] Melnikov, A., et al, "Registration of common IMAP 388 keywords", Work in progress: draft-melnikov-imap-keywords-XX.txt, 389 June 2002 391 10. Author's Addresses 393 John Neystadt 394 Comverse Technology 395 Habarzel 29, Ramat Hahayal Tel-Aviv, Israel, 69710 396 Phone: +972-3-645-4185 397 Email: john@comverse.com 399 Alexey Melnikov 400 ACI Worldwide/MessagingDirect 401 Address: 22 The Quadrant, Richmond, 402 Surrey, United Kingdom, TW9 1BP 403 Phone: +44 20 8332 4508 404 Email: mel@messagingdirect.com 406 11. Change Log 408 00 Initial Revision. 409 01 - Added support for generic IMAP flag counting. 410 - Removed Importance, since it now relies on $Important flag 411 from [IMAP-KEYWORDS]. 412 - Implemented various comments received from the imap list 413 regarding implementation options. 414 - Added ABNF. 415 - Major wording improvements. 417 12. Open Issues for Discussion 419 - Currently there is no way to request counters of per only 420 specific message context. If MUA requests new "COUNTERS" data item 421 it will get them all. This can be wasteful on large amount of 422 folders. On other hand this would complicate the command 423 furthermore. If somebody thinks this must be added, please say so. 425 - Should EXAMINE and SELECT include COUNTERS untagged response as 426 well? (Probably not) 428 - Is it useful to request just counters without grouping my message 429 context class? 431 13. To Do 433 Add a new command (similar to STATUS COUNTERS) that can be used in 434 SELECTED state.