aboutsummaryrefslogtreecommitdiff
path: root/inbox/cap.xml
blob: 92dfd0310f4a20ea88f93172179fbd2904ea3d4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
<?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>