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-0173.xml 9.1KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218
  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 Subscription Storage</title>
  10. <abstract>This document defines an XMPP protocol extension for storing subscriptions to Pubsub nodes.</abstract>
  11. &LEGALNOTICE;
  12. <number>0173</number>
  13. <status>Deferred</status>
  14. <type>Historical</type>
  15. <sig>Standards</sig>
  16. <approver>Council</approver>
  17. <dependencies>
  18. <spec>XMPP Core</spec>
  19. <spec>XEP-0049</spec>
  20. <spec>XEP-0060</spec>
  21. </dependencies>
  22. <supersedes/>
  23. <supersededby/>
  24. <shortname>pubsubs</shortname>
  25. <author>
  26. <firstname>Magnus</firstname>
  27. <surname>Henoch</surname>
  28. <email>henoch@dtek.chalmers.se</email>
  29. <jid>legoscia@jabber.cd.chalmers.se</jid>
  30. </author>
  31. <revision>
  32. <version>0.1</version>
  33. <date>2006-02-09</date>
  34. <initials>psa</initials>
  35. <remark><p>Initial version; changed title to Pubsub Subscription Storage; changed namespace to storage:pubsubs for consistency with other storage XEPs.</p></remark>
  36. </revision>
  37. <revision>
  38. <version>0.0.4</version>
  39. <date>2005-12-11</date>
  40. <initials>mh</initials>
  41. <remark><p>Add resource attribute.</p></remark>
  42. </revision>
  43. <revision>
  44. <version>0.0.3</version>
  45. <date>2005-11-13</date>
  46. <initials>mh</initials>
  47. <remark><p>Add subscription attribute.</p></remark>
  48. </revision>
  49. <revision>
  50. <version>0.0.2</version>
  51. <date>2005-10-28</date>
  52. <initials>mh</initials>
  53. <remark><p>Fix typo and schema.</p></remark>
  54. </revision>
  55. <revision>
  56. <version>0.0.1</version>
  57. <date>2005-10-25</date>
  58. <initials>mh</initials>
  59. <remark><p>First draft.</p></remark>
  60. </revision>
  61. </header>
  62. <section1 topic='Introduction' anchor='intro'>
  63. <p>&xep0060; allows Jabber entities to subscribe to various kinds of information, but provides no way of remembering which nodes a user has subscribed to. Other protocols (e.g. &xep0080;, &xep0084;) allow information about a certain entity to be published to a Pubsub node. These protocols use &xep0030; to allow other entities to find the pubsub node used by a certain entity, but provide no way of performing the opposite mapping, from pubsub node to information source. This document attempts to fill that void, using &xep0049; for storing information about subscriptions.</p>
  64. </section1>
  65. <section1 topic='Requirements' anchor='reqs'>
  66. <p>This protocol enables Jabber clients to do the following:</p>
  67. <ul>
  68. <li>Remember which pubsub nodes the entity has subscribed to, and what kind of information is available at each node</li>
  69. <li>Update the mappings when subscriptions are added or removed</li>
  70. <li>Correlate incoming pubsub events to subscriptions</li>
  71. </ul>
  72. </section1>
  73. <section1 topic='Protocol' anchor='proto'>
  74. <p>The &lt;subscriptions/&gt; element qualified by the 'storage:pubsubs' namespace is the root element used in the jabber:iq:private transactions. It has zero or more &lt;subscription/&gt; child elements, each of which MUST possess the following attributes:</p>
  75. <ul>
  76. <li><em>jid</em> -- The JID of the pubsub service used</li>
  77. <li><em>node</em> -- The pubsub node at which the data is available</li>
  78. <li><em>subscription</em> -- The current subscription state, one of "none", "pending", "unconfigured" and "subscribed"</li>
  79. </ul>
  80. <p>Additionally, the &lt;subscription/&gt; element MAY possess these attributes:</p>
  81. <ul>
  82. <li><em>resource</em> -- The resource that is subscribed to this pubsub node. If the 'resource' attribute is absent, the bare JID is subscribed.</li>
  83. <li><em>user</em> -- The JID of the owner of this particular piece of data</li>
  84. <li><em>targetns</em> -- The namespace of the data in question</li>
  85. </ul>
  86. </section1>
  87. <section1 topic='Use Cases' anchor='usecases'>
  88. <section2 topic='Retrieving Existing Subscriptions' anchor='retrieving'>
  89. <p>In this example, the user already has a subscription to Juliet's geolocation, possibly established through another client.</p>
  90. <example caption='Client requests existing subscriptions'><![CDATA[
  91. <iq type='get' id='retrieve1'>
  92. <query xmlns='jabber:iq:private'>
  93. <subscriptions xmlns='storage:pubsubs'/>
  94. </query>
  95. </iq>
  96. ]]></example>
  97. <example caption='Server returns existing subscriptions'><![CDATA[
  98. <iq type='result' id='retrieve1'>
  99. <query xmlns='jabber:iq:private'>
  100. <subscriptions xmlns='storage:pubsubs'>
  101. <subscription user='juliet@capulet.com'
  102. jid='pubsub.capulet.com'
  103. node='juliet/geoloc'
  104. targetns='http://jabber.org/protocol/geoloc'
  105. subscription='subscribed'/>
  106. </subscriptions>
  107. </query>
  108. </iq>
  109. ]]></example>
  110. </section2>
  111. <section2 topic='Updating Subscriptions' anchor='updating'>
  112. <p>Due to the nature of XEP-0049, incremental updates are not possible; a client MUST send the entire &lt;subscriptions/&gt; node for each update. Before performing the update, the client SHOULD retrieve the stored subscriptions, and incorporate any changes.</p>
  113. <p>In this example, the user has just subscribed to Romeo's tune (see &xep0118;). Assuming that retrieving happened as in the previous use case, updating the subscriptions proceeds as follows:</p>
  114. <example caption='Client sends updated subscriptions'><![CDATA[
  115. <iq type='set' id='update1'>
  116. <query xmlns='jabber:iq:private'>
  117. <subscriptions xmlns='storage:pubsubs'>
  118. <subscription user='juliet@capulet.com'
  119. jid='pubsub.capulet.com'
  120. node='juliet/geoloc'
  121. targetns='http://jabber.org/protocol/geoloc'
  122. subscription='subscribed'/>
  123. <subscription user='romeo@montague.net'
  124. jid='pubsub.montague.net'
  125. node='5017cdc9f4a3d1450445c9096064e459'
  126. targetns='http://jabber.org/protocol/tune'
  127. subscription='subscribed'/>
  128. </subscriptions>
  129. </query>
  130. </iq>
  131. ]]></example>
  132. <example caption='Server reports success'><![CDATA[
  133. <iq type='result' id='update1'/>
  134. ]]></example>
  135. </section2>
  136. <section2 topic='Identifying Incoming Events' anchor='identifying'>
  137. <p>Having recorded the retrieved mappings, the client is now prepared to identify incoming pubsub events. Assume that the following event arrives:</p>
  138. <example caption='Client receives pubsub event'><![CDATA[
  139. <message
  140. from='pubsub.montague.net'
  141. to='mercutio@shakespeare.lit'>
  142. <event xmlns='http://jabber.org/protocol/pubsub#event'>
  143. <items node='5017cdc9f4a3d1450445c9096064e459'>
  144. <item id='current'>
  145. <tune xmlns='http://jabber.org/protocol/tune'>
  146. <artist>Yes</artist>
  147. <title>Heart of the Sunrise</title>
  148. <source>Yessongs</source>
  149. <track>3</track>
  150. <length>686</length>
  151. </tune>
  152. </item>
  153. </items>
  154. </event>
  155. </message>
  156. ]]></example>
  157. <p>The client now knows that this information comes from romeo@montague.net.</p>
  158. </section2>
  159. </section1>
  160. <section1 topic='Security Considerations' anchor='security'>
  161. <p>Pubsub events offer an opportunity to spoof sender addresses e.g. through 'replyto' data (as specified by the &xep0033; protocol). This protocol attempts to close that hole. It does so by the following rules and assumptions:</p>
  162. <ul>
  163. <li>A client MUST add mappings (i.e. associations between a publisher's JID and a pubsub node) only from trustworthy sources, i.e. published disco items (see &xep0030;). This relies on disco information not being cracked or falsified.</li>
  164. <li>A client MUST retrieve mappings only from trustworthy sources, i.e. private XML storage. This assumes that no-one but the user is able to change such information.</li>
  165. </ul>
  166. </section1>
  167. <section1 topic='IANA Considerations' anchor='iana'>
  168. <p>This document requires no interaction with &IANA;.</p>
  169. </section1>
  170. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  171. <p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this document.</p>
  172. </section1>
  173. <section1 topic='XML Schema' anchor='schema'>
  174. <code><![CDATA[
  175. <?xml version='1.0' encoding='UTF-8'?>
  176. <xs:schema
  177. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  178. targetNamespace='storage:pubsubs'
  179. xmlns='storage:pubsubs'
  180. elementFormDefault='qualified'>
  181. <xs:element name='subscriptions'>
  182. <xs:complexType>
  183. <xs:sequence>
  184. <xs:element ref='subscription' minOccurs='0' maxOccurs='unbounded'/>
  185. </xs:sequence>
  186. </xs:complexType>
  187. </xs:element>
  188. <xs:element name='subscription'>
  189. <xs:complexType>
  190. <xs:attribute name='jid' type='xs:string' use='required'/>
  191. <xs:attribute name='node' type='xs:string' use='required'/>
  192. <xs:attribute name='subscription' use='required'>
  193. <xs:simpleType>
  194. <xs:restriction base='xs:NCName'>
  195. <xs:enumeration value='none'/>
  196. <xs:enumeration value='pending'/>
  197. <xs:enumeration value='subscribed'/>
  198. <xs:enumeration value='unconfigured'/>
  199. </xs:restriction>
  200. </xs:simpleType>
  201. </xs:attribute>
  202. <xs:attribute name='resource' type='xs:string' use='optional'/>
  203. <xs:attribute name='user' type='xs:string' use='optional'/>
  204. <xs:attribute name='targetns' type='xs:string' use='optional'/>
  205. </xs:complexType>
  206. </xs:element>
  207. </xs:schema>
  208. ]]></code>
  209. </section1>
  210. </xep>