Browse Source

XEP-0395: accept inbox/cap.xml as Experimental

Jonas Wielicki 1 year ago
parent
commit
26dbfb3ec0
1 changed files with 282 additions and 0 deletions
  1. 282
    0
      xep-0395.xml

+ 282
- 0
xep-0395.xml View File

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

Loading…
Cancel
Save