moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 16:55:07 -05:00
Code Issues Releases Wiki Activity

1.10pre1

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@902 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-06-01 20:28:28 +00:00
parent 56d74a4c3d
commit a62d95e9f3
1 changed files with 285 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

305
xep-0060.xml
View File

@ -1,17 +1,3 @@
PEP FEATURES
presence-subscribe (4.1)
caps-filtering (4.2)
auto-create (3)
last-published (4.3.4 -- or config?)
one feature for each default access model?
OTHER FEATURES
subscribe-and-get (needed if last-published?)
plus-private
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
@ -62,6 +48,13 @@ plus-private
&stpeter;
&ralphm;
<revision>
<version>1.10pre1</version>
<date>in progress, last updated 2007-05-30</date>
<initials>psa</initials>
<remark><p>In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification and defined them more precisely; also defined one disco#info feature for each default access model.</p></remark>
</revision>
<revision>
<version>1.9</version>
<date>2006-09-13</date>
@ -551,7 +544,7 @@ And by opposing end them?
<section2 topic='Event Types' anchor='events'>
<p>The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.</p>
<p>No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the <link url='#impl-caching'>Item Caching</link> section of this document).</p>
<p>No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the <link url='#impl-caching'>Item Caching</link> section of this document); if the service supports the "http://jabber.org/protocol/pubsub#last-published" feature then the value of this option MUST default to "on_sub_and_presence" (though the service SHOULD allow the node owner to override the default).</p>
<p>A pubsub service MUST validate publish requests against the configuration of the node along both of these dimensions (see the <link url='#publisher-publish'>Publish An Item to a Node</link> section of this document for the relevant error conditions).</p>
<p>Whether an item must be provided by the publisher, and whether an item ID is provided by the publisher or generated by the pubsub service, depends on the type of event being published. We can summarize the relevant rules as follows:</p>
<table caption='Event Types, Items, and Item IDs'>
@ -616,7 +609,15 @@ And by opposing end them?
</tr>
</table>
<p>A generic publish-subscribe implementation SHOULD support all of the defined access models, although specialized publish-subscribe implementations MAY support only a subset of the access models. Which access models are provided in a particular deployment is a matter of service provisioning (e.g., some restricted deployments may wish to lock down permissions so that only the "authorize" and "whitelist" access models are provided, or even only the "whitelist" access model).</p>
<p>In order for a node creator or owner to specify the access model (see the <link url='#owner-create'>Create a Node With Default Configuration</link> and <link url='#owner-configure'>Configure a Node</link> sections of this document), the 'pubsub#access_model' configuration field is used.</p>
<p>A pubsub service SHOULD advertise its default access model for newly-created nodes by returning one of the following values in its disco#info responses:</p>
<ul>
<li>http://jabber.org/protocol/pubsub#access-authorize</li>
<li>http://jabber.org/protocol/pubsub#access-open</li>
<li>http://jabber.org/protocol/pubsub#access-presence</li>
<li>http://jabber.org/protocol/pubsub#access-roster</li>
<li>http://jabber.org/protocol/pubsub#access-whitelist</li>
</ul>
<p>A node creator or owner can override the default access model by specifying an appropriate value for the 'pubsub#access_model' configuration field (see the <link url='#owner-create'>Create a Node With Default Configuration</link> and <link url='#owner-configure'>Configure a Node</link> sections of this document).</p>
</section2>
<section2 topic='Addressing' anchor='addressing'>
@ -1057,6 +1058,7 @@ And by opposing end them?
<delay xmlns='urn:xmpp:delay' stamp='2003-12-13T23:58:37Z'/>
</message>
]]></example>
<p>If the service sends the last published item by default for all nodes (subject to overriding by node configuration), it MUST return a feature of "http://jabber.org/protocol/pubsub#last-published" in its responsess to disco#info requests.</p>
<p>There are several reasons why the subscription request might fail:</p>
<ol>
<li>The bare JID portions of the JIDs do not match.</li>
@ -2388,7 +2390,7 @@ And by opposing end them?
</error>
</iq>
]]></example>
<p>If the requesting entity attempts to publish an item to a node that does not exist, the service MUST return an &notfound; error.</p>
<p>If the requesting entity attempts to publish an item to a node that does not exist and the service does not support the "auto-create" feature (see <link url='publisher-publish-autocreate'>Automatic Node Creation</link>), the service MUST return an &notfound; error.</p>
<example caption='Entity attempts to publish to a non-existent node'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
@ -2499,6 +2501,9 @@ And by opposing end them?
</iq>
]]></example>
<p>Finally, in order to facilitate authorization for item removal as described in the <link url='#publisher-delete'>Delete an Item from a Node</link> section of this document, implementations that support persistent items SHOULD store the item (if the node is so configured) and maintain a record of the publisher.</p>
<section3 topic='Automatic Node Creation' anchor='publisher-publish-autocreate'>
<p>A pubsub service MAY automatically create a node when it receives a publish request sent to a node that does not exist (instead of returning an &notfound; error). When doing so, the service SHOULD apply the default node configuration. If a service supports this functionality, it MUST advertise that fact by including a feature of "http://jabber.org/protocol/pubsub#auto-create" in its disco#info responses.</p>
</section3>
</section2>
<section2 topic='Delete an Item from a Node' anchor='publisher-delete'>
@ -2990,7 +2995,7 @@ And by opposing end them?
<value>1028</value>
</field>
<field var='pubsub#send_last_published_item' type='list-single'
label='Deliver notifications only to available users'>
label='When to send the last published item'>
<option label='Never'><value>never</value></option>
<option label='When a new subscription is processed'><value>on_sub</value></option>
<option label='When a new subscription is processed and whenever a subscriber comes online'>
@ -3286,7 +3291,6 @@ And by opposing end them?
<value>9216</value>
</field>
<field var='pubsub#send_last_published_item' type='list-single'
label='Deliver notifications only to available users'>
label='When to send the last published item'>
<option label='Never'><value>never</value></option>
<option label='When a new subscription is processed'><value>on_sub</value></option>
@ -4565,10 +4569,163 @@ And by opposing end them?
</section1>
<section1 topic='IM Account Integration' anchor='presence'>
<p>Publish-subscribe functionality can be integrated into existing instant messaging and presence services (see <cite>RFC 3921</cite>), such that each registered account functions as a virtual pubsub service (sometimes called "pubsub-on-a-JID"). In such deployments, the root pubsub node for each virtual pubsub service has the same address as the account JID, which is typically associated with an IM user (e.g., &lt;hamlet@denmark.lit&gt;). Since an IM user typically has a roster of buddies and shares presence information with those buddies, the virtual pubsub service can use the roster and presence information to provide some helpful shortcuts for subscribers, in particular the auto-subscribe and filtered-notifications features described in this section.</p>
<p>Publish-subscribe functionality can be integrated into existing instant messaging and presence services (see <cite>RFC 3921</cite>), such that each registered account functions as a virtual pubsub service (sometimes called "pubsub-on-a-JID"). In such deployments, the root pubsub node for each virtual pubsub service has the same address as the bare JID (&BAREJID;) of the account, which is typically associated with an IM user (e.g., &lt;hamlet@denmark.lit&gt;). Since an IM user typically has a roster of "buddies" and shares presence information with those buddies, the virtual pubsub service can use roster and presence information to provide some helpful shortcuts for subscribers, in particular the auto-subscribe and filtered-notifications features described in this section.</p>
<section2 topic='Auto-Subscribe' anchor='auto-subscribe'>
<p>When a contact is affiliated with the account owner through an XMPP presence subscription, the "auto-subscribe" feature greatly simplifies the subscription process. This is done by associating the presence subscription with a pubsub subscription to the account owner's root collection node (i.e., bare JID), with a subscription_type of "items" and a subscription_depth of "all".</p>
<p>Consider the following presence subscription exchange:</p>
<example caption='Presence subscription handshake'><![CDATA[
<presence from='nurse@capulet.lit' to='juliet@capulet.lit' type='subscribe'/>
<presence from='juliet@capulet.lit' to='nurse@capulet.lit' type='subscribed'/>
]]></example>
<p>With the auto-subscribe feature enabled, this presence subscription exchange is equivalent to the following pubsub subscription exchange:</p>
<example caption='Entity subscribes to a collection node'><![CDATA[
<iq type='set'
from='nurse@capulet.lit/chamber'
to='juliet@capulet.lit
id='collsub'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe jid='nurse@capulet.lit'/>
<options>
<x xmlns='jabber:x:data'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field var='pubsub#subscription_type'>
<value>items</value>
</field>
<field var='pubsub#subscription_depth'>
<value>all</value>
</field>
</x>
</options>
</pubsub>
</iq>
<iq type='result' from='juliet@capulet.lit' to='nurse@capulet.lit/chamber' id='collsub'/>
]]></example>
<p>Note: Automated pubsub subscriptions MUST be based on the JID contained in the 'from' address of the presence subscription request, which for IM contacts will be a bare JID (&BAREJID;).</p>
</section2>
<section2 topic='Filtered Notifications' anchor='filtered-notifications'>
<p>A contact may not want to receive notifications for all payload types. A contact SHOULD signal its preferences to the account owner's server by including <cite>XEP-0115</cite> information that specifies the namespaces for which the contact wishes to receive notifications (if any). This information is used by a pubsub service that supports the "filtered-notifications" feature to send only those payload types that the subscriber wishes to receive.</p>
<p>In order to make this possible, all possible payload namespaces can be appended with the string "+notify" to indicate that the contact wishes to receive notifications for the payload format. Thus if Romeo wants to receive notifications for activity data and geolocation data but not tune data, his client would advertise support for the following namespaces in the disco#info results it sends: <note>Including, say, the 'http://jabber.org/protocol/geoloc' namespace indicates that the client understands the geolocation namespace, whereas including the 'http://jabber.org/protocol/geoloc+notify' namespace indicates that the client wishes to receive notifications related to geolocation.</note></p>
<ul>
<li>http://jabber.org/protocol/geoloc+notify</li>
<li>http://jabber.org/protocol/tune+notify</li>
</ul>
<p>This set of namespaces would then be advertised as a <cite>XEP-0115</cite> "ext" value, such as the following:</p>
<example caption='Contact sends presence with caps'><![CDATA[
<presence from='romeo@montague.lit/orchard'>
<c xmlns='http://jabber.org/protocol/caps'
node='http://www.chatopus.com/ec'
ver='2.1'
ext='sendmeloc tunes'/>
</presence>
]]></example>
<p>Note: In <cite>XEP-0115</cite>, the "ext" values are opaque strings with no semantic meaning.</p>
<p>It is the responsibility of the account owner's server to cache <cite>XEP-0115</cite> information (including "ext" values and their associated namespaces). When the server receives presence from a contact, it MUST check that presence information for entity capabilities data and correlate that data with the desired namespaces for the contact's client. The server MUST NOT send notifications related to any data formats that the contact's client has not asked for via the relevant "namespace+notify" disco#info feature. This enables a client to turn off all notifications (e.g., because of bandwidth restrictions) and to easily receive all desired data formats simply by adding support for the appropriate "namespace+notify" combination in its disco#info results and client capabililies. However, it also implies that a client can request notifications only on a global basis and cannot request, say, mood information only from certain contacts in the user's roster. Community consensus is that this is an acceptable tradeoff. Also, note that this works only if the account owner has a presence subscription to the contact and the contact has a presence subscription to the account owner.</p>
<p>Some examples may help to illustrate the concept of notification filtering. Here we show presence generated by two of the contacts listed above (benvolio@montague.lit does have any presence subscriptions to or from juliet@capulet.lit and therefore is not involved in these protocol flows).</p>
<example caption='Presence with caps'><![CDATA[
<presence from='nurse@capulet.lit/chamber'>
<c xmlns='http://jabber.org/protocol/caps'
node='http://exodus.jabberstudio.org/caps'
ver='0.9'
ext='foo bar baz'/>
</presence>
<presence from='romeo@montague.lit/orchard'>
<c xmlns='http://jabber.org/protocol/caps'
node='http://www.chatopus.com/ec'
ver='2.1'
ext='sendmeloc sendmetunes'/>
</presence>
]]></example>
<p>We assume that Juliet's server doesn't know anything about these capabilities, so it sends service discovery information requests to each of the clients on Juliet's behalf (realistically, the capulet.lit server will quickly build up a cache of client capabilities, with the result that it will not need to send these service discovery requests):</p>
<example caption='Account server queries node#ver'><![CDATA[
<iq from='juliet@capulet.lit'
to='nurse@capulet.lit/chamber'
type='get'
id='disco123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#0.9'/>
</iq>
<iq from='nurse@capulet.lit/chamber'
to='juliet@capulet.lit'
type='result'
id='disco123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#0.9'/>
<feature var='http://jabber.org/protocol/tune'/>
<feature var='http://jabber.org/protocol/activity'/>
<feature var='http://jabber.org/protocol/geoloc'/>
</query>
</iq>
]]></example>
<p>Note: The disco#info result from the node#ver includes only base protocol support, since user-configured notification preferences are to be specified in entity capability extensions. Therefore the server also needs to query the relevant extensions:</p>
<example caption='Account server queries node#ext combinations'><![CDATA[
<iq from='juliet@capulet.lit'
to='nurse@capulet.lit/chamber'
type='get'
id='ext123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#foo'/>
</iq>
<iq from='nurse@capulet.lit/chamber'
to='juliet@capulet.lit'
type='result'
id='ext123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#foo'/>
<feature var='http://jabber.org/protocol/tune+notify'/>
</query>
</iq>
<iq from='juliet@capulet.lit'
to='nurse@capulet.lit/chamber'
type='get'
id='ext234'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#bar'/>
</iq>
<iq from='nurse@capulet.lit/chamber'
to='juliet@capulet.lit'
type='result'
id='ext234'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#bar'/>
<feature var='http://jabber.org/protocol/activity+notify'/>
</query>
</iq>
<iq from='juliet@capulet.lit'
to='nurse@capulet.lit/chamber'
type='get'
id='ext123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#baz'/>
</iq>
<iq from='nurse@capulet.lit/chamber'
to='juliet@capulet.lit'
type='result'
id='ext123'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='http://exodus.jabberstudio.org/caps#baz'/>
<feature var='http://jabber.org/protocol/geoloc+notify'/>
</query>
</iq>
]]></example>
<p>Note: As explained in <cite>XEP-0115</cite>, these requests would not all be sent to the same client and resource, but rather would be sent to random entities that advertise the same entity capabilities information.</p>
<p>The server shall also query the node#ver and node#ext combinations for other contacts (not shown here), which for &lt;romeo@montague.lit&gt; indicate an interest in "http://jabber.org/protocol/geoloc+notify" and "http://jabber.org/protocol/tune+notify" but not "http://jabber.org/protocol/activity+notify".</p>
<p>Now we revisit account owner publication and server generation of notifications, with filtering enabled because the server has caps information:</p>
<ul>
<li><p>If Juliet publishes a tune item to the presence-access "http://jabber.org/protocol/tune" node, her server will send notifications to &lt;nurse@capulet.lit/chamber&gt; and &lt;romeo@montague.lit/orchard&gt; (full JIDs).</p></li>
<li><p>If Juliet publishes an activity item to the presence-access "http://jabber.org/protocol/activity" node, her server will send notifications only to &lt;nurse@capulet.lit/chamber&gt;.</p></li>
<li><p>If Juliet publishes a geolocation item to the roster-access "http://jabber.org/protocol/geoloc" node, her server will send notifications only to &lt;romeo@montague.lit/orchard&gt;.</p></li>
</ul>
</section2>
</section1>
@ -4582,6 +4739,48 @@ And by opposing end them?
<th>Support</th>
<th>Section</th>
</tr>
<tr>
<td>access-authorize</td>
<td>The default access model is "authorize".</td>
<td>OPTIONAL</td>
<td><link url='#accessmodels'>Nodes Access Models</link></td>
</tr>
<tr>
<td>access-open</td>
<td>The default access model is "open".</td>
<td>OPTIONAL</td>
<td><link url='#accessmodels'>Nodes Access Models</link></td>
</tr>
<tr>
<td>access-presence</td>
<td>The default access model is "presence".</td>
<td>OPTIONAL</td>
<td><link url='#accessmodels'>Nodes Access Models</link></td>
</tr>
<tr>
<td>access-roster</td>
<td>The default access model is "roster".</td>
<td>OPTIONAL</td>
<td><link url='#accessmodels'>Nodes Access Models</link></td>
</tr>
<tr>
<td>access-whitelist</td>
<td>The default access model is "whitelist".</td>
<td>OPTIONAL</td>
<td><link url='#accessmodels'>Nodes Access Models</link></td>
</tr>
<tr>
<td>auto-create</td>
<td>The service supports auto-creation of nodes on publish to a non-existent node.</td>
<td>OPTIONAL</td>
<td><link url='#publisher-publish-autocreate'>Automatic Node Creation</link></td>
</tr>
<tr>
<td>auto-subscribe</td>
<td>The service supports auto-subscription to a nodes based on presence subscription.</td>
<td>RECOMMENDED</td>
<td><link url='#auto-subscribe'>Auto-Subscribe</link></td>
</tr>
<tr>
<td>collections</td>
<td>Collection nodes are supported.</td>
@ -4618,6 +4817,12 @@ And by opposing end them?
<td>RECOMMENDED</td>
<td><link url='#owner-delete'>Delete a Node</link></td>
</tr>
<tr>
<td>filtered-notifications</td>
<td>Notifications are filtered based on Entity Capabilities data.</td>
<td>RECOMMENDED</td>
<td><link url='#filtered-notifications'>Filtered Notifications</link></td>
</tr>
<tr>
<td>get-pending</td>
<td>Retrieval of pending subscription approvals is supported.</td>
@ -4636,6 +4841,12 @@ And by opposing end them?
<td>RECOMMENDED</td>
<td>&#160;</td>
</tr>
<tr>
<td>last-published</td>
<td>By default the last published item is sent to new subscribers and on receipt of available presence from existing subscribers.</td>
<td>RECOMMENDED</td>
<td><link url='#events'>Event Types</link></td>
</tr>
<tr>
<td>leased-subscription</td>
<td>Time-based subscriptions are supported.</td>
@ -4690,6 +4901,12 @@ And by opposing end them?
<td>OPTIONAL</td>
<td>&#160;</td>
</tr>
<tr>
<td>presence-subscribe</td>
<td>Authorized contacts are automatically subscribed to a user's virtual pubsub service.</td>
<td>RECOMMENDED</td>
<td><link url='#auto-subscribe'>Auto-Subscribe</link></td>
</tr>
<tr>
<td>publish</td>
<td>Publishing items is supported (note: not valid for collection nodes).</td>
@ -5326,6 +5543,41 @@ O, what a rogue and peasant slave am I!
<section2 topic='Service Discovery Features' anchor='registrar-features'>
<p>The XMPP Registrar maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that may be returned by pubsub services. The following registry submission has been provided to the XMPP Registrar for that purpose.</p>
<code><![CDATA[
<var>
<name>http://jabber.org/protocol/pubsub#access-authorize</name>
<desc>The default access model is authorize.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#access-open</name>
<desc>The default access model is open.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#access-presence</name>
<desc>The default access model is presence.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#access-roster</name>
<desc>The default access model is roster.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#access-whitelist</name>
<desc>The default access model is whitelist.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#auto-create</name>
<desc>The service supports automatic creation of nodes on first publish.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#auto-subscribe</name>
<desc>The service supports automatic subscription to a nodes based on presence subscription.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#collections</name>
<desc>Collection nodes are supported.</desc>
@ -5356,6 +5608,11 @@ O, what a rogue and peasant slave am I!
<desc>Deletion of nodes is supported.</desc>
<doc>XEP-0060</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#filtered-notifications</name>
<desc>The service supports filtering of notifications based on Entity Capabilities.</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#get-pending</name>
<desc>Retrieval of pending subscription approvals is supported.</desc>
@ -5371,6 +5628,14 @@ O, what a rogue and peasant slave am I!
<desc>Publishers may specify item identifiers.</desc>
<doc>XEP-0060</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#last-published</name>
<desc>
The service supports sending of the last published item to new
subscribers and to newly available resources.
</desc>
<doc>XEP-0163</doc>
</var>
<var>
<name>http://jabber.org/protocol/pubsub#leased-subscription</name>
<desc>Time-based subscriptions are supported.</desc>