Merge branch 'pubsub-compare-and-publish' of into feature/protoxep-pubsub-cap

This commit is contained in:
Jonas Wielicki 2017-08-23 16:40:14 +02:00
commit f68cd2e146
1 changed files with 169 additions and 0 deletions

inbox/cap.xml Normal file
View File

@ -0,0 +1,169 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<title>Atomically Compare-And-Publish PubSub Items</title>
<abstract>This specification provides a mechanism to atomically Compare-And-Publish items to a PubSub node.</abstract>
<type>Standards Track</type>
<remark><p>First draft.</p></remark>
<section1 topic='Introduction' anchor='intro'>
<p>This specification provides a mechanism to atomically publish
items to a PubSub node depending on the item ID of the node's latest
item. This allows to prevent race conditions and avoids data
loss in certain situations.</p>
<section1 topic='Discoverying Support' anchor='disco'>
<p>If an entity supports the Compared-And-Publish feature it MUST
advertise the fact by returning a &lt;feature/&gt; with the 'var'
attribute set to 'urn:xmpp:pubsub:cap:0' in response to a &xep0030;
query for information.</p>
<section1 topic='Compare-And-Publish PubSub Items' anchor='cap'>
<p>In order to atomically compare-and-publish an item, a client
sends an &IQ; with a 'pubsub' element qualified by the
'urn:xmpp:pubsub:cap:0' namespace. The element MUST contain the same
attributes and elements as the &lt;publish/&gt; element defined in
&xep0060; <em>and</em> it MUST contain a previd attribute containing
an item ID.</p>
<p>The PubSub service MUST only publish the item if the node's
latest item ID is equal to the ID found in the 'previd'
<example caption='Publisher publishes an item using Compare-And-Publish'><![CDATA[
<iq type='set'
<pubsub xmlns='urn:xmpp:pubsub:cap:0'>
<entry xmlns=''>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
<link rel='alternate' type='text/html'
<section2 topic='Successfully published an item using Compare-And-Publish'>
<p>If the 'previd' matched the latest item's ID and if the service
was able to successfully process the request then the protocol
continues as defined in <cite>XEP-0060 7.1.2</cite>.</p>
<section2 topic='Could not publish because newest item ID did not match'>
<p>In case the Compare-And-Publish operation failed because the
latest node id is not the same as given in the 'previd' attribute
in the request, the server returns an &IQ; result with 'pubsub'
element qualified by the 'urn:xmpp:pubsub:cap:0' namespace which
contains a &lt;compare-and-publish-failed/&gt; element. The
element MUST have a 'id' attribute with the ID of the lastest
<example caption='Service returns IQ response notifying of failed Compare-And-Publish operation'><![CDATA[
<iq type='result'
<pubsub xmlns='urn:xmpp:pubsub:cap:0'>
<compare-and-publish-failed id='2'/>
<section2 topic='Error cases'>
<p>All other error cases are handled as specified in
<cite>XEP-0060 § 7.1.3</cite></p>
<section1 topic='Security Considerations' anchor='security'>
<p>This extension protocol does not add any further security
considerations to the ones mentioned in <cite>XEP-0060 §
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with the Internet Assigned
Numbers Authority (IANA).</p>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>This specification defines the following XML namespaces:</p>
<code caption='Registry Submission'><![CDATA[
<desc>Indicates support for Compare-And-Publish</desc>
<section1 topic='XML Schema' anchor='schema'>
<p>TODO: Add after the XEP leaves the 'experimental' state.</p>