[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 RFC 5182

Document: draft-melnikov-imap-search-res-04.txt           A. Melnikov
Intended category: Standard Track                          Isode Ltd.
Updates: RFC 4731 (if approved)                         November 2006
Expires: May 2007



         IMAP extension for referencing the last SEARCH result

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress".

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   A revised version of this draft document will be submitted to the RFC
   editor as a Proposed Standard for the Internet Community.  Discussion
   and suggestions for improvement are requested, and should be sent to
   the IMAPEXT Mailing list <ietf-imapext@imc.org>. Distribution of this
   draft is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   Many IMAP clients use the result of a SEARCH command as the input to
   perform another operation, for example fetching the found messages,
   deleting them or copying them to another mailbox.




Melnikov                    Expires: May 2007                   [Page 1]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   This can be achieved using standard IMAP operations described in RFC
   2501, however this would be suboptimal: the server will send the list
   of found messages to the client, after that the client will have to
   parse the list, reformat it and send it back to the server.  The
   client can't pipeline the SEARCH command with the subsequent command.

   This document proposes an IMAP extension that allows a client to tell
   a server to use the result of the latest SEARCH (or UID SEARCH)
   command as an input to any subsequent command.

   This document updates RFC 4731.


1.   Conventions Used in this Document

   In examples, "C:" indicates lines sent by a client that is connected
   to a server.  "S:" indicates lines sent by the server to the client.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [KEYWORDS].

   <<Other editorial comments/questions are shown like this.>>


2.   Introduction and Overview

   The SEARCH result reference extension described in this document is
   present in any IMAP4 implementation which returns "X-DRAFT-
   I04-SEARCHRES" as one of the supported capabilities in the CAPABILITY
   command response. <<Note to the RFC Editor: the capability name will
   change upon publication as an RFC>>.

   The SEARCH result reference extension defines a new SEARCH result
   option [IMAPABNF] "SAVE" that tells the server to remember the result
   of the SEARCH or UID SEARCH command (as well as any command based on
   SEARCH, e.g. SORT and THREAD [SORT]) and store it in an internal
   variable that we will reference as the "search result variable". The
   client can use the "$" marker to reference the content of this
   internal variable. The "$" marker can be used instead of message (or
   UID) sequence in order to indicate that the server should substitute
   it with the list of messages from the search result variable.  Thus
   the client can use the result of the latest remembered SEARCH command
   as a parameter to another command.  The search result marker has
   several advantages:
    * it avoids wasted bandwidth and associated delay;
    * it allows the client to pipeline a SEARCH [IMAP4] command with a
      subsequent FETCH/STORE/COPY [IMAP4] or UID EXPUNGE [UIDPLUS]



Melnikov                    Expires: May 2007                   [Page 2]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   command;
    * the client doesn't need to spend time reformatting the
      result of a SEARCH command into a message set used in
      the subsequent command;
    * it allows the server to perform optimizations.

   In absence of any other SEARCH result option, the SAVE result option
   also suppresses any SEARCH response that would have been otherwise
   returned by the SEARCH command.  If other SEARCH result options are
   present, the SAVE result option MAY suppresses SEARCH or ESEARCH
   [IMAPABNF] responses (or there parts) that would have been otherwise
   returned by the SEARCH command.

   Upon successful completion of a SELECT or an EXAMINE command (after
   the tagged OK response), the current search result variable is set to
   all messages in the mailbox, i.e. "1:*" message set if the mailbox is
   not empty.  Note, that "1:*" here refers to a static snapshot of the
   mailbox at the moment of selection, so message that are subsequently
   added to the mailbox are not automatically included in this set.

   A successful SEARCH command with the SAVE result option sets the
   value of the search result variable to the list of messages found in
   the SEARCH command. For example, if no messages were found, the
   search result variable will contain the empty list.  A failed SEARCH
   command (any SEARCH command that caused the server to return BAD or
   NO tagged response) or a successful SEARCH command with no SAVE
   result option MUST NOT change the search result variable.

   When a message listed in the search result variable is EXPUNGEd, it
   is automatically removed from the list.  Implementors are reminded
   that if the server stores the list as a list of message numbers, it
   MUST automatically adjust them when notifying the client about
   expunged messages.

   If the server decides to send a new UIDVALIDITY value while mailbox
   is opened, this causes resetting of the search variable to the empty
   list.

   Note that even if the "$" marker contains the empty list of messages,
   it must be treated by all commands accepting message sets as
   parameters, as a valid, but non matching list of messages. For
   example, the "FETCH $" command would return tagged OK response and no
   FETCH responses.  See also the Example # 5 below.

   Implementation note: server implementers should note that "$" can
   reference IMAP message sequence or UID sequence, depending on context
   where it is used. For example, the "$" marker can be set as a result
   of a SEARCH (SAVE) command and used as a parameter to a UID FETCH



Melnikov                    Expires: May 2007                   [Page 3]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   command (which accept UID sequence, not message sequence), or the "$"
   marker can be set as a result of a UID SEARCH (SAVE) command and used
   as a parameter to a FETCH command (which accept message sequence, not
   UID sequence).

 2.1.   Examples

   1) The following example demonstrates how the client can use the
      result of a SEARCH command to FETCH headers of interesting
      messages:

   Example 1:
               C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994
                  NOT FROM "Smith"
               S: A282 OK SEARCH completed, result saved
               C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER)
               S: * 2 FETCH (UID 14 ...
               S: * 84 FETCH (UID 100 ...
               S: * 882 FETCH (UID 1115 ...
               S: A283 OK completed

   The client can also pipeline the two commands:

   Example 2:
               C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994
                  NOT FROM "Smith"
               C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER)
               S: A282 OK SEARCH completed
               S: * 2 FETCH (UID 14 ...
               S: * 84 FETCH (UID 100 ...
               S: * 882 FETCH (UID 1115 ...
               S: A283 OK completed

   2) The following example demonstrates that the result of one SEARCH
      command can be used to subset the result of another SEARCH
      command:

   Example 3:
               C: A300 SEARCH RETURN (SAVE) SINCE 1-Jan-2004
                   NOT FROM "Smith"
               S: A300 OK SEARCH completed
               C: A301 UID SEARCH UID $ SMALLER 4096
               S: * SEARCH 17 900 901
               S: A301 OK completed

   Note that the second command in Example 3 can be replaced with:
               C: A301 UID SEARCH $ SMALLER 4096
   and the result of the command would be the same.



Melnikov                    Expires: May 2007                   [Page 4]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   3) The following example demonstrates that a failed SEARCH doesn't
      invalidate the search result variable. It also shows that the "$"
      marker can be combined with other message numbers using the OR
      SEARCH criterion.

   Example 4:
               C: B282 SEARCH RETURN (SAVE) SINCE 1-Feb-1994
                   NOT FROM "Smith"
               S: B282 OK SEARCH completed
               C: B283 SEARCH CHARSET KOI8-R (OR $ 1,3000:3021) TEXT {4}
               C: XXXX
               S: B283 NO [BADCHARSET UTF-8] KOI8-R is not supported
               C: B284 SEARCH CHARSET UTF-8 (OR $ 1,3000:3021) TEXT {8}
               C: YYYYYYYY
               S: * SEARCH 882 1102 3003 3005 3006
               S: B284 OK completed

        Note: Since this document is restricted to 7-bit ASCII text, it
        is not possible to show actual KOI8-R or UTF-8 data.  The "XXXX"
        and ""YYYYYYYY" are placeholders for what would be 4 and 8
        octets of 8-bit data in an actual transaction.

        4) The following example demonstrates that it is not an error to
        use the "$" marker when it contains no messages.  Explanatory
        comments are starting with // and are not part of the protocol:


        Example 5:
                    C: E282 SEARCH RETURN (SAVE) SINCE 28-Oct-2006
                        NOT FROM "Eric"
                    C: E283 COPY $ "Other Messages"
                   //The "$" contains no messages
                    S: E282 OK SEARCH completed
                    S: E283 OK COPY completed, nothing copied


 2.2.   Interaction with ESEARCH extension

        Servers that implement both [ESEARCH] and the extension defined
        in this document are required to conform to additional
        requirements listed in this section.

        The SAVE result option doesn't change whether the server would
        return item corresponding to MIN, MAX and COUNT [ESEARCH] result
        options.  However when the SAVE result option is combined with
        the ALL [ESEARCH] result option, the server MUST NOT return the
        ALL return item in the corresponding ESEARCH response.




Melnikov                    Expires: May 2007                   [Page 5]

INTERNET DRAFT        Last SEARCH result reference         November 2006


        When the SAVE result option is combined with the MIN or MAX
        [ESEARCH] result option, and none of the other ESEARCH result
        options are present, the corresponding MIN/MAX is returned (if
        the search result is not empty) but the "$" marker would contain
        a single message as returned in the MIN/MAX return item. If the
        SAVE result option is combined with both MIN and MAX result
        options, and none of the other ESEARCH result options are
        present, the "$" marker would contain one or two messages as
        returned in the MIN/MAX return items.  If the SAVE result option
        is combined with ALL and/or COUNT result option, the "$" marker
        would always contain all messages found by the SEARCH or UID
        SEARCH command.

        The following table summarizes the additional requirement on
        ESEARCH server implementations described in this section.

        +----------------+-------------------+-------------------------+
        | Combination of | "$" marker value  |     Data returned in    |
        |  Result option |                   |     ESEARCH response    |
        +----------------+-------------------+-------------------------+
        |   SAVE MIN     |        MIN        |           MIN           |
        +----------------+-------------------+-------------------------+
        |   SAVE MAX     |        MAX        |           MAX           |
        +----------------+-------------------+-------------------------+
        |   SAVE MIN MAX |     MIN & MAX     |        MIN & MAX        |
        +----------------+-------------------+-------------------------+
        |   SAVE * [m]   | all found messages| * & [m], except for ALL |
        +----------------+-------------------+-------------------------+

        where  '*'  means "ALL" and/or "COUNT"
              '[m]' means optional "MIN" and/or "MAX"


        The following example demonstrates behavioural difference
        for different combinations of ESEARCH result options.
        Explanatory comments are starting with // and are not
        part of the protocol:

        Example 6:  C: C282 SEARCH RETURN (ALL) SINCE 12-Feb-2006
                        NOT FROM "Smith"
                    S: * ESEARCH (TAG "C283") ALL 2,10:15,21
                  //$ value hasn't changed
                    S: C282 OK SEARCH completed

                    C: C283 SEARCH RETURN (ALL SAVE) SINCE 12-Feb-2006
                        NOT FROM "Smith"
                    S: * ESEARCH (TAG "C283")
                  //$ value is 2,10:15,21



Melnikov                    Expires: May 2007                   [Page 6]

INTERNET DRAFT        Last SEARCH result reference         November 2006


                    S: C283 OK SEARCH completed

                    C: C284 SEARCH RETURN (SAVE MIN) SINCE 12-Feb-2006
                        NOT FROM "Smith"
                    S: * ESEARCH (TAG "C284") MIN 2
                  //$ value is 2
                    S: C284 OK SEARCH completed

                    C: C285 SEARCH RETURN (MAX SAVE MIN) SINCE
                        12-Feb-2006 NOT FROM "Smith"
                    S: * ESEARCH (TAG "C285") MIN 2 MAX 21
                  //$ value is 2,21
                    S: C285 OK SEARCH completed

                    C: C286 SEARCH RETURN (MAX SAVE MIN COUNT)
                        SINCE 12-Feb-2006 NOT FROM "Smith"
                    S: * ESEARCH (TAG "C286") MIN 2 MAX 21 COUNT 8
                  //$ value is 2,10:15,21
                    S: C286 OK SEARCH completed

                    C: C286 SEARCH RETURN (ALL SAVE MIN) SINCE
                        12-Feb-2006 NOT FROM "Smith"
                    S: * ESEARCH (TAG "C286") MIN 2
                  //$ value is 2,10:15,21
                    S: C286 OK SEARCH completed


   3.   Formal Syntax

   The following syntax specification uses the Augmented Backus-Naur
   Form (ABNF) notation as specified in [ABNF]. Non-terminals referenced
   but not defined below are as defined in [IMAP4] or [IMAPABNF].

   Except as noted otherwise, all alphabetic characters are case-
   insensitive.  The use of upper or lower case characters to define
   token strings is for editorial clarity only.  Implementations MUST
   accept these strings in a case-insensitive fashion.

   capability         =/ "X-DRAFT-I04-SEARCHRES"
                        ;; capability is defined in [IMAP4]

   <<fix capability name before publication>>

   sequence-set       =/ seq-last-command
                        ;; extends sequence-set to allow for
                        ;; "result of the last command" indicator.

   seq-last-command   = "$"



Melnikov                    Expires: May 2007                   [Page 7]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   search-return-opt  = "SAVE"
                        ;; conforms to generic search-return-opt
                        ;; syntax defined in [IMAPABNF]



4.   Security Considerations

   It is believed that this extension doesn't raise any additional
   security concerns not already discussed in [IMAP4].

   However, this extension might require the server to keep additional
   state, that may be used to simplify Deny of Service attacks.


5.  IANA Considerations

   IMAP4 capabilities are registered by publishing a standards track or
   IESG approved experimental RFC.  The registry is currently located
   at:

      http://www.iana.org/assignments/imap4-capabilities

   This document defines the "X-DRAFT-I04-SEARCHRES" <<Fix upon
   publication>>
    IMAP capability.  IANA is requested to add it to the registry.


6.   Acknowledgments

   The author would like to thank Mark Crispin, Cyrus Daboo and Curtis
   King for reminding that this document has to be written, as well as
   for comments and corrections received.

   The author would also like to thank Dave Cridland for comments and
   corrections received.


7.   References

7.1. Normative references

   [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
   Requirement Levels", BCP 14, RFC 2119, March 1997.

   [ABNF] Crocker, D., and Overell, P. "Augmented BNF for Syntax
   Specifications: ABNF", RFC 4234, October 2005.




Melnikov                    Expires: May 2007                   [Page 8]

INTERNET DRAFT        Last SEARCH result reference         November 2006


   [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
   4rev1", RFC 3501, University of Washington, March 2003.

   [IMAPABNF] Melnikov, A., and C. Daboo, "Collected extensions to IMAP4
   ABNF", RFC 4466, April 2006.

   [ESEARCH] Melnikov, A., and D. Cridland, "IMAP4 Extension to SEARCH
   Command for Controlling What Kind of Information Is Returned", RFC
   4731, November 2006.


7.2. Informative references

   [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) -
   UIDPLUS extension", RFC 4315, December 2005.

   [SORT] Crispin, M. and  K. Murchison, "INTERNET MESSAGE ACCESS
   PROTOCOL - SORT AND THREAD EXTENSIONS", work in progress, draft-ietf-
   imapext-sort-XX.txt

8.   Author's Addresses

   Alexey Melnikov
   Isode Ltd.
   5 Castle Business Village,
   36 Station Road,
   Hampton, Middlesex,
   TW12 2BX, United Kingdom

   Email: Alexey.Melnikov@isode.com


9.   Full Copyright Statement

   Copyright (C) The Internet Society (2006).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.




Melnikov                    Expires: May 2007                   [Page 9]

INTERNET DRAFT        Last SEARCH result reference         November 2006


Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.


10.   Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at ietf-
   ipr@ietf.org.






















Melnikov                    Expires: May 2007                  [Page 10]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/