One document matched: draft-brandt-imap-replace-00.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-00" 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="29" month="April" year="2015" />
    <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
           replacment 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>
Using commands from the base IMAP specification, replacement of a message
involves 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.  The REPLACE command is intended to provide an 
atomic alternative to the existing non-atomic sequence.
</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 an atomic 
encapsulation of STORE + UID EXPUNGE + APPEND. Servers that support 
the REPLACE command MUST guarantee atomicity; either the specified 
message is completely replaced by the supplied message, or the 
specified message is left unmodified and no part of the supplied 
message data is stored. Servers supporting REPLACE also MUST NOT 
infer any inheritance of content, flags, or annotations from the 
message being replaced.
</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. [UID] STORE +FLAGS.SILENT \DELETED
   2. UID EXPUNGE
   3. APPEND
</artwork>
</figure>
</t>
<t>
In the cited sequence, the original message is removed first to 
avoid possible quota implications of APPENDing new data first.
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 or 
modified state; any untagged EXPUNGE response MUST NOT be sent until
all actions are successfully completed. Additionally, the target 
mailbox MUST NOT be modified until all actions are successfully 
completed.
</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 command 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, UID EXPUNGE, and 
APPEND.
</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.
</t>
</section>
<section anchor="RFC4315interact" title="RFC 4315, UIDPLUS">
<t>
Servers supporting both REPLACE and UIDPLUS <xref target="RFC4315"/> MUST send 
APPENDUID in response to a UID REPLACE command. The only 
exceptions to this are the ones outlined for APPEND in RFC4315 
section 3.
</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>
</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>