diff --git a/inbox/cap.xml b/inbox/cap.xml index 92dfd031..e4704e78 100644 --- a/inbox/cap.xml +++ b/inbox/cap.xml @@ -22,6 +22,18 @@ cap &flow; + + 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 @@ -50,28 +62,91 @@ -

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 <publish/> element defined in - &xep0060; and it MUST contain a previd attribute containing - an item ID.

+ -

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.

+

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.

+ + - - - - + id='pub1'> + + + + Soliloquy 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, And by opposing end them? - - tag:denmark.lit,2003:entry-32397 - 2003-12-13T18:30:02Z - 2003-12-13T18:30:02Z + + + + http://jabber.org/protocol/pubsub#publish-options + + + 1 + + + ]]> - - -

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 XEP-0060 7.1.2.

- -

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 <compare-and-publish-failed/> element. The - element MUST have a 'id' attribute with the ID of the lastest - item.

+

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.

- - - - + to='hamlet@denmark.lit/elsinore' + id='retract1'> + + + + + ]]> - + -

All other error cases are handled as specified in - XEP-0060 § 7.1.3

+ - +

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 extension protocol does not add any further security considerations to the ones mentioned + in XEP-0060 § 14..

 @@ -153,17 +238,39 @@ And by opposing end them? - - urn:xmpp:pubsub:cap:0 - Indicates support for Compare-And-Publish - XEP-XXXX + 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.

+ + + + + + + +