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-0254.xml 16KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378
  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>PubSub Queueing</title>
  10. <abstract>This specification defines an extension to XMPP publish-subscribe for queueing information at a node.</abstract>
  11. &LEGALNOTICE;
  12. <number>0254</number>
  13. <status>Deferred</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <approver>Council</approver>
  17. <dependencies>
  18. <spec>XMPP Core</spec>
  19. <spec>XEP-0060</spec>
  20. </dependencies>
  21. <supersedes/>
  22. <supersededby/>
  23. <shortname>NOT_YET_ASSIGNED</shortname>
  24. &hildjj;
  25. &stpeter;
  26. <revision>
  27. <version>0.1</version>
  28. <date>2008-11-13</date>
  29. <initials>psa</initials>
  30. <remark><p>Initial published version.</p></remark>
  31. </revision>
  32. <revision>
  33. <version>0.0.3</version>
  34. <date>2008-10-07</date>
  35. <initials>jjh/psa</initials>
  36. <remark><p>Added more detailed error flows; added additional implementation notes.</p></remark>
  37. </revision>
  38. <revision>
  39. <version>0.0.2</version>
  40. <date>2008-10-07</date>
  41. <initials>jjh/psa</initials>
  42. <remark>
  43. <ul>
  44. <li>Specified that notifications are sent to only one subscriber at a time.</li>
  45. <li>Specified that notifications include payloads.</li>
  46. <li>Added protocol extension for unlock feature.</li>
  47. <li>Modified namespace to incorporate namespace versioning.</li>
  48. </ul>
  49. </remark>
  50. </revision>
  51. <revision>
  52. <version>0.0.1</version>
  53. <date>2008-08-14</date>
  54. <initials>psa/jjh</initials>
  55. <remark><p>First draft.</p></remark>
  56. </revision>
  57. </header>
  58. <section1 topic='Introduction' anchor='intro'>
  59. <p>The &xep0060; extension to XMPP provides a comprehensive technology for alerts, notifications, data syndication, rich presence, and other real-time messaging use cases. In terms of traditional publish-subscribe systems like Java Message Service (JMS), the core XMPP PubSub specification covers the Observer design pattern only; however, traditional publish-subscribe systems often include support for a second design pattern, usually called the "point-to-point" or "queueing" pattern. <note>See for instance &lt;<link url='http://en.wikipedia.org/wiki/Java_Message_Service'>http://en.wikipedia.org/wiki/Java_Message_Service</link>&gt;.</note> This specification defines a few small extensions to XMPP PubSub that enable support for a queueing mode in XMPP. The queueing mode is an add-on feature that a service can support, and that a node owner can enable if supported by the service. The feature name is "urn:xmpp:pubsub:queueing:0".</p>
  60. </section1>
  61. <section1 topic='How It Works' anchor='howitworks'>
  62. <section2 topic='Subscribing' anchor='subscribe'>
  63. <p>If a node has enabled support for the queueing mode, in response to a subscription request without configuration options it MUST return an IQ-error containing a subscription options form; this form MUST include the "queue_requests" field (which specifies the number of parallel requests a subscriber is willing to process).</p>
  64. <example caption='Service indicates that subscription configuration is required'><![CDATA[
  65. <iq from='workflows.shakespeare.lit'
  66. id='sub1'
  67. to='workerbee237@shakespeare.lit/foo'
  68. type='error'>
  69. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  70. <subscribe
  71. jid='workerbee237@shakespeare.lit'
  72. node='a290fjsl29j19kjb'/>
  73. <options
  74. jid='workerbee237@shakespeare.lit'
  75. node='a290fjsl29j19kjb'>
  76. <x xmlns='jabber:x:data' type='form'>
  77. <field var='FORM_TYPE' type='hidden'>
  78. <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
  79. </field>
  80. <field type='text-single' var='pubsub#queue_requests'>
  81. <required/>
  82. </field>
  83. </x>
  84. </options>
  85. </pubsub>
  86. <error type='modify'>
  87. <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  88. <configuration-required xmlns='http://jabber.org/protocol/pubsub#errors'/>
  89. </error>
  90. </iq>
  91. ]]></example>
  92. <p>The subscriber would then send a new subscription request, this time with options.</p>
  93. <example caption='Subscribing with options'><![CDATA[
  94. <iq from='workerbee237@shakespeare.lit/foo'
  95. id='sub2'
  96. to='workflows.shakespeare.lit'
  97. type='set'>
  98. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  99. <subscribe
  100. jid='workerbee237@shakespeare.lit'
  101. node='a290fjsl29j19kjb'/>
  102. <options
  103. jid='workerbee237@shakespeare.lit'
  104. node='a290fjsl29j19kjb'>
  105. <x xmlns='jabber:x:data' type='submit'>
  106. <field var='FORM_TYPE' type='hidden'>
  107. <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
  108. </field>
  109. <field var='pubsub#queue_requests'>
  110. <value>5</value>
  111. </field>
  112. </x>
  113. </options>
  114. </pubsub>
  115. </iq>
  116. ]]></example>
  117. <p>If the subscription request can be processed successfully, the service returns an IQ-result and includes the configuration options established during the negotiation.</p>
  118. <example caption='Service replies with success (including configuration options)'><![CDATA[
  119. <iq from='workflows.shakespeare.lit'
  120. id='sub2'
  121. to='workerbee237@shakespeare.lit/foo'
  122. type='result'>
  123. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  124. <subscription
  125. jid='workerbee237@shakespeare.lit'
  126. node='a290fjsl29j19kjb'
  127. subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
  128. subscription='subscribed'/>
  129. <options>
  130. <x xmlns='jabber:x:data' type='result'>
  131. <field var='FORM_TYPE' type='hidden'>
  132. <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
  133. </field>
  134. <field var='pubsub#queue_requests'>
  135. <value>5</value>
  136. </field>
  137. </x>
  138. </options>
  139. </pubsub>
  140. </iq>
  141. ]]></example>
  142. </section2>
  143. <section2 topic='Assigning an Item' anchor='assign'>
  144. <p>At any time, a publisher can push an item to the queue node.</p>
  145. <example caption='Publisher publishes an item'><![CDATA[
  146. <iq from='engine.shakespeare.lit'
  147. id='pub1'
  148. to='workflow.shakespeare.lit'
  149. type='set'>
  150. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  151. <publish node='a290fjsl29j19kjb'>
  152. <item id='ae890ac52d0df67ed7cfdf51b644e901'>
  153. <example xmlns='urn:xmpp:example'>payload</example>
  154. </item>
  155. </publish>
  156. </pubsub>
  157. </iq>
  158. ]]></example>
  159. <p>The item is published to <em>one</em> of the subscribers.</p>
  160. <example caption='One subscriber receives a notification'><![CDATA[
  161. <message from='workflow.shakespeare.lit'
  162. id='foo'
  163. to='workerbee237@shakespeare.lit'>
  164. <event xmlns='http://jabber.org/protocol/pubsub#event'>
  165. <items node='a290fjsl29j19kjb'>
  166. <item id='ae890ac52d0df67ed7cfdf51b644e901'>
  167. <example xmlns='urn:xmpp:example'>payload</example>
  168. </item>
  169. </items>
  170. </event>
  171. </message>
  172. ]]></example>
  173. </section2>
  174. <section2 topic='Deleting an Item from the Queue' anchor='delete'>
  175. <p>When the subscriber that received the item has successfully processed it (whatever that means in the context of the queue), the subscriber deletes the item from the queue.</p>
  176. <example caption='Entity deletes an item from a node'><![CDATA[
  177. <iq from='workerbee237@shakespeare.lit/foo'
  178. id='delete1'
  179. to='workflows.shakespeare.lit'
  180. type='get'>
  181. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  182. <retract node='a290fjsl29j19kjb'>
  183. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  184. </retract>
  185. </pubsub>
  186. </iq>
  187. ]]></example>
  188. <p>In the context of a queue node, the service MUST treat a delete request from a subscriber that received the item as if the sender were a publisher; i.e., it MUST delete the item from the queue and notify only this subscriber that the item has been deleted.</p>
  189. <example caption='Subscriber receives delete notification'><![CDATA[
  190. <message from='workflow.shakespeare.lit'
  191. id='bar'
  192. to='workerbee237@shakespeare.lit'>
  193. <event xmlns='http://jabber.org/protocol/pubsub#event'>
  194. <items node='a290fjsl29j19kjb'>
  195. <retract id='ae890ac52d0df67ed7cfdf51b644e901'/>
  196. </items>
  197. </event>
  198. </message>
  199. ]]></example>
  200. <p>Note: The subscriber SHOULD NOT commit any pending transactions until it receives the delete notification.</p>
  201. <p>If the item does not exist, the service MUST return an &notfound; error as described in <cite>XEP-0060</cite>.</p>
  202. <p>If the entity that attempts to delete the item is not the subscriber that received the item, the service MUST return a &forbidden; error as described in <cite>XEP-0060</cite>.</p>
  203. <p>If the item is locked by another subscriber, the service MUST return a &conflict; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
  204. <example caption='Item is locked by another subscriber'><![CDATA[
  205. <iq from='workflows.shakespeare.lit'
  206. id='delete1'
  207. to='workerbee237@shakespeare.lit/foo'
  208. type='get'>
  209. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  210. <retract node='a290fjsl29j19kjb'>
  211. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  212. </retract>
  213. </pubsub>
  214. <error type='auth'>
  215. <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  216. </error>
  217. </iq>
  218. ]]></example>
  219. <p>If the subscriber that received the item attempts to delete the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error (this flow is not defined in <cite>XEP-0060</cite>.</p>
  220. <example caption='Item is no longer locked by subscriber'><![CDATA[
  221. <iq from='workflows.shakespeare.lit'
  222. id='delete1'
  223. to='workerbee237@shakespeare.lit/foo'
  224. type='get'>
  225. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  226. <retract node='a290fjsl29j19kjb'>
  227. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  228. </retract>
  229. </pubsub>
  230. <error type='wait'>
  231. <unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  232. </error>
  233. </iq>
  234. ]]></example>
  235. </section2>
  236. <section2 topic='Unlocking an Item' anchor='unlock'>
  237. <p>The subscriber might determine that it cannot process the item (whatever that means in the context of the queue); if so, the subscriber unlocks the item.</p>
  238. <example caption='Entity unlocks an item'><![CDATA[
  239. <iq from='workerbee237@shakespeare.lit/foo'
  240. id='unlock1'
  241. to='workflows.shakespeare.lit'
  242. type='get'>
  243. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  244. <unlock xmlns='urn:xmpp:pubsub:queueing:0'
  245. node='a290fjsl29j19kjb'>
  246. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  247. </unlock>
  248. </pubsub>
  249. </iq>
  250. ]]></example>
  251. <p>The service then MUST unlock the item and notify only this subscriber that the item has been unlocked.</p>
  252. <example caption='Subscriber receives unlock notification'><![CDATA[
  253. <message from='workflow.shakespeare.lit'
  254. id='baz'
  255. to='workerbee237@shakespeare.lit'>
  256. <event xmlns='http://jabber.org/protocol/pubsub#event'>
  257. <items node='a290fjsl29j19kjb'>
  258. <unlock xmlns='urn:xmpp:queueing:0'
  259. id='ae890ac52d0df67ed7cfdf51b644e901'/>
  260. </items>
  261. </event>
  262. </message>
  263. ]]></example>
  264. <p>When an item is unlocked, the service would then send a publish notification to another subscriber according to application-specific logic for determining the "next" subscriber.</p>
  265. <p>If the item does not exist, the service MUST return an &notfound; error.</p>
  266. <example caption='Item does not exist'><![CDATA[
  267. <iq from='workflows.shakespeare.lit'
  268. id='delete1'
  269. to='workerbee237@shakespeare.lit/foo'
  270. type='error'>
  271. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  272. <unlock xmlns='urn:xmpp:pubsub:queueing:0'
  273. node='a290fjsl29j19kjb'>
  274. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  275. </unlock>
  276. </pubsub>
  277. <error type='cancel'>
  278. <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  279. </error>
  280. </iq>
  281. ]]></example>
  282. <p>If the entity that attempts to unlock the item is not the subscriber that received the item, the service MUST return a &forbidden; error.</p>
  283. <example caption='Requesting entity did not receive item'><![CDATA[
  284. <iq from='workflows.shakespeare.lit'
  285. id='delete1'
  286. to='workerbee237@shakespeare.lit/foo'
  287. type='error'>
  288. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  289. <unlock xmlns='urn:xmpp:pubsub:queueing:0'
  290. node='a290fjsl29j19kjb'>
  291. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  292. </unlock>
  293. </pubsub>
  294. <error type='auth'>
  295. <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  296. </error>
  297. </iq>
  298. ]]></example>
  299. <p>If the item is locked by another subscriber, the service MUST return a &conflict; error.</p>
  300. <example caption='Item is locked by another subscriber'><![CDATA[
  301. <iq from='workflows.shakespeare.lit'
  302. id='delete1'
  303. to='workerbee237@shakespeare.lit/foo'
  304. type='error'>
  305. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  306. <unlock xmlns='urn:xmpp:pubsub:queueing:0'
  307. node='a290fjsl29j19kjb'>
  308. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  309. </unlock>
  310. </pubsub>
  311. <error type='cancel'>
  312. <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  313. </error>
  314. </iq>
  315. ]]></example>
  316. <p>If the subscriber that received the item attempts to unlock the item but the item is no longer locked by the subscriber (e.g., because of a race condition or a lost notification), the service MUST return an &unexpected; error.</p>
  317. <example caption='Item is no longer locked by subscriber'><![CDATA[
  318. <iq from='workflows.shakespeare.lit'
  319. id='delete1'
  320. to='workerbee237@shakespeare.lit/foo'
  321. type='error'>
  322. <pubsub xmlns='http://jabber.org/protocol/pubsub'>
  323. <unlock xmlns='urn:xmpp:pubsub:queueing:0'
  324. node='a290fjsl29j19kjb'>
  325. <item id='ae890ac52d0df67ed7cfdf51b644e901'/>
  326. </unlock>
  327. </pubsub>
  328. <error type='wait'>
  329. <unexpected-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  330. </error>
  331. </iq>
  332. ]]></example>
  333. </section2>
  334. </section1>
  335. <section1 topic='Determining Support' anchor='support'>
  336. <p>If a pubsub service supports the queueing mode, it MUST advertise support for the "urn:xmpp:pubsub:queueing:0" namespace in response to &xep0030; information requests.</p>
  337. </section1>
  338. <section1 topic='Implementation Notes' anchor='impl'>
  339. <p>If the service receives unavailable presence from a subscriber, it SHOULD unlock all outstanding queue items associated with the subscriber and unsubscribe the subscriber to prevent delivery of further publish notifications.</p>
  340. <p>If a subscriber cannot process queue items because of an unrecoverable error (e.g., disk full), the subscriber SHOULD unsubscribe and then unlock all of its outstanding queue items.</p>
  341. <p>If the service does not receive a delete or unlock request from a subscriber that received a queue item in a configurable amount of time, it SHOULD timeout the request, send an unlock notification to the subscriber, and send a publish notification to the "next" subscriber.</p>
  342. </section1>
  343. <section1 topic='Security Considerations' anchor='security'>
  344. <p>To follow.</p>
  345. </section1>
  346. <section1 topic='IANA Considerations' anchor='iana'>
  347. <p>This document requires no interaction with &IANA;.</p>
  348. </section1>
  349. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  350. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  351. <p>This specification defines the following XML namespace:</p>
  352. <ul>
  353. <li>urn:xmpp:pubsub:queueing:0</li>
  354. </ul>
  355. <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  356. </section2>
  357. <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
  358. &NSVER;
  359. </section2>
  360. <section2 topic='Service Discovery Features' anchor='registrar-features'>
  361. <p>The &REGISTRAR; maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that can be returned by pubsub services. The following registry submission supplements the existing list.</p>
  362. <code><![CDATA[
  363. <var>
  364. <name>urn:xmpp:pubsub:queueing:0</name>
  365. <desc>The node or service supports the queueing mode.</desc>
  366. <doc>XEP-xxxx</doc>
  367. </var>
  368. ]]></code>
  369. </section2>
  370. </section1>
  371. </xep>