moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-22 07:38:52 -05:00
Code Issues Releases Wiki Activity

Update inbox/cap.xml

Browse Source
This commit is contained in:
Florian Schmaus 2017-10-06 11:10:58 +02:00
parent 0071bdd205
commit f57b8ae7df
1 changed files with 160 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
inbox/cap.xml
View File

@ -22,6 +22,18 @@
<supersededby/> <supersededby/>
<shortname>cap</shortname> <shortname>cap</shortname>
&flow; &flow;
<revision>
<version>0.0.3</version>
<date>2017-10-06</date>
<initials>fs</initials>
<remark><p>Use a custom item value (CAP-V).</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2017-08-25</date>
<initials>fs</initials>
<remark><p>Use PubSub publish-options preconditions.</p></remark>
</revision>
<revision> <revision>
<version>0.0.1</version> <version>0.0.1</version>
<date>2017-04-20</date> <date>2017-04-20</date>
@ -50,28 +62,91 @@
<section1 topic='Compare-And-Publish PubSub Items' anchor='cap'> <section1 topic='Compare-And-Publish PubSub Items' anchor='cap'>
<p>In order to atomically compare-and-publish an item, a client <section2 topic='PubSub Item Compare-And-Publish Value (CAP-V)' anchor='cap-v'>
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 <p>PubSub services supporting the Compare-And-Publish PubSub extension MUST include a Comapre-and-Publish value
latest item ID is equal to the ID found in the 'previd' (CAP-V) for every item in every response. The CAP-V value MUST change if the content of the item changed and
attribute.</p> different item content under the same node MUST NOT yield the same CAP-V. A simple computation of the CAP-ID would
be to hash the String representation of the item's content.</p>
<example caption='Publisher publishes an item using Compare-And-Publish'><![CDATA[ <p>CAP-Vs are assoicated with PubSub node's items via the item ID. The maping information is placed by the PubSub
service in a &lt;cap-v-map/&gt; extension element, qualified by the 'urn:xmpp:pubsub:cap:0' namespace, as child
element of the &lt;items/&gt; element. The &lt;cap-v-map/&gt; element contains one or more &lt;cap-v-map-entry/&gt;
elements, of which each MUST have a 'item-id' and a 'cap-value' attribute. The former contains the PubSub item ID
value and the later contains the according CAP-V of the item.</p>
<example caption='Service returns some items and their according CAP-Vs'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='items1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='princely_musings'>
<item id='368866411b877c30064a5f62b917cffe'>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>The Uses of This World</title>
<summary>
O, that this too too solid flesh would melt
Thaw and resolve itself into a dew!
</summary>
</entry>
</item>
<item id='3300659945416e274474e469a1f0154c'>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Ghostly Encounters</title>
<summary>
O all you host of heaven! O earth! what else?
And shall I couple hell? O, fie! Hold, hold, my heart;
And you, my sinews, grow not instant old,
But bear me stiffly up. Remember thee!
</summary>
</entry>
</item>
<item id='4e30f35051b7b8b42abe083742187228'>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Alone</title>
<summary>
Now I am alone.
O, what a rogue and peasant slave am I!
</summary>
</entry>
</item>
<cap-v-map xmlns='urn:xmpp:pubsub:cap:0'>
<cap-value-map-entry
item-id='368866411b877c30064a5f62b917cffe'
cap-value='35a204c2-5d6c-43a2-8e0d-a235a627b04a'/>
<cap-value-map-entry
item-id='3300659945416e274474e469a1f0154c'
cap-value='166b7c04-ed4d-4872-aa56-a58268da84e2'/>
<cap-value-map-entry
item-id='4e30f35051b7b8b42abe083742187228'
cap-value='67f7f792-f2ee-4918-8894-36a3c4a6dd5f'/>
</cap-v-map>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='PubSub publishing using Compare-And-Publish'>
<p>In order to atomically compare-and-publish an item, a client sends a <cite>XEP-0060</cite> &lt;publish/&gt; IQ
with a 'pubsub#prev_item_cap_value' precondition publishing option, set to the value of the currently assumed CAP-V
of the latest item of the node.</p>
<p>The PubSub service MUST only publish the item if the node's latest item CAP-V is equal to the
CAP-V found in the 'pubsub#prev_item_cap_value' field.</p>
<example caption='Atomically publishing with Compare-And-Publish'><![CDATA[
<iq type='set' <iq type='set'
from='hamlet@denmark.lit/blogbot' from='hamlet@denmark.lit/blogbot'
to='pubsub.shakespeare.lit' to='pubsub.shakespeare.lit'
id='compare-and-publish1'> id='pub1'>
<pubsub xmlns='urn:xmpp:pubsub:cap:0'> <pubsub xmlns='http://jabber.org/protocol/pubsub'>
<compare-and-publish <publish node='princely_musings'>
node='princely_musings' <item id='2'>
previd='1'> <entry xmlns='https://example.org'>
<item>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Soliloquy</title> <title>Soliloquy</title>
<summary> <summary>
To be, or not to be: that is the question: To be, or not to be: that is the question:
@ -80,63 +155,73 @@ The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles, Or to take arms against a sea of troubles,
And by opposing end them? And by opposing end them?
</summary> </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> </entry>
</item> </item>
</publish> </publish>
<publish-options>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#publish-options</value>
</field>
<field var='pubsub#prev_item_cap_value'>
<value>1</value>
</field>
</x>
</publish-options>
</pubsub> </pubsub>
</iq> </iq>
]]></example> ]]></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>
<section2 topic='Could not publish because newest item ID did not match'> <section2 topic='Could not publish because newest item ID did not match'>
<p>In case the Compare-And-Publish operation failed because the <p>In case the Compare-And-Publish operation failed because the latest node id is not the same
latest node id is not the same as given in the 'previd' attribute as given in the 'previd' attribute in the request, the server returns an &lt;conflict/&gt; error
in the request, the server returns an &IQ; result with 'pubsub' of type 'modify' which a pubsub-specific condition of &lt;precondition-not-met/&gt; and a
element qualified by the 'urn:xmpp:pubsub:cap:0' namespace which &lt;compare-and-publish-failed/&gt; element qualifed by the 'urn:xmpp:pubsub:cap:0'
contains a &lt;compare-and-publish-failed/&gt; element. The namespace. The element MUST have a 'cap-id' attribute with the CAP-V of the lastest item.</p>
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[ <example caption='Service returns IQ response notifying of failed Compare-And-Publish operation'><![CDATA[
<iq type='result' <iq type='error'
from='pubsub.shakespeare.lit' from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/blogbot' to='hamlet@denmark.lit/elsinore'
id='compare-and-ublish1'> id='retract1'>
<pubsub xmlns='urn:xmpp:pubsub:cap:0'> <error type='modify'>
<compare-and-publish-failed id='2'/> <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</pubsub> <precondition-not-met xmlns='http://jabber.org/protocol/pubsub#errors'/>
<compare-and-publish-failed xmlns='urn:xmpp:pubsub:cap:0' cap-id='2'/>
</error>
</iq> </iq>
]]></example> ]]></example>
</section2> </section2>
<section2 topic='Error cases'> </section1>
<p>All other error cases are handled as specified in <section1 topic='Rationale' anchor='rationale'>
<cite>XEP-0060 § 7.1.3</cite></p>
</section2> <p>Unfortunately it was not possible to re-use the PubSub item ID for the "Atomically
Compare-And-Publish" purpose. This is mostly due <cite>XEP-0060 § 12.8</cite> stating that:</p>
<p class='box'>
"If a publisher publishes an item and the ItemID
matches that of an existing item, the pubsub service MUST overwrite the existing item and generate a new event
notification."
</p>
<p> Which means that the content of an item could change without its ID, rendering the item ID
unusable for CAP. </p>
<p>Injecting a "cap"-namespaced attribute carrying the item's CAP-V into PubSub's &lt;item/&gt;
would be a very elegant approach to assign CAP-Vs to PubSub items (and the favored one of the
XEP's author). But the usage of namespaces attributes within XMPP is controversial. Therefore this
XEP resorts to using the &lt;cap-v-map/&gt; approach for now.</p>
</section1> </section1>
<section1 topic='Security Considerations' anchor='security'> <section1 topic='Security Considerations' anchor='security'>
<p>This extension protocol does not add any further security <p>This extension protocol does not add any further security considerations to the ones mentioned
considerations to the ones mentioned in <cite>XEP-0060 § in <cite>XEP-0060 § 14.</cite>.</p>
14.</cite>.</p>
</section1> </section1>
@ -153,17 +238,39 @@ And by opposing end them?
<ul> <ul>
<li>urn:xmpp:pubsub:cap:0</li> <li>urn:xmpp:pubsub:cap:0</li>
</ul> </ul>
<code caption='Registry Submission'><![CDATA[ <code caption='Registry Submission'><![CDATA[
<var> <var>
<name>urn:xmpp:pubsub:cap:0</name> <name>urn:xmpp:pubsub:cap:0</name>
<desc>Indicates support for Compare-And-Publish</desc> <desc>Indicates support for Compare-And-Publish</desc>
<doc>XEP-XXXX</doc> <doc>XEP-XXXX</doc>
</var>]]></code> </var>]]></code>
<p>This specification defines the following &lt;publish-options/&gt; fields:</p>
<ul>
<li>pubsub#prev_item_cap_value</li>
</ul>
<code caption='Registry Submission'><![CDATA[
<field var='pubsub#prev_item_cap_value'
type='text-single'
label='Precondition: The assumed value of the latest item&apos; CAP-V of the node'/>]]></code>
</section1> </section1>
<section1 topic='XML Schema' anchor='schema'> <section1 topic='XML Schema' anchor='schema'>
<p>TODO: Add after the XEP leaves the 'experimental' state.</p> <p>TODO: Add after the XEP leaves the 'experimental' state.</p>
</section1> </section1>
<section1 topic='Acknowledgements' anchor='acknowledgements'>
<p>Thanks to Kim Alvefur and Dave Cridland for their feedback.</p>
</section1>
</xep> </xep>
<!-- Local Variables: -->
<!-- fill-column: 100 -->
<!-- indent-tabs-mode: nil -->
<!-- End: -->