ProtoXEP: Disco Feature Attachment

This commit is contained in:
Jérôme Poisson 2021-07-22 11:18:42 +02:00
parent acc6d5224e
commit fb20b7c15b
1 changed files with 139 additions and 0 deletions

View File

@ -0,0 +1,139 @@
<?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>Disco Feature Attachment</title>
<abstract>This specification provides a way to indicate that a feature is implemented for a specific namespace</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0030</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>dfa</shortname>
<author>
<firstname>Jérôme</firstname>
<surname>Poisson</surname>
<email>goffi@goffi.org</email>
<jid>goffi@jabber.fr</jid>
</author>
<revision>
<version>0.0.1</version>
<date>2021-07-22</date>
<initials>jp</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0030; is ubiquitous tools used by nearly every XMPP implementation. It's handy to declare that an entity implements a specific feature, but it can be confusing when a feature may be part of several functionalities. For instance, if a server advertise support &xep0059; and supports both &xep0163; and &xep0313;, we don't know if RSM is implemented only for PEP, only for MAM, or for both (it could be also implemented for other functionalities such as disco items).</p>
<p>In &xep0060; there is <link url="https://xmpp.org/extensions/xep-0060.html#subscriber-retrieve-returnsome">a workaround</link> which proposes to use <tt>http://jabber.org/protocol/pubsub#rsm</tt>, but this solution doesn't tell if RSM is implemented for MAM or any other protocol, it is Pubsub specific and not extensible.</p>
<p>To fix this situation, this XEP proposes a simple way to advertise that a feature is implemented for a specific functionality.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>It should be easy to implement Disco Feature Attachment both for the advertising entity and the requesting one, thus, the main requirement is to be based on &xep0030; without any other extensions.</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<ul>
<li><strong>Attached Feature</strong> — feature being attached to a specific functionality (e.g.: &xep0059;).</li>
<li><strong>Root Namespace</strong> — the main namespace of attached feature, the one normally advertised with &xep0030; (e.g.: <tt>http://jabber.org/protocol/rsm</tt>)</li>
<li><strong>Target Feature</strong> — feature on which the attached feature is implemented (e.g.: &xep0060;).</li>
<li><strong>Target Namespace</strong> — namespace of the feature on which attached feature is implemented (e.g. <tt>http://jabber.org/protocol/pubsub</tt>)</li>
<li><strong>Attachment Namespace</strong> — namespace indicating that a feature is attached to an other one. (e.g. <tt>http://jabber.org/protocol/rsm@http://jabber.org/protocol/pubsub</tt>)</li>
</ul>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>An XMPP server <tt>example.com</tt> wants to advertise support for &xep0059;, it is implemented for:</p>
<ul>
<li>&xep0030; (for discovering items)</li>
<li>&xep0163;</li>
<li>&xep0313;</li>
</ul>
<p>To do that, the server MUST advertise the root namespace as usual (here <tt>http://jabber.org/protocol/rsm</tt>), and it MUST advertise the attachment namespace for every supported target feature:</p>
<example caption="Service Discovery information request"><![CDATA[
<iq from='example.org'
id='disco1'
to='example.com'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service Discovery information response"><![CDATA[
<iq from='example.com'
id='disco1'
to='example.org'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/rsm'/>
<feature var='http://jabber.org/protocol/rsm@http://jabber.org/protocol/pubsub'/>
<feature var='http://jabber.org/protocol/rsm@urn:xmpp:mam:2'/>
<feature var='http://jabber.org/protocol/rsm@http://jabber.org/protocol/disco#items'/>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<p>An attachment namespace is build by concatenating those 3 strings</p>
<ul>
<li>the root namespace of the attached feature (e.g.: <tt>urn:xmpp:order-by:1</tt>)</li>
<li>the character <tt>@</tt></li>
<li>the target namespace (e.g.: <tt>http://jabber.org/protocol/pubsub</tt>)</li>
</ul>
<p>Here the resulting attachment namespace is <tt>urn:xmpp:order-by:1@http://jabber.org/protocol/pubsub</tt> and it means "<em>the &xep0413; feature is implemented for &xep0060;</em>".</p>
<p>If a functionality has several namespaces linked to it (e.g. &xep0060; has <tt>http://jabber.org/protocol/pubsub</tt>, <tt>http://jabber.org/protocol/pubsub#owner</tt>, <tt>http://jabber.org/protocol/pubsub#event</tt>, etc.), the one to be chosen it the one used for advertising with &xep0030; (here it's <tt>http://jabber.org/protocol/pubsub</tt>).</p>
<p>If attached feature is only implemented for part of a functionality, only the corresponding namespace must be used in attachment namespace (e.g. if RSM is implemented only for discovering items but not features, the attachment namespace to advertise is only <tt>http://jabber.org/protocol/rsm@http://jabber.org/protocol/disco#items</tt>).</p>
<p>If a XEP has special requirements regarding disco feature attachments, then they MAY be specified there, in which case they take precedence over the rules defined here.</p>
</section1>
<section1 topic='discovering support' anchor='disco'>
<p>If an entity supports the "Disco Feature Attachment" protocol, it MUST advertise it by including the "urn:xmpp:dfa:0" discovery feature &NSNOTE; in response to a &xep0030; information request:</p>
<example caption="service discovery information request"><![CDATA[
<iq from='example.org'
id='disco1'
to='example.com'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="service discovery information response"><![CDATA[
<iq from='example.com'
id='disco1'
to='example.org'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='urn:xmpp:dfa:0'/>
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This document introduces no security considerations or concerns above and beyond those discussed in <cite>RFC 6120</cite> and <cite>RFC 6125</cite>.</p>
</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>TODO</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>TODO</p>
</section1>
</xep>