xeps/xep-0173.xml

219 line
9.1 KiB
XML

<?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>Pubsub Subscription Storage</title>
<abstract>This document defines an XMPP protocol extension for storing subscriptions to Pubsub nodes.</abstract>
&LEGALNOTICE;
<number>0173</number>
<status>Deferred</status>
<type>Historical</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0049</spec>
<spec>XEP-0060</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>pubsubs</shortname>
<author>
<firstname>Magnus</firstname>
<surname>Henoch</surname>
<email>henoch@dtek.chalmers.se</email>
<jid>legoscia@jabber.cd.chalmers.se</jid>
</author>
<revision>
<version>0.1</version>
<date>2006-02-09</date>
<initials>psa</initials>
<remark><p>Initial version; changed title to Pubsub Subscription Storage; changed namespace to storage:pubsubs for consistency with other storage XEPs.</p></remark>
</revision>
<revision>
<version>0.0.4</version>
<date>2005-12-11</date>
<initials>mh</initials>
<remark><p>Add resource attribute.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2005-11-13</date>
<initials>mh</initials>
<remark><p>Add subscription attribute.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2005-10-28</date>
<initials>mh</initials>
<remark><p>Fix typo and schema.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2005-10-25</date>
<initials>mh</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<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>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This protocol enables Jabber clients to do the following:</p>
<ul>
<li>Remember which pubsub nodes the entity has subscribed to, and what kind of information is available at each node</li>
<li>Update the mappings when subscriptions are added or removed</li>
<li>Correlate incoming pubsub events to subscriptions</li>
</ul>
</section1>
<section1 topic='Protocol' anchor='proto'>
<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>
<ul>
<li><em>jid</em> -- The JID of the pubsub service used</li>
<li><em>node</em> -- The pubsub node at which the data is available</li>
<li><em>subscription</em> -- The current subscription state, one of "none", "pending", "unconfigured" and "subscribed"</li>
</ul>
<p>Additionally, the &lt;subscription/&gt; element MAY possess these attributes:</p>
<ul>
<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>
<li><em>user</em> -- The JID of the owner of this particular piece of data</li>
<li><em>targetns</em> -- The namespace of the data in question</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Retrieving Existing Subscriptions' anchor='retrieving'>
<p>In this example, the user already has a subscription to Juliet's geolocation, possibly established through another client.</p>
<example caption='Client requests existing subscriptions'><![CDATA[
<iq type='get' id='retrieve1'>
<query xmlns='jabber:iq:private'>
<subscriptions xmlns='storage:pubsubs'/>
</query>
</iq>
]]></example>
<example caption='Server returns existing subscriptions'><![CDATA[
<iq type='result' id='retrieve1'>
<query xmlns='jabber:iq:private'>
<subscriptions xmlns='storage:pubsubs'>
<subscription user='juliet@capulet.com'
jid='pubsub.capulet.com'
node='juliet/geoloc'
targetns='http://jabber.org/protocol/geoloc'
subscription='subscribed'/>
</subscriptions>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Updating Subscriptions' anchor='updating'>
<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>
<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>
<example caption='Client sends updated subscriptions'><![CDATA[
<iq type='set' id='update1'>
<query xmlns='jabber:iq:private'>
<subscriptions xmlns='storage:pubsubs'>
<subscription user='juliet@capulet.com'
jid='pubsub.capulet.com'
node='juliet/geoloc'
targetns='http://jabber.org/protocol/geoloc'
subscription='subscribed'/>
<subscription user='romeo@montague.net'
jid='pubsub.montague.net'
node='5017cdc9f4a3d1450445c9096064e459'
targetns='http://jabber.org/protocol/tune'
subscription='subscribed'/>
</subscriptions>
</query>
</iq>
]]></example>
<example caption='Server reports success'><![CDATA[
<iq type='result' id='update1'/>
]]></example>
</section2>
<section2 topic='Identifying Incoming Events' anchor='identifying'>
<p>Having recorded the retrieved mappings, the client is now prepared to identify incoming pubsub events. Assume that the following event arrives:</p>
<example caption='Client receives pubsub event'><![CDATA[
<message
from='pubsub.montague.net'
to='mercutio@shakespeare.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='5017cdc9f4a3d1450445c9096064e459'>
<item id='current'>
<tune xmlns='http://jabber.org/protocol/tune'>
<artist>Yes</artist>
<title>Heart of the Sunrise</title>
<source>Yessongs</source>
<track>3</track>
<length>686</length>
</tune>
</item>
</items>
</event>
</message>
]]></example>
<p>The client now knows that this information comes from romeo@montague.net.</p>
</section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<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>
<ul>
<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>
<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>
</ul>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>No namespaces or parameters need to be registered with the &REGISTRAR; as a result of this document.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='storage:pubsubs'
xmlns='storage:pubsubs'
elementFormDefault='qualified'>
<xs:element name='subscriptions'>
<xs:complexType>
<xs:sequence>
<xs:element ref='subscription' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='subscription'>
<xs:complexType>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:attribute name='node' type='xs:string' use='required'/>
<xs:attribute name='subscription' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='none'/>
<xs:enumeration value='pending'/>
<xs:enumeration value='subscribed'/>
<xs:enumeration value='unconfigured'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='resource' type='xs:string' use='optional'/>
<xs:attribute name='user' type='xs:string' use='optional'/>
<xs:attribute name='targetns' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>