One document matched: draft-brandt-imap-replace-02.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?><?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-brandt-imap-replace-02" ipr="trust200902">
<front>
<title abbrev="IMAP REPLACE Extension">
IMAP REPLACE Extension
</title>
<author fullname="Stuart Brandt" initials="S" surname="Brandt">
      <organization>AOL</organization>
      <address>
        <postal>
          <street>43623 Preddy Ct</street>
          <!-- Reorder these if your country does things differently -->
          <city>Ashburn</city>
          <region>VA</region>
          <code>20147</code>
          <country>USA</country>
        </postal>
        <email>stujenerin@aol.com</email>
        <!-- uri and facsimile elements may also be added -->
      </address>
    </author>
    <date day="19" month="January" year="2016" />
    <keyword>IMAP</keyword>
    <keyword>REPLACE</keyword>
    <keyword>email</keyword>
    <abstract>
       <t> This document defines an IMAP extension which can be used to replace
           an existing message in a message store with a new message. Message
           replacement is a common operation for clients that automatically 
           save drafts or notes as a user composes them.
       </t>
    </abstract>
</front>

<middle>
<section anchor="Conventions" title="Conventions Used in This Document"> 
<t>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 <xref target="RFC2119"/>.
</t>
<t>Formal syntax is defined by <xref target="RFC5234"/>.
</t>
<t>
Example lines prefaced by "C:" are sent by the client and ones
prefaced by "S:" by the server. 
</t>
</section>  
<section anchor="Overview" title="Overview"> 
<t>
This document defines an IMAP <xref target="RFC3501"/> extension to facilitate
replacing an existing message with a new one. This is accomplished by 
defining a new REPLACE command and extending the UID command to 
allow UID REPLACE. 
</t>
<t>
Since there is no replace function in the base IMAP specification, clients 
have instead had to use a combination of three separate commands issued 
in serial fashion; APPEND, STORE, EXPUNGE. Pipelining of these three 
commands is not recommended since failure of any individual command 
should prevent subsequent commands from being executed lest the original 
message version be lost.  
</t>
<t>
Because of the non-atomic nature of the existing sequence, 
interruptions can leave messages in intermediate states which can 
be seen and acted upon by other clients. Such interruptions can 
also strand older revisions of messages, thereby forcing the user 
to manually clean up multiple revisions of the same message in 
order to avoid wasteful quota consumption.  Additionally, the 
existing sequence can fail on APPEND due to an over-quota 
condition even though the subsequent STORE/EXPUNGE would free up 
enough space for the newly revised message. And finally, server 
efficiencies may be possible with a single logical message
replacement operation as compared to the existing 
APPEND/STORE/EXPUNGE sequence.
</t>
<t>
In its simplest form, the REPLACE command is a single-command 
encapsulation of APPEND, STORE +flags \DELETED and UID EXPUNGE 
for a message, except that it avoids any of the quota implications or 
intermediate states associated with the 3 command sequence. In 
handling a REPLACE command, a server MUST NOT generate a response 
code for the STORE +flags \DELETED portion of the sequence. 
Additionally, servers supporting the REPLACE command MUST NOT infer 
any inheritance of content, flags, or annotations from the message 
being replaced. Finally, the replaced and replacing messages SHOULD 
NOT be present in the mailbox at the same time.
</t>
</section> 
<section anchor="REPLACEandUIDREPLACE" title="REPLACE and UID REPLACE"> 
<section anchor="AdvertiseREPLACE" title="Advertising Support for REPLACE">
<t>
Servers that implement the REPLACE extension will return "REPLACE" 
as one of the supported capabilities in the CAPABILITY command 
response.
</t>
</section>
<section anchor="REPLACE" title="REPLACE Command">  
<t>
<figure>
<artwork>
Arguments:  message sequence number
            mailbox name
            OPTIONAL flag parenthesized list
            OPTIONAL date/time string
            message literal

Responses: no specific responses for this command

Result:     OK - replace completed
            NO - replace error; can't remove specified message 
                 or can't add new message content
            BAD - command unknown or arguments invalid
</artwork>
</figure>
</t>
<t>
<figure>
<artwork>
Example:
  C: A003 REPLACE 4 Drafts (\Seen \Draft) {312}
  S: + Ready for literal data
  C: Date: Thu, 1 Jan 2015 00:05:00 -0500 (EST)
  C: From: Fritz Schmidt <fritz.ze@example.org>
  C: Subject: happy new year !!
  C: To: miss.mitzy@example.org
  C: Message-Id: <B238822388-0100000@example.org>
  C: MIME-Version: 1.0
  C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
  C:
  C: Just saw the best fireworks show. Wish you were here.
  C:
  S: * 4 EXPUNGE
  S: A003 OK [APPENDUID 1 2000] Replace completed
</artwork>
</figure>
</t>
</section> 
<section anchor="UIDREPLACE" title="UID REPLACE Command"> 
<t>
This extends the first form of the UID command (see <xref target="RFC3501"/>
Section 6.4.8) to add the REPLACE command defined above as a valid 
argument. This form of REPLACE uses a UID rather than sequence 
number as its first parameter.
<figure>
<artwork>
Example:
  C: A004 UID REPLACE 2000 Drafts (\Seen \Draft) {350}
  S: + Ready for literal data
  C: Date: Thu, 1 Jan 2015 00:06:00 -0500 (EST)
  C: From: Fritz Schmidt <fritz.ze@example.org>
  C: Subject: happy new year !!
  C: To: miss.mitzy@example.org
  C: Message-Id: <B238822389-0100000@example.org>
  C: MIME-Version: 1.0
  C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
  C:
  C: Just saw the best fireworks show. Wish you were here.
  C: Hopefully next year you can join us.
  C:
  S: * 4 EXPUNGE
  S: A004 OK [APPENDUID 1 2001] Replace completed
</artwork>
</figure>
</t>
</section> 
<section anchor="HowItWorks" title="Semantics of REPLACE and UID REPLACE"> 
<t>
The REPLACE and UID REPLACE commands take five arguments: a 
message identifier, a named mailbox, an optional parenthesized 
flag list, an optional message date/time string, and a message 
literal. The message literal will be appended to the named 
mailbox, and the message specified by the message identifier will
be removed from the selected mailbox. These operations will appear
to the client as a single action. This has the same effect as the
following sequence:
<figure>
<artwork>
   1. APPEND
   2. [UID] STORE +FLAGS.SILENT \DELETED
   3. UID EXPUNGE
</artwork>
</figure>
</t>
<t>
In the cited sequence, the quota implications of the APPEND are
evaluated within the context of the pending EXPUNGE so that only
the net quota consumption is considered.  Additionally, the EXPUNGE
portion of the sequence only applies to the specified message, 
not all messages flagged as \Deleted.
</t>
<t>
Although the effect of REPLACE is identical to the steps above, 
the semantics are not identical; similar to MOVE <xref target="RFC6851"/>, the 
intermediate states produced do not occur, and the response codes 
are different. In particular, the response codes for EXPUNGE and 
APPEND will be returned while those for the STORE operation MUST 
NOT be generated. 
</t>
<t>
When an error occurs while processing REPLACE or UID REPLACE, the
server MUST NOT leave the selected mailbox in an inconsistent 
state; any untagged EXPUNGE response MUST NOT be sent until
all actions are successfully completed. 
</t>
<t>
While it may be common for the named mailbox argument to match the 
selected mailbox for the common use case of replacing a draft, the 
REPLACE extension intentionally does not require the two to be the same.
As an example, it's possible to use the REPLACE command to replace 
a message in the \Drafts special-use mailbox with a message in the
\Sent special-use mailbox following message submission.
</t>
<t>
Because of the similarity of REPLACE to APPEND, extensions that
affect APPEND affect REPLACE in the same way. Response codes such
TRYCREATE (see <xref target="RFC3501"/> Section 6.3.11), as well as those
defined by extensions, are sent as appropriate. See <xref target="ExtensionInteractions"/>
for more information about how REPLACE interacts with other IMAP 
extensions.
</t>
</section> 
<section anchor="ValidState" title="IMAP State Diagram Impacts">
<t>
Unlike the APPEND command which is valid in the authenticated 
state, the REPLACE and UID REPLACE commands MUST only be valid 
in the selected state. This difference from APPEND is necessary 
since REPLACE operates on message sequence numbers.
</t>
</section> 
</section>

<section anchor="ExtensionInteractions" title="Interaction with other extensions">
<t>
This section describes how REPLACE interacts with some other IMAP 
extensions.
</t>
<section anchor="RFC4314interact" title="RFC 4314, ACL">
<t>
The ACL rights <xref target="RFC4314"/> required for UID REPLACE are the
union of the ACL rights required for UID STORE and UID EXPUNGE in the 
current mailbox, and APPEND in the target mailbox.
</t>
</section>
<section anchor="RFC4469interact" title="RFC 4469, CATENATE">
<t>
Servers supporting both REPLACE and CATENATE <xref target="RFC4469"/> MUST support
the addtional append-data and resp-text-code elements defined the 
Formal Syntax section of RFC4469 in conjunction with the REPLACE 
command. When combined with CATENATE, REPLACE can become a quite efficient way
for message manipulation.
<figure>
<artwork>
Example:

  User composes message and attaches photo
  ----------------------------------------
  C: A010 APPEND Drafts (\Seen \Draft) {1201534}
  S: + Ready for literal data
  C: Date: Thu, 1 Jan 2015 00:10:00 -0500 (EST)
  C: From: Fritz Schmidt <fritz.ze@example.org>
  C: Message-ID: <B238822388-0100003@example.org>
  C: MIME-Version: 1.0
  C: Content-Type: multipart/mixed;
  C:         boundary="------------030305060306060609050804"
  C:
  C: --------------030305060306060609050804
  C: Content-Type: text/plain; charset=utf-8; format=flowed
  C: Content-Transfer-Encoding: 7bit
  C: 
  C: Here is picture from the fireworks
  C: 
  C: Yours...
  C: Fritz
  C: 
  C: --------------030305060306060609050804
  C: Content-Type: image/jpeg;
  C:         name="Fireworks.jpg"
  C: Content-Transfer-Encoding: base64
  C: Content-Disposition: attachment;
  C:         filename="Fireworks.jpg"
  C:
    <large base64 encoded part goes here>
  C: 
  C: --------------030305060306060609050804--
  S: A010 OK [APPENDUID 1 3002] APPEND complete

  User completes message with To: and Subject: fields
  ---------------------------------------------------
  C: A011 UID REPLACE 3002 Drafts CATENATE (TEXT {71}
  S: + Ready for literal data
  C: To: Mitzy <miss.mitzy@example.org>
  C: Subject: My view of the fireworks
  C:  URL "/Drafts/;UID=3002")
  S: * 5 EXISTS
  S: * 4 EXPUNGE
  S: A011 OK [APPENDUID 1 3003] REPLACE completed
</artwork>
</figure>
</t>
</section>
<section anchor="RFC4315interact" title="RFC 4315, UIDPLUS">
<t>
Servers supporting both REPLACE and UIDPLUS <xref target="RFC4315"/> SHOULD send 
APPENDUID in response to a UID REPLACE command. For additional information
see section 3 of RFC4315.

Servers implementing REPLACE and UIDPLUS are also advised to send the 
APPENDUID response code in an untagged OK before sending the EXPUNGE or 
replaced responses. (Sending the APPENDUID in the tagged OK, as described
in the UIDPLUS specification means that the client first receives an
EXPUNGE for a message and afterwards APPENDUID for the new message.  
It can be unnecessarily difficult to process that sequence usefully.)
</t>
</section>
<section anchor="SieveInteract" title="RFC 6785, IMAP Events in Sieve">
<t>
REPLACE applies to IMAP events in Sieve <xref target="RFC6785"/> in the
same way that APPEND does. Therefore, REPLACE can cause a Sieve 
script to be invoked with the imap.cause set to "APPEND". Because 
the intermediate state of STORE +FLAGS.SILENT \DELETED is not 
exposed by REPLACE, no action will be taken that results in a
imap.cause of FLAG.
</t>
</section>
<section anchor="RFC7162interact" title="RFC 7162, CONDSTORE/QRESYNC">
<t>
Servers implementing both REPLACE and CONDSTORE/QRESYNC <xref target="RFC7162"/> MUST
treat the message being replaced as if it were being removed with 
a UID EXPUNGE command. Sections 3.2.9 and 3.2.10 of RFC 7162 are 
particularly relevant for this condition.
</t>
</section>
</section>
<section title="Formal Syntax"> 
<t>
The following syntax specification uses the Augmented Backus-Naur 
Form (ABNF) notation as specified in <xref target="RFC5234"/>. <xref target="RFC3501"/> 
defines the non-terminals "capability","command-select", "mailbox", 
and "seq-number".  <xref target="RFC4466"/> defines the non-terminal "append-message".
</t>
<t>
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.
</t>
<figure>
<artwork type="ABNF">
capability     =/ "REPLACE"

command-select =/ replace
replace        = "REPLACE" SP seq-number SP mailbox append-message
uid            = "UID" SP (copy / fetch/ search / store / move /
                           replace)

</artwork>
</figure>
</section> 
<section title="Security Considerations"> 
<t>This document is believed to add no security problems beyond 
those that may already exist with the base IMAP specificaiton.
</t>
</section> 
<section title="IANA Considerations"> 
<t>The IANA is requested to add REPLACE to the
"IMAP 4 Capabilities" registry,
http://www.iana.org/assignments/imap4-capabilities.
</t>
</section> 
<section title="Acknowledgements"> 
<t>
The author would like to thank the participants of IMAPEXT with
particular thanks to Arnt Gulbrandsen, Alexey Melkinov, and Chris Newman 
for their specific contributions.
</t>
</section> 
</middle>

<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119" ?>
<?rfc include="reference.RFC.3501" ?>
<?rfc include="reference.RFC.4314" ?>
<?rfc include="reference.RFC.4315" ?>
<?rfc include="reference.RFC.4466" ?>
<?rfc include="reference.RFC.4469" ?>
<?rfc include="reference.RFC.5234" ?>
<?rfc include="reference.RFC.6785" ?>
<?rfc include="reference.RFC.7162" ?>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.6851" ?>
</references>

</back>
</rfc>