xeps/inbox/cap.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <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>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XEP-0030</spec>
    <spec>XEP-0060</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>cap</shortname>
  &flow;
  <revision>
    <version>0.0.1</version>
    <date>2017-04-20</date>
    <initials>fs</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<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>

<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>

<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'
  attribute.</p>

  <example caption='Publisher publishes an item using Compare-And-Publish'><![CDATA[
<iq type='set'
    from='hamlet@denmark.lit/blogbot'
    to='pubsub.shakespeare.lit'
    id='compare-and-publish1'>
  <pubsub xmlns='urn:xmpp:pubsub:cap:0'>
    <compare-and-publish
        node='princely_musings'
        previd='1'>
      <item>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Soliloquy</title>
          <summary>
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?
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32397</id>
          <published>2003-12-13T18:30:02Z</published>
          <updated>2003-12-13T18:30:02Z</updated>
        </entry>
      </item>
    </publish>
  </pubsub>
</iq>
]]></example>

  <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>

  <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
    item.</p>

   <example caption='Service returns IQ response notifying of failed Compare-And-Publish operation'><![CDATA[
<iq type='result'
    from='pubsub.shakespeare.lit'
    to='hamlet@denmark.lit/blogbot'
    id='compare-and-ublish1'>
  <pubsub xmlns='urn:xmpp:pubsub:cap:0'>
    <compare-and-publish-failed id='2'/>
  </pubsub>
</iq>
]]></example>

  </section2>

  <section2 topic='Error cases'>

    <p>All other error cases are handled as specified in
    <cite>XEP-0060 § 7.1.3</cite></p>

  </section2>

</section1>

<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 §
  14.</cite>.</p>

</section1>

<section1 topic='IANA Considerations' anchor='iana'>

  <p>This document requires no interaction with the Internet Assigned
  Numbers Authority (IANA).</p>

</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>

  <p>This specification defines the following XML namespaces:</p>
  <ul>
    <li>urn:xmpp:pubsub:cap:0</li>
  </ul>
  	<code caption='Registry Submission'><![CDATA[
<var>
	<name>urn:xmpp:pubsub:cap:0</name>
	<desc>Indicates support for Compare-And-Publish</desc>
	<doc>XEP-XXXX</doc>
</var>]]></code>

</section1>
<section1 topic='XML Schema' anchor='schema'>

  <p>TODO: Add after the XEP leaves the 'experimental' state.</p>

</section1>
</xep>