No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0395.xml 9.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Atomically Compare-And-Publish PubSub Items</title>
  10. <abstract>This specification provides a mechanism to atomically Compare-And-Publish items to a PubSub node.</abstract>
  11. &LEGALNOTICE;
  12. <number>0395</number>
  13. <status>Experimental</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <approver>Council</approver>
  17. <dependencies>
  18. <spec>XEP-0030</spec>
  19. <spec>XEP-0060</spec>
  20. </dependencies>
  21. <supersedes/>
  22. <supersededby/>
  23. <shortname>cap</shortname>
  24. &flow;
  25. <revision>
  26. <version>0.1</version>
  27. <date>2017-11-29</date>
  28. <initials>XEP Editor (jwi)</initials>
  29. <remark><p>Accepted by Council as Expremental XEP</p></remark>
  30. </revision>
  31. <revision>
  32. <version>0.0.3</version>
  33. <date>2017-10-06</date>
  34. <initials>fs</initials>
  35. <remark><p>Use a custom item value (CAP-V).</p></remark>
  36. </revision>
  37. <revision>
  38. <version>0.0.2</version>
  39. <date>2017-08-25</date>
  40. <initials>fs</initials>
  41. <remark><p>Use PubSub publish-options preconditions.</p></remark>
  42. </revision>
  43. <revision>
  44. <version>0.0.1</version>
  45. <date>2017-04-20</date>
  46. <initials>fs</initials>
  47. <remark><p>First draft.</p></remark>
  48. </revision>
  49. </header>
  50. <section1 topic='Introduction' anchor='intro'>
  51. <p>This specification provides a mechanism to atomically publish
  52. items to a PubSub node depending on the item ID of the node's latest
  53. item. This allows to prevent race conditions and avoids data
  54. loss in certain situations.</p>
  55. </section1>
  56. <section1 topic='Discoverying Support' anchor='disco'>
  57. <p>If an entity supports the Compared-And-Publish feature it MUST
  58. advertise the fact by returning a &lt;feature/&gt; with the 'var'
  59. attribute set to 'urn:xmpp:pubsub:cap:0' in response to a &xep0030;
  60. query for information.</p>
  61. </section1>
  62. <section1 topic='Compare-And-Publish PubSub Items' anchor='cap'>
  63. <section2 topic='PubSub Item Compare-And-Publish Value (CAP-V)' anchor='cap-v'>
  64. <p>PubSub services supporting the Compare-And-Publish PubSub extension MUST include a Comapre-and-Publish value
  65. (CAP-V) for every item in every response. The CAP-V value MUST change if the content of the item changed and
  66. different item content under the same node MUST NOT yield the same CAP-V. A simple computation of the CAP-ID would
  67. be to hash the String representation of the item's content.</p>
  68. <p>CAP-Vs are assoicated with PubSub node's items via the item ID. The maping information is placed by the PubSub
  69. service in a &lt;cap-v-map/&gt; extension element, qualified by the 'urn:xmpp:pubsub:cap:0' namespace, as child
  70. element of the &lt;items/&gt; element. The &lt;cap-v-map/&gt; element contains one or more &lt;cap-v-map-entry/&gt;
  71. elements, of which each MUST have a 'item-id' and a 'cap-value' attribute. The former contains the PubSub item ID
  72. value and the later contains the according CAP-V of the item.</p>
  73. <example caption='Service returns some items and their according CAP-Vs'><![CDATA[
  74. <iq type='result'
  75. from='pubsub.shakespeare.lit'
  76. to='francisco@denmark.lit/barracks'
  77. id='items1'>
  78. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  79. <items node='princely_musings'>
  80. <item id='368866411b877c30064a5f62b917cffe'>
  81. <entry xmlns='http://www.w3.org/2005/Atom'>
  82. <title>The Uses of This World</title>
  83. <summary>
  84. O, that this too too solid flesh would melt
  85. Thaw and resolve itself into a dew!
  86. </summary>
  87. </entry>
  88. </item>
  89. <item id='3300659945416e274474e469a1f0154c'>
  90. <entry xmlns='http://www.w3.org/2005/Atom'>
  91. <title>Ghostly Encounters</title>
  92. <summary>
  93. O all you host of heaven! O earth! what else?
  94. And shall I couple hell? O, fie! Hold, hold, my heart;
  95. And you, my sinews, grow not instant old,
  96. But bear me stiffly up. Remember thee!
  97. </summary>
  98. </entry>
  99. </item>
  100. <item id='4e30f35051b7b8b42abe083742187228'>
  101. <entry xmlns='http://www.w3.org/2005/Atom'>
  102. <title>Alone</title>
  103. <summary>
  104. Now I am alone.
  105. O, what a rogue and peasant slave am I!
  106. </summary>
  107. </entry>
  108. </item>
  109. <cap-v-map xmlns='urn:xmpp:pubsub:cap:0'>
  110. <cap-value-map-entry
  111. item-id='368866411b877c30064a5f62b917cffe'
  112. cap-value='35a204c2-5d6c-43a2-8e0d-a235a627b04a'/>
  113. <cap-value-map-entry
  114. item-id='3300659945416e274474e469a1f0154c'
  115. cap-value='166b7c04-ed4d-4872-aa56-a58268da84e2'/>
  116. <cap-value-map-entry
  117. item-id='4e30f35051b7b8b42abe083742187228'
  118. cap-value='67f7f792-f2ee-4918-8894-36a3c4a6dd5f'/>
  119. </cap-v-map>
  120. </items>
  121. </pubsub>
  122. </iq>
  123. ]]></example>
  124. </section2>
  125. <section2 topic='PubSub publishing using Compare-And-Publish'>
  126. <p>In order to atomically compare-and-publish an item, a client sends a <cite>XEP-0060</cite> &lt;publish/&gt; IQ
  127. with a 'pubsub#prev_item_cap_value' precondition publishing option, set to the value of the currently assumed CAP-V
  128. of the latest item of the node.</p>
  129. <p>The PubSub service MUST only publish the item if the node's latest item CAP-V is equal to the
  130. CAP-V found in the 'pubsub#prev_item_cap_value' field.</p>
  131. <example caption='Atomically publishing with Compare-And-Publish'><![CDATA[
  132. <iq type='set'
  133. from='hamlet@denmark.lit/blogbot'
  134. to='pubsub.shakespeare.lit'
  135. id='pub1'>
  136. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  137. <publish node='princely_musings'>
  138. <item id='2'>
  139. <entry xmlns='https://example.org'>
  140. <title>Soliloquy</title>
  141. <summary>
  142. To be, or not to be: that is the question:
  143. Whether 'tis nobler in the mind to suffer
  144. The slings and arrows of outrageous fortune,
  145. Or to take arms against a sea of troubles,
  146. And by opposing end them?
  147. </summary>
  148. </entry>
  149. </item>
  150. </publish>
  151. <publish-options>
  152. <x xmlns='jabber:x:data' type='submit'>
  153. <field var='FORM_TYPE' type='hidden'>
  154. <value>http://jabber.org/protocol/pubsub#publish-options</value>
  155. </field>
  156. <field var='pubsub#prev_item_cap_value'>
  157. <value>1</value>
  158. </field>
  159. </x>
  160. </publish-options>
  161. </pubsub>
  162. </iq>
  163. ]]></example>
  164. </section2>
  165. <section2 topic='Could not publish because newest item ID did not match'>
  166. <p>In case the Compare-And-Publish operation failed because the latest node id is not the same
  167. as given in the 'previd' attribute in the request, the server returns an &lt;conflict/&gt; error
  168. of type 'modify' which a pubsub-specific condition of &lt;precondition-not-met/&gt; and a
  169. &lt;compare-and-publish-failed/&gt; element qualifed by the 'urn:xmpp:pubsub:cap:0'
  170. namespace. The element MUST have a 'cap-id' attribute with the CAP-V of the lastest item.</p>
  171. <example caption='Service returns IQ response notifying of failed Compare-And-Publish operation'><![CDATA[
  172. <iq type='error'
  173. from='pubsub.shakespeare.lit'
  174. to='hamlet@denmark.lit/elsinore'
  175. id='retract1'>
  176. <error type='modify'>
  177. <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  178. <precondition-not-met xmlns='http://jabber.org/protocol/pubsub#errors'/>
  179. <compare-and-publish-failed xmlns='urn:xmpp:pubsub:cap:0' cap-id='2'/>
  180. </error>
  181. </iq>
  182. ]]></example>
  183. </section2>
  184. </section1>
  185. <section1 topic='Rationale' anchor='rationale'>
  186. <p>Unfortunately it was not possible to re-use the PubSub item ID for the "Atomically
  187. Compare-And-Publish" purpose. This is mostly due <cite>XEP-0060 § 12.8</cite> stating that:</p>
  188. <p class='box'>
  189. "If a publisher publishes an item and the ItemID
  190. matches that of an existing item, the pubsub service MUST overwrite the existing item and generate a new event
  191. notification."
  192. </p>
  193. <p> Which means that the content of an item could change without its ID, rendering the item ID
  194. unusable for CAP. </p>
  195. <p>Injecting a "cap"-namespaced attribute carrying the item's CAP-V into PubSub's &lt;item/&gt;
  196. would be a very elegant approach to assign CAP-Vs to PubSub items (and the favored one of the
  197. XEP's author). But the usage of namespaces attributes within XMPP is controversial. Therefore this
  198. XEP resorts to using the &lt;cap-v-map/&gt; approach for now.</p>
  199. </section1>
  200. <section1 topic='Security Considerations' anchor='security'>
  201. <p>This extension protocol does not add any further security considerations to the ones mentioned
  202. in <cite>XEP-0060 § 14.</cite>.</p>
  203. </section1>
  204. <section1 topic='IANA Considerations' anchor='iana'>
  205. <p>This document requires no interaction with the Internet Assigned
  206. Numbers Authority (IANA).</p>
  207. </section1>
  208. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  209. <p>This specification defines the following XML namespaces:</p>
  210. <ul>
  211. <li>urn:xmpp:pubsub:cap:0</li>
  212. </ul>
  213. <code caption='Registry Submission'><![CDATA[
  214. <var>
  215. <name>urn:xmpp:pubsub:cap:0</name>
  216. <desc>Indicates support for Compare-And-Publish</desc>
  217. <doc>XEP-XXXX</doc>
  218. </var>]]></code>
  219. <p>This specification defines the following &lt;publish-options/&gt; fields:</p>
  220. <ul>
  221. <li>pubsub#prev_item_cap_value</li>
  222. </ul>
  223. <code caption='Registry Submission'><![CDATA[
  224. <field var='pubsub#prev_item_cap_value'
  225. type='text-single'
  226. label='Precondition: The assumed value of the latest item&apos; CAP-V of the node'/>]]></code>
  227. </section1>
  228. <section1 topic='XML Schema' anchor='schema'>
  229. <p>TODO: Add after the XEP leaves the 'experimental' state.</p>
  230. </section1>
  231. <section1 topic='Acknowledgements' anchor='acknowledgements'>
  232. <p>Thanks to Kim Alvefur and Dave Cridland for their feedback.</p>
  233. </section1>
  234. </xep>
  235. <!-- Local Variables: -->
  236. <!-- fill-column: 100 -->
  237. <!-- indent-tabs-mode: nil -->
  238. <!-- End: -->