diff --git a/xep-0395.xml b/xep-0395.xml new file mode 100644 index 00000000..4f92819d --- /dev/null +++ b/xep-0395.xml @@ -0,0 +1,282 @@ + + +%ents; +]> + + +
+ Atomically Compare-And-Publish PubSub Items + This specification provides a mechanism to atomically Compare-And-Publish items to a PubSub node. + &LEGALNOTICE; + 0395 + Experimental + Standards Track + Standards + Council + + XEP-0030 + XEP-0060 + + + + cap + &flow; + + 0.1 + 2017-11-29 + XEP Editor (jwi) +

Accepted by Council as Expremental XEP

 + + + 0.0.3 + 2017-10-06 + fs +

Use a custom item value (CAP-V).

 + + + 0.0.2 + 2017-08-25 + fs +

Use PubSub publish-options preconditions.

 + + + 0.0.1 + 2017-04-20 + fs +

First draft.

 + +
+ + + +

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.

+ + + + + +

If an entity supports the Compared-And-Publish feature it MUST + advertise the fact by returning a <feature/> with the 'var' + attribute set to 'urn:xmpp:pubsub:cap:0' in response to a &xep0030; + query for information.

+ + + + + + + +

PubSub services supporting the Compare-And-Publish PubSub extension MUST include a Comapre-and-Publish value + (CAP-V) for every item in every response. The CAP-V value MUST change if the content of the item changed and + 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.

+ +

CAP-Vs are assoicated with PubSub node's items via the item ID. The maping information is placed by the PubSub + service in a <cap-v-map/> extension element, qualified by the 'urn:xmpp:pubsub:cap:0' namespace, as child + element of the <items/> element. The <cap-v-map/> element contains one or more <cap-v-map-entry/> + 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.

+ + + + + + + The Uses of This World + +O, that this too too solid flesh would melt +Thaw and resolve itself into a dew! + + + + + + Ghostly Encounters + +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! + + + + + + Alone + +Now I am alone. +O, what a rogue and peasant slave am I! + + + + + + + + + + + +]]> + + + + + +

In order to atomically compare-and-publish an item, a client sends a XEP-0060 <publish/> 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.

+ +

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.

+ + + + + + + Soliloquy + +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? + + + + + + + + http://jabber.org/protocol/pubsub#publish-options + + + 1 + + + + + +]]> + + + + + +

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 <conflict/> error + of type 'modify' which a pubsub-specific condition of <precondition-not-met/> and a + <compare-and-publish-failed/> element qualifed by the 'urn:xmpp:pubsub:cap:0' + namespace. The element MUST have a 'cap-id' attribute with the CAP-V of the lastest item.

+ + + + + + + + +]]> + + + + + + + +

Unfortunately it was not possible to re-use the PubSub item ID for the "Atomically + Compare-And-Publish" purpose. This is mostly due XEP-0060 § 12.8 stating that:

+

+ "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." +

+

Which means that the content of an item could change without its ID, rendering the item ID + unusable for CAP.

+ +

Injecting a "cap"-namespaced attribute carrying the item's CAP-V into PubSub's <item/> + 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 <cap-v-map/> approach for now.

+ + + + + +

This extension protocol does not add any further security considerations to the ones mentioned + in XEP-0060 § 14..

+ + + + + +

This document requires no interaction with the Internet Assigned + Numbers Authority (IANA).

+ + + + + +

This specification defines the following XML namespaces:

+ + + urn:xmpp:pubsub:cap:0 + Indicates support for Compare-And-Publish + XEP-XXXX +]]> + +

This specification defines the following <publish-options/> fields:

+ + ]]> + + + + + +

TODO: Add after the XEP leaves the 'experimental' state.

+ + + + + +

Thanks to Kim Alvefur and Dave Cridland for their feedback.

+ + + + + + + + +