git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3929 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2010-02-17 04:14:02 +00:00
parent 38c3589314
commit ae704d6c48
1 changed files with 43 additions and 155 deletions

View File

@ -23,6 +23,12 @@
&hildjj;
&metajack;
&stpeter;
<revision>
<version>0.2</version>
<date>2010-02-16</date>
<initials>psa</initials>
<remark><p>Simplified feature discovery to use standard XMPP disco.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2009-09-15</date>
@ -162,61 +168,61 @@
<section1 topic='Protocol' anchor='protocol'>
<p>The SIFT protocol is used to <em>intercept</em> or <em>filter</em> inbound stanzas only, not outbound stanzas sent by the client to the server or other entities. By "intercept" is meant that the server will not deliver any such stanza kind (message, presence, or IQ) to the client, and by "filter" is meant that the server will apply a rule to determine if the specific stanza will be delivered to the client (e.g., matching against a payload namespace); in general we refer to these actions as "sifting". The SIFT protocol enables the server to support only basic interception (even here to support interception only for particular kinds of stanzas), basic filtering as defined by the rules described in this specification, or advanced filtering using extensions to SIFT defined in other specifications. Each of the features supported by the server can be discovered by the client for maximum interoperability. The features, the process for discovering them, and the process for enabling them are described in the following sections.</p>
<section2 topic='Features' anchor='features'>
<p>SIFT supports the following features.</p>
<p>SIFT supports the features defined below. Each feature is identified by a separate value for 'var' attribute qualified by the 'http://jabber.org/protocol/disco#info' namespace as specified in &xep0030;.</p>
<section3 topic='Stanza Kinds' anchor='features-stanzas'>
<p>A server MAY support any combination of sifting IQ, message, or presence stanzas. For each kind of stanza that can be sifted, the server shall include in the features discovery result an &lt;iq-sift/&gt;, &lt;message-sift/&gt;, or &lt;presence-sift/&gt; element, respectively.</p>
<p>A server MAY support any combination of sifting IQ, message, or presence stanzas, as advertised by the following service discovery features.</p>
<dl>
<di>
<dt>iq-sift</dt>
<dt>urn:xmpp:sift:stanzas:iq</dt>
<dd>The server enables the client to sift all &IQ; stanzas or ones that match the specified criteria.</dd>
<dt>message-sift</dt>
<dt>urn:xmpp:sift:stanzas:message</dt>
<dd>The server enables the client to sift all &MESSAGE; stanzas or ones that match the specified criteria.</dd>
<dt>presence-sift</dt>
<dt>urn:xmpp:sift:stanzas:presence</dt>
<dd>The server enables the client to sift all &PRESENCE; stanzas or ones that match the specified criteria.</dd>
</di>
</dl>
</section3>
<section3 topic='Sender' anchor='features-sender'>
<p>A server MAY enable the client to sift based on sender. The following values are supported.</p>
<p>A server MAY enable the client to sift based on sender. The following features are supported.</p>
<dl>
<di>
<dt>all</dt>
<dt>urn:xmpp:sift:senders:all</dt>
<dd>The server shall sift this kind of stanza no matter who the sender is. This is the <strong>default</strong>.</dd>
<dt>local</dt>
<dt>urn:xmpp:sift:senders:local</dt>
<dd>The server shall sift this kind of stanza only from entities associated with the same local domain as the user itself (not from remote domains).</dd>
<dt>others</dt>
<dt>urn:xmpp:sift:senders:others</dt>
<dd>The server shall sift this kind of stanza only from other entities (not from the user itself).</dd>
<dt>remote</dt>
<dt>urn:xmpp:sift:senders:remote</dt>
<dd>The server shall sift this kind of stanza only from entities associated with remote domains (not from the same local domain as the user itself).</dd>
<dt>self</dt>
<dt>urn:xmpp:sift:senders:self</dt>
<dd>The server shall sift this kind of stanza only from the user itself (not from other entities).</dd>
</di>
</dl>
<p>These values are child elements of the &lt;iq-sift/&gt;, &lt;message-sift/&gt;, and &lt;presence-sift/&gt; elements when the server returns a features discovery result, whereas they are values of the 'sender' attribute when the client enables sift support.</p>
</section3>
<section3 topic='Recipient' anchor='features-recipient'>
<p>A server MAY enable the client to filter based on recipient. The following values are supported.</p>
<p>A server MAY enable the client to filter based on recipient. The following features are supported.</p>
<dl>
<di>
<dt>all</dt>
<dt>urn:xmpp:sift:recipients:all</dt>
<dd>The server shall sift this kind of stanza if the recipient is the bare JID &LOCALBARE; of the user or the full JID &LOCALFULL; of the particular resource. This is the <strong>default</strong>.</dd>
<dt>bare</dt>
<dt>urn:xmpp:sift:recipients:bare</dt>
<dd>The server shall sift this kind of stanza only if the recipient is the bare JID &LOCALBARE; of the user.</dd>
<dt>full</dt>
<dt>urn:xmpp:sift:recipients:full</dt>
<dd>The server shall sift this kind of stanza only if the recipient is the full JID &LOCALFULL; of the particular resource.</dd>
</di>
</dl>
<p>These values are child elements of the &lt;iq-sift/&gt;, &lt;message-sift/&gt;, and &lt;presence-sift/&gt; elements when the server returns a features discovery result, whereas they are values of the 'recipient' attribute when the client enables sift support.</p>
</section3>
<section3 topic='Payload' anchor='features-payload'>
<p>A server MAY enable the client to sift based on the XML namespace and element name of the payload(s) that the client allows for delivery. If so, the server shall include in the features discovery result an &lt;allow/&gt; element for the relevant kind of stanza.</p>
<p>A server MAY enable the client to sift based on the XML namespace and element name of the payload(s) that the client allows for delivery. If so, the server shall advertise a feature of <strong>urn:xmpp:sift:payloads:qname</strong>.</p>
</section3>
<section3 topic='Advanced Matching' anchor='features-advanced'>
<p>A server could match based on more complex criteria, e.g. Regular Expressions or XPath Expressions; such functionality is implicitly allowed because the XML schema specifies the &lt;xs:any/&gt; notation, but any such advanced matching shall be defined in separate specifications.</p>
</section3>
</section2>
<section2 topic='Discovering Supported Features' anchor='discovering'>
<p>If a server supports the SIFT protocol, it MUST advertise that fact in its responses to &xep0030; information ("disco#info") requests by returning a feature of "urn:xmpp:sift:1":</p>
<p>A client can discover if its server supports SIFT by sending a disco#info request.</p>
<example caption='A disco#info query'><![CDATA[
<iq type='get'
from='romeo@montague.lit/pda'
@ -225,55 +231,37 @@
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='A disco#info response'><![CDATA[
<p>If a server supports the SIFT protocol, it MUST advertise that fact in its responses to "disco#info" requests by returning a feature of "urn:xmpp:sift:1" &VNOTE;. The server MUST also specify which features it supports.</p>
<p>In the following reply, the server indicates that it supports a minimal subset of SIFT features merely for the sake of presence blocking.</p>
<example caption='Minimal server support'><![CDATA[
<iq type='result'
from='montague.lit'
to='romeo@montague.lit/pda'
id='bf4vb167'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:sift:1'/>
<feature var='urn:xmpp:sift:stanzas:presence'/>
</query>
</iq>
]]></example>
<p>This response enables the client to know that the server supports SIFT in general, but particular SIFT features. In order to discover which SIFT features are supported, a client sends an IQ-get containing a &lt;features/&gt; element qualified by the 'urn:xmpp:sift:1' namespace.</p>
<example caption="Client requests SIFT support details"><![CDATA[
<iq from='romeo@montague.lit/pda'
id='bn4hf91g'
to='montague.lit'
type='get'>
<features xmlns='urn:xmpp:sift:1'/>
</iq>
]]></example>
<p>The server then returns a list of the particular SIFT features it supports.</p>
<example caption="Server provides details regarding SIFT support"><![CDATA[
<iq from='montague.lit'
id='bn4hf91g'
<p>In the following reply, the server indicates that it supports a wider range of SIFT features.</p>
<example caption='More extensive server support'><![CDATA[
<iq type='result'
from='montague.lit'
to='romeo@montague.lit/pda'
type='result'>
<features xmlns='urn:xmpp:sift:1'>
<message-sift>
<recipient>
<all/>
</recipient>
<senders>
<all/>
<others/>
</senders>
</message-sift>
<presence-sift>
<recipient>
<all/>
</recipient>
<senders>
<all/>
<others/>
</senders>
</presence-sift>
</features>
id='bf4vb167'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:sift:1'/>
<feature var='urn:xmpp:sift:recipients:all'/>
<feature var='urn:xmpp:sift:senders:all'/>
<feature var='urn:xmpp:sift:senders:others'/>
<feature var='urn:xmpp:sift:stanzas:iq'/>
<feature var='urn:xmpp:sift:stanzas:message'/>
<feature var='urn:xmpp:sift:stanzas:presence'/>
</query>
</iq>
]]></example>
<p>The foregoing IQ-result indicates that montague.net supports only message and presence sifting, allows the client to filter those kinds of stanzas only from all entities or from other entities (but not from local entities, remote entities, or itself), allows the client to filter those kinds of stanzas only to <em>both</em> the bare JID and full JID (but not to the bare JID or the full JID alone), and does not support filtering based on payload.</p>
<p>Naturally, the server could return the typical XMPP error conditions, such as &unavailable; if the server does not support the SIFT protocol or the version specified by the client.</p>
<p>To enable clients to cache information about supported features, a server SHOULD return &xep0115; data via stream features as described in <cite>XEP-0115</cite>.</p>
</section2>
<section2 topic='Enabling SIFT' anchor='enabling'>
<p>To enable sifting of stanzas, the client sends an IQ-set to the server containing a &lt;sift/&gt; child element that in turn contains an &lt;iq/&gt; element, a &lt;message/&gt; element, a &lt;presence/&gt; element, or some combination of those elements. Each of these elements MAY include a 'recipient' attribute whose value is "all", "bare", or "full" (defaulting to "all"). Each of these elements MAY also include a 'sender' attribute whose value is "all", "local", "others", "remote", or "self" (defaulting to "all").</p>
@ -440,25 +428,6 @@
xmlns='urn:xmpp:sift:1'
elementFormDefault='qualified'>
<xs:element name='features'>
<xs:complexType>
<xs:sequence>
<xs:element name='iq-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='message-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='presence-sift'
type='featureElementType'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='sift'>
<xs:complexType>
<xs:sequence>
@ -478,28 +447,6 @@
</xs:complexType>
</xs:element>
<xs:element name='featureElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='recipient'
type='recipientElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='sender'
type='senderElementType'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='allow'
type='allowElementType'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:any namespace='##other'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='siftElementType'>
<xs:complexType>
<xs:sequence>
@ -538,65 +485,6 @@
</xs:complexType>
</xs:element>
<xs:element name='recipientElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='all'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='bare'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='full'
type='empty'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='senderElementType'>
<xs:complexType>
<xs:sequence>
<xs:element name='all'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='local'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='others'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='remote'
type='empty'
minOccurs='0'
maxOccurs='1'/>
<xs:element name='self'
type='empty'
minOccurs='0'
maxOccurs='1'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name='allowElementType'>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='name'
type='xs:NCName'
use='required'/>
<xs:attribute name='ns'
type='xs:anyURI'
use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
@ -608,7 +496,7 @@
</section1>
<section1 topic='Acknowledgements' anchor='acks'>
<p>The authors wish to acknowledge feedback received from Dave Cridland, Jack Erwin, Waqas Hussein, Craig Kaes, Dirk Meyer, Robert Quattlebaum, Mike Taylor, Matthew Wild, and Jiří Zárevúcký, as well as from the participants at XMPP Summit 7 on July 20-21, 2009.</p>
<p>The authors wish to acknowledge feedback received from Dave Cridland, Jack Erwin, Fabio Forno, Waqas Hussein, Craig Kaes, Dirk Meyer, Christopher Orr, Robert Quattlebaum, Mike Taylor, Matthew Wild, and Jiří Zárevúcký, as well as from participants at XMPP Summit #7 in July 2009 and XMPP Summit #8 in February 2010.</p>
</section1>
</xep>