<abstract>This document defines an XMPP protocol extension that enables entities to request, and servers to perform, advanced processing of XMPP <message/> stanzas, including reliable data transport, time-sensitive delivery, and transient messages.</abstract>
<remark>Specified that the timestamp for an expire-at condition must be a UTC DateTime per XEP-0082; provided further explanation regarding expire-at and expire-in conditions.</remark>
<remark>Changes to address Council feedback: clarified error handling and provided error examples; specified that server should validate all rule semantics before returning an error; specified that service discovery information can be cached (not necessary to send disco query before dispatching each message); added "forward" and "gateway" to values of "deliver" condition to handle redirection of messages to alternate XMPP addresses and non-XMPP systems respectively; more clearly specified processing rules for "expire-in" condition; changed milliseconds to seconds for "expire-in"; made explicit that partial JID-matching is not included for "match-resource" condition; added clarifying note to security consideration regarding "deliver" condition; corrected values of per-hop from [yes|no] to [true|false]; changed "standard" conditions to "defined" conditions and mandated that they should be supported; changed "http://jabber.org/protocol/amp#std-actions" namespace to "http://jabber.org/protocol/amp#errors".</remark>
<remark>Incorported changes requested from Standards list discussions: Changed entity-to-server discovery behavior; s2s discovery behavior; Expanded application-specific error conditions; Reorganized for better presentation; Changed "per-hop" to apply to the entire ruleset; Fixed minor typos and missteps</remark>
<remark>Changed disco behavior; Changed schema to reflect customizations</remark>
</revision>
<revision>
<version>0.5.1</version>
<date>2003-09-20</date>
<initials>lw</initials>
<remark>Fixed many typos</remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-08-28</date>
<initials>lw</initials>
<remark>Renamed to "amp" (thanks stpeter!); Added information about the original addressing; Added requirement for id attribute in &MESSAGE;; Restricted behavior within the "Security Considerations";</remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-06-23</date>
<initials>lw</initials>
<remark>Completely rewritten to better account for various suggested usage details and requirements; Completely reorganized to better codify the protocol(s) and their possible uses; Added more conditions; Added more actions; Added common usage scenarios</remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-04-21</date>
<initials>lw</initials>
<remark>Clarified client-side processing; Removed semantics scope; Clarified "fail" action; Moved existing "use-cases" into "Usage" section in "Overview"; Added more relevant use cases; Added XMPP-style error conditions</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-04-15</date>
<initials>psa</initials>
<remark>Added XML Schema (with author's assistance).</remark>
<p>This document defines a protocol that enables an end-point entity to specify additional delivery semantics for an XMPP <message/> stanza. This protocol is typically used by clients to inform the receiving server how to deliver a particular stanza, such as providing an expiration time or a resource-matching strategy.</p>
<p>The built-in delivery semantics for <message/> stanzas (defined in &xmppcore; and, for instant messaging applications, also in &xmppim;) are adequate for most current applications. However, there are various cases where more stringent delivery semantics are necessary. The most common cases discussed in this document are:</p>
<li>Reliable data transport -- the sender requires notification (positive and/or negative) of message delivery.</li>
<li>Time-sensitive messages -- the message is valid only until a certain date and time.</li>
<li>Transient messages -- the message should not be stored offline for later delivery.</li>
</ul>
</section2>
<section2topic='Concepts'anchor='intro-concepts'>
<p>This protocol is mostly handled by the server or servers processing the <message/>. The protocol consists of a list of rules, with conditions and actions for each rule. Upon receipt of an appropriately marked message, the server interprets the rules in the order they are received, looking for met conditions. When a condition is met, the action for that rule is executed, and message processing stops.</p>
<p>Each rule is flagged for the scope it applies to, whether it be the overall route, or for each hop in the route. Additionally, while this document defines a default set of conditions and actions, the protocol is extensible enough to allow for more to be defined in the future.</p>
<p>In order for this protocol to function properly, the containing &MESSAGE; stanza MUST possess an 'id' attribute, and the value of the 'id' attribute MUST NOT be an empty string. The server MUST include this 'id' attribute value with any response back to the sender; this enables servers and clients to properly relate the initial request with any subsequent alert, error, or notification.</p>
<p>The following use case flow describes the interaction between the sender and a server. As illustrated below, this interaction is actually rather simple:</p>
<p>Sending entities that wish to use AMP SHOULD discover support for this protocol (using &xep0030;) along the intended path. Typically, this would involve sending disco#info queries to the sending entity's own server and the server of the intended recipient. The results of these queries MAY be cached for up to 24 hours, unless otherwise expired.</p>
<p>If a server supports Advanced Message Processing, it MUST report that by including a service discovery feature of "http://jabber.org/protocol/amp" in the service discovery information result that it returns to the requesting entity.</p>
<examplecaption="Initial Service Discovery information request"><![CDATA[
<p>A server SHOULD also maintain a service discovery node named "http://jabber.org/protocol/amp", at which it advertises the individual actions and conditions it supports. If an entity needs to determine whether the server supports individual actions and conditions, it SHOULD send a service discovery information request to that node; the server then MUST either return the list of supported actions and conditions or return an error such as &feature;. (Note: If the server does not provide information for this disco node, the requesting entity MUST assume that all actions and conditons are supported for each reported action set or condition set.)</p>
<p>Each supported action shall be reported as a feature using the following format:</p>
<p>The following examples show the request-response flow for information about individual actions and conditions (note the inclusion of the 'node' attribute).</p>
<examplecaption="Request for information about individual actions and conditions"><![CDATA[
<p>Once support is determined, the sender can attach the desired delivery semantics to the message:</p>
<examplecaption='A message with AMP semantics'><![CDATA[
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<body>My lord, dispatch; read o'er these articles.</body>
<ampxmlns='http://jabber.org/protocol/amp'>
<rulecondition='expire-at'
action='drop'
value='2004-01-01T00:00:00Z'/>
</amp>
</message>
]]></example>
<p>The semantics are defined as a set of <rule/> elements within the <amp/> root element. Each <rule/> declares the condition to trigger on and the action to execute if triggered.</p>
<p>By default, the ruleset applies only to the "edge servers": those servers to which the sending and receiving entities are connected. (Note: For the purposes of Advanced Message Processing, "server" is defined as in <cite>XMPP Core</cite> and does not include any internal components, such as connection managers, that may provide functionality within a server implementation or installation.)</p>
<p>The ruleset MAY be applied to all server-to-server "hops" along the route from the sending and receiving entities by adding the "per-hop' attribute to the <amp/> element. The value of this attribute is either "true" (apply rules to all hops) or "false" (follow default behavior, i.e., apply rules at the edge servers only).</p>
<examplecaption='Another message with AMP semantics'><![CDATA[
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<body>My lord, dispatch; read o'er these articles.</body>
<ampxmlns='http://jabber.org/protocol/amp'
per-hop='true'>
<rulecondition='expire-at'
action='drop'
value='2004-01-01T00:00:00Z'/>
</amp>
</message>
]]></example>
<p>For examples of validation failure, refer to the <linkurl="#errors">Error Handling</link> section of this document.</p>
<p>Note: Even if "per-hop" processing is requested, each server in the route MUST ignore rules that cannot apply to it; the <linkurl="#conditions-def">Defined Conditions</link> outline if they can be applied per-hop.</p>
<p>Server operation is where the bulk of the work is performed. Upon receiving a message with an AMP extension, the server performs the following flow:</p>
<p>Validation can take many forms, but at the very least the server MUST verify that it understands each of the rule conditions and actions, and that the condition contents are appropriate. The server MAY also refuse to accept certain combinations of conditions and actions, for example if they present a risk of violating security policies. If the semantics are not valid, supported, or acceptable, the server MUST reply with an error specifying the rule(s) that are at issue. The server SHOULD validate all the semantics before returning an error. For syntax and examples of error handling related to validation failure, refer to the <linkurl="#errors">Error Handling</link> section of this document.</p>
<p>This step is essentially what a server normally does, except that it does not actually perform the action. This determines what would happen to the message if there were no semantics attached (such as dispatch to another server or store offline). At this point, the server SHOULD also calculate any timing or calendar requirements (if applicable).</p>
<p>At this step, the server processes the attached semantics. The server MUST process the rules serially, and in the order they are presented within the <amp/> element. As soon as a rule's condition is met, processing ends with that action overriding the default action determined earlier (unless the action permits continued processing).</p>
<p>Once all rules have been processed or otherwise accounted for, the server executes the action determined at this point.</p>
<p>A server SHOULD NOT dispatch a &MESSAGE; stanza with AMP semantics to another server unless it knows that the next server supports AMP (this SHOULD be discovered via <cite>Service Discovery</cite> and MAY be cached to avoid delivery delays). If the next server does not support AMP, the current server replies to the original sender with a &e503; error condition. Otherwise this flow starts again for the server to which the message has been dispatched.</p>
<p>If the determined action involves returning an event (alert, error, or notification) to the sender, a server MUST send a &MESSAGE; stanza to the sender containing the rule that was met. This &MESSAGE; stanza MUST include the original value of the 'id' attribute and SHOULD NOT contain the non-AMP contents (e.g., &BODY; child) originally included by the sender.</p>
</section3>
</section2>
</section1>
<section1topic='Conditions and Actions'anchor='conditionsactions'>
<p>The preceding sections of this document define the general behavior regarding AMP. This section outlines how <rule/> action and condition sets are specified. It also provides defined action and condition sets; these action and condition sets SHOULD be supported by any implementation of Advanced Message Processing, but support for any given action or condition set it not required. (Note: The action and condition sets defined herein may be supplemented in the future via registration of additional action and condition sets with the XMPP Registrar.)</p>
<p>The condition defines how or when a particular rule is triggered. The value of the condition attribute determines what the contents of the <rule/> mean.</p>
<p>The "expire-at" condition is used to ensure delivery before an absolute point in time. Naturally, this does not <em>guarantee</em><note>Guarantee is a strong word. This document defines methods for making message delivery more reliable within certain bounds, but does not pretend that such methods provide any form of guaranteed delivery.</note> that the message will not be delivered after that time from the sender's perspective, since this document does not assume that all machine clocks (e.g., for all servers along the delivery route) are synchronized. However, in order to help ensure that this condition is met correctly, servers that implement this document (or the machines that host such servers) SHOULD use the Network Time Protocol (&rfc1305;) to keep in sync with established time authorities. Note also that expire-at functionality becomes less reliable the closer the expire-at time is to the present (e.g., the sender will receive less reliable delivery of a message speciifying an expire-at time two seconds in the future than of a message specifying an expire-at time two hours or two days in the future).</p>
<p>The content of the 'value' attribute specifies some point after the exact moment the message is sent; the content MUST be a DateTime as specified in &xep0082;, and the timezone MUST be UTC.</p>
<p>The condition is met if the message would be delivered to the recipient after the specified datetime. To determine the datetime to compare to, the processor first determines if and when a message can be dispatched (e.g. not stored offline). The processor then records this datetime, and compares it with the specified datetime. If the current datetime is on or after that specified, the condition is met.</p>
<p>This condition MAY be applied to each "hop" in the server route.</p>
<p>The "match-resource" condition is used to restrict delivery based on the resource identifier of the recipient JID.</p>
<p>The defined values for this condition are:</p>
<tablecaption='"match-resource" values'>
<tr>
<th>Value</th>
<th>Description</th>
<th>Example</th>
</tr>
<tr>
<td>any</td>
<td>Destination resource matches any value, effectively ignoring the intended resource.</td>
<td>"home/laptop" matches "home", "home/desktop" or "work/desktop"</td>
</tr>
<tr>
<td>exact</td>
<td>Destination resource exactly matches the intended resource.</td>
<td>"home/laptop" only matches "home/laptop" and not "home/desktop" or "work/desktop"</td>
</tr>
<tr>
<td>other</td>
<td>Destination resource matches any value except for the intended resource.</td>
<td>"home/laptop" matches "work/desktop", "home" or "home/desktop", but not "home/laptop"</td>
</tr>
</table>
<p>The condition is met if the resource for the actual destination JID matches the intended JID using the above rules. For instance, if a message is intended for "romeo@montague.net/work" with the "match-resource" condition of "exact", the condition is met if the message can be immediately delivered only to "romeo@montague.net/work".</p>
<p>For purposes of this condition, an intended JID with no resource has the following behavior:</p>
<li>If the value is "exact", the condition is met only if the server would deliver to a destination JID without a resource identifier (e.g., a &xep0045; room or offline storage).</li>
<li>If the value is "other", the condition is met only if the server would not deliver to a destination JID without a resource identifier.</li>
</ul>
<p>This condition MUST NOT be applied to each "hop" in the server route, only at the edge servers. If an <amp/> element includes this condition and also indicates that it should be processed per hop, this <rule/> shall be ignored.</p>
<p>Note: By design, this protocol does not include support for partial resource matching (which would stipulate, for example, that the resource identifiers "home/laptop" and "homeboy" both match "home").</p>
<p>The action defines what occurs when a particular rule is triggered. The value of the action attribute determines the behavior if the rule's condition is met.</p>
<p>The "alert" action triggers a reply &MESSAGE; stanza to the sending entity. This &MESSAGE; stanza MUST contain the element <amp status='alert'/>, which itself contains the <rule/> that triggered this action. In all other respects, this action behaves as "drop".</p>
<p>The "drop" action silently discards the message from any further delivery attempts and ensures that it is not placed into offline storage. The drop MUST NOT result in other responses.</p>
</section3>
<section3topic='error'anchor='actions-def-error'>
<p>The "error" action triggers a reply &MESSAGE; stanza of type "error" to the sending entity. The &MESSAGE; stanza's <error/> child MUST contain a <failed-rules xmlns='http://jabber.org/protocol/amp#errors'/> error condition, which itself contains the rules that triggered this action.</p>
<p>Note that the error SHOULD be of type "modify", and the general error condition SHOULD be <undefined-condition xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>.</p>
<p>The "notify" action triggers a reply &MESSAGE; stanza to the sending entity. This &MESSAGE; stanza MUST contain the element <amp status='notify'/>, which itself contains the <rule/> that triggered this action. Unlike the other actions, this action does not override the default behavior for a server. Instead, the server then executes its default behavior after sending the notify.</p>
<section2topic='Description of Condition/Action Combinations'anchor='description'>
<p>In general, a rule can be read as "do {action} if {condition} is true for {value}"; however, to facilitate understanding, this section describes the various condition/action combinations in plain English.</p>
<p>All delivery semantics are encapsulated in the <amp/> element. This element contains one or more <rule/> elements specifying the specific rules to process. It can optionally possess attributes about the current status, the original sender and recipient, and route applicability.</p>
<p>The 'status' attribute specifies the reason for this <amp/> element. When specifying semantics to be applied (client to server), this attribute MUST NOT be present. When replying to a sending entity regarding a met condition, this attribute MUST be present and SHOULD be the value of the 'action' attribute for the triggered rule. (Note: Individual action definitions MAY provide their own requirements.)</p>
<p>The 'from' attribute specifies the original sender of the containing &MESSAGE; stanza. This attribute MUST be specified for any &MESSAGE; stanza sent from a supporting server, regardless of the recipient. It SHOULD NOT be specified otherwise. The value of the 'from' attribute MUST be the full JID (node@domain/resource) of the sender for the original &MESSAGE; stanza.</p>
<p>The 'to' attribute specifies the original (intended) recipient of the containing &MESSAGE; stanza. This attribute MUST be specified for any &MESSAGE; stanza sent from a supporting server, regardless of the recipient. It SHOULD NOT be specified otherwise. The value of the 'to' attribute MUST be the full JID (node@domain/resource) of the intended recipient for the original &MESSAGE; stanza.</p>
<p>The 'per-hop' attribute flags the contained ruleset for processing at each server in the route between the original sender and original intended recipient. This attribute MAY be present, and MUST be either "true" or "false". If not present, the default is "false".</p>
<p>The 'action' attribute defines the result for this rule. This attribute MUST be present, and MUST be either a value defined in the <linkurl="#actions-def">Defined Actions</link> section, or one registered with the XMPP Registrar.</p>
<p>The 'condition' attribute defines the overall condition this rule applies to. This attribute MUST be present, and MUST be either a value defined in the <linkurl="#conditions-def">Defined Conditions</link> section, or one registered with the XMPP Registrar.</p>
<p>The 'value' attribute defines how the condition is matched. This attribute MUST be present, and MUST NOT be an empty string (""). The interpretation of this attribute's value is determined by the 'condition' attribute.</p>
<p>The &MESSAGE; stanza is nearly ideal for data transport, but to ensure reliability it is often desirable that such messages not be delivered to any resource but that specified. To facilitate this, the sending entity includes a <rule action='drop' condition='match-resource' value='other'/> (if failure notification is unnecessary) or <rule action='error' condition='match-resource' value='other'/> (if failure notification is required). The following example illustrates this using &xep0047;:</p>
<p>In the above case, the sender would receive an error reply if the message could not be delivered specifically to "francisco@hamlet.lit/pda" by the specified time. For example, if the intended resource went offline before the message could be delivered, the processing server would return the following error:</p>
<examplecaption='Failed reliable data transport message'><