mirror of https://github.com/moparisthebest/xeps
220 lines
9.5 KiB
XML
220 lines
9.5 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 xmlns="">
|
|
<header>
|
|
<title>PubSub Server Information</title>
|
|
<abstract>This document defines a data format whereby basic information of an XMPP domain can be expressed and exposed over pub-sub.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>xxxx</number>
|
|
<status>ProtoXEP</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies/>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>serverinfo</shortname>
|
|
<author>
|
|
<firstname>Guus</firstname>
|
|
<surname>der Kinderen</surname>
|
|
<email>guus.der.kinderen@gmail.com</email>
|
|
<jid>guus.der.kinderen@igniterealtime.org</jid>
|
|
</author>
|
|
<revision>
|
|
<version>1.0.0</version>
|
|
<date>2023-12-19</date>
|
|
<initials>gdk</initials>
|
|
<remark>
|
|
<ul>
|
|
<li>Initial version.</li>
|
|
</ul>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic="Introduction" anchor="intro">
|
|
<p>To facilitate discovery of information of individual domains in an XMPP-based network, this specification defines a data format to define basic information for individual XMPP domains. By leveraging &xep0060; this information can efficiently be shared with applications that compose an overview of the larger XMPP network.</p>
|
|
</section1>
|
|
<section1 topic="Requirements" anchor="requirements">
|
|
<ul>
|
|
<li>Describe links between nodes in an XMPP-based network, by enumerating connections used for federation between XMPP domains.</li>
|
|
<li>An extensible data format, allowing additional data (such as that defined in &xep0092;) to be retrievable without requiring additional round-trips.</li>
|
|
</ul>
|
|
</section1>
|
|
<section1 topic="Discovering Support" anchor="disco">
|
|
<p>Support is advertised by publishing a first-level leaf node using the name 'serverinfo' on a pub-sub service. An entity trying to discover support will, for a given domain name, use &xep0030; to identify a Publish-Subscribe service for the domain, and subsequently use service discovery to discover the node with name 'serverinfo' as defined in section 5.3 of &xep0060;.</p>
|
|
<example caption="Entity queries collection node for information"><![CDATA[
|
|
<iq type='get'
|
|
from='francisco@denmark.lit/barracks'
|
|
to='pubsub.shakespeare.lit'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='serverinfo'/>
|
|
</iq>]]></example>
|
|
<example caption="Service responds with identity of pubsub/leaf"><![CDATA[
|
|
<iq type='result'
|
|
from='pubsub.shakespeare.lit'
|
|
to='francisco@denmark.lit/barracks'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'
|
|
node='serverinfo'>
|
|
...
|
|
<identity category='pubsub' type='leaf'/>
|
|
...
|
|
</query>
|
|
</iq>]]></example>
|
|
</section1>
|
|
<section1 topic="Data Format" anchor="impl">
|
|
<p>The data format uses an element named 'serverinfo' in the namespace 'urn:xmpp:serverinfo:0'. In its minimal form, it defines each XMPP domain name served by the local server in an attribute named 'name'.</p>
|
|
<example caption="Minimal Data Format"><![CDATA[
|
|
<serverinfo xmlns='urn:xmpp:serverinfo:0'>
|
|
<domain name='shakespeare.lit'/>
|
|
</serverinfo>]]></example>
|
|
<p>The optional 'federation' child element is used to denote remote XMPP domains with which the local domain is federating. Each of them are represented by an element named 'remote-domain'. The domain name of the peer in an attribute named 'name'. Optionally, each actual (e.g. TCP) connection from the local server to the peer is added as a 'connection' child-element to the 'remote-domain' element, that has an optional 'type' attribute, defining the directionality of the connection (one of 'incoming', 'outgoing' and 'bidi').</p>
|
|
<example caption="Data Format with Federated Domains"><![CDATA[
|
|
<serverinfo xmlns="urn:xmpp:serverinfo:0">
|
|
<domain name="shakespeare.lit">
|
|
<federation>
|
|
<remote-domain name='denmark.lit'>
|
|
<connection type="incoming"/>
|
|
<connection type="outgoing"/>
|
|
</remote-domain>
|
|
<remote-domain name='montague.net'>
|
|
<connection type="bidi"/>
|
|
</remote-domain>
|
|
</federation>
|
|
</domain>
|
|
</serverinfo>]]></example>
|
|
<p>Additional data MAY be included as child-elements of the 'server-info' element or any of the 'domain' elements. Such data MUST be namespaced appropriately. The example below uses the 'query' element defined in &xep0092; to include information about the software application associated with the local server.</p>
|
|
<example caption="Data Format with Software Version"><![CDATA[
|
|
<serverinfo xmlns="urn:xmpp:serverinfo:0">
|
|
<domain name="shakespeare.lit">
|
|
<federation>
|
|
<remote-domain name='montague.net'>
|
|
<connection type="bidi"/>
|
|
</remote-domain>
|
|
</federation>
|
|
</domain>
|
|
<query xmlns='jabber:iq:version'>
|
|
<name>Openfire</name>
|
|
<version>4.8.0</version>
|
|
<os>Windows 11</os>
|
|
</query>
|
|
</serverinfo>]]></example>
|
|
</section1>
|
|
<section1 topic="Publication" anchor="impl">
|
|
<p>The data is to be published using a pub-sub node named 'serverinfo' that MUST be a first-level leaf node of a pub-sub service for the domain. It is RECOMMENDED that the leaf-node is configured to have an open access model and contain a maximum of 1 item.</p>
|
|
<example caption="Publish ServerInfo Item"><![CDATA[
|
|
<iq type='set'
|
|
from='william@shakespeare.lit/atwork'
|
|
to='pubsub.shakespeare.lit'
|
|
id='publish1'>
|
|
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
|
<publish node='serverinfo'>
|
|
<item id='current'>
|
|
<serverinfo xmlns="urn:xmpp:serverinfo:0">
|
|
<domain name="shakespeare.lit">
|
|
<federation>
|
|
<remote-domain name='denmark.lit'>
|
|
<connection type="incoming"/>
|
|
<connection type="outgoing"/>
|
|
</remote-domain>
|
|
<remote-domain name='montague.net'>
|
|
<connection type="bidi"/>
|
|
</remote-domain>
|
|
</federation>
|
|
</domain>
|
|
</serverinfo>
|
|
</item>
|
|
</publish>
|
|
</pubsub>
|
|
</iq>]]></example>
|
|
</section1>
|
|
<section1 topic="Implementation Notes" anchor="impl">
|
|
<p>As certain information can be expected to be updated continuously and frequently, the server MAY choose to reduce the frequency of updates of the 'serverinfo' pub-sub node.</p>
|
|
</section1>
|
|
<section1 topic="IANA Considerations" anchor="iana">
|
|
<p>This document requires no interaction with the &IANA;</p>
|
|
</section1>
|
|
<section1 topic="XMPP Registrar Considerations" anchor="registrar">
|
|
<section2 topic="Protocol Namespaces" anchor="registrar-ns">
|
|
<p>This specification defines the following XML namespaces:</p>
|
|
<ul>
|
|
<li>urn:xmpp:serverinfo:0</li>
|
|
</ul>
|
|
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
|
|
</section2>
|
|
</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='urn:xmpp:serverinfo:0'
|
|
xmlns='urn:xmpp:serverinfo:0'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:annotation>
|
|
<xs:documentation>
|
|
The protocol documented by this schema is defined in
|
|
XEP-0XXX: http://www.xmpp.org/extensions/xep-0XXX.html
|
|
</xs:documentation>
|
|
</xs:annotation>
|
|
|
|
<xs:element name="serverinfo" type="urn:serverinfoType" xmlns:urn="urn:xmpp:serverinfo:0"/>
|
|
|
|
<xs:simpleType name="directionType" final="restriction" >
|
|
<xs:restriction base="xs:string">
|
|
<xs:enumeration value="incoming" />
|
|
<xs:enumeration value="outgoing" />
|
|
<xs:enumeration value="bidi" />
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
<xs:complexType name="connectionType">
|
|
<xs:simpleContent>
|
|
<xs:extension base="xs:string">
|
|
<xs:attribute type="directionType" name="type" use="optional"/>
|
|
</xs:extension>
|
|
</xs:simpleContent>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name="remote-domainType">
|
|
<xs:sequence>
|
|
<xs:element type="urn:connectionType" name="connection" maxOccurs="unbounded" minOccurs="0" xmlns:urn="urn:xmpp:serverinfo:0"/>
|
|
</xs:sequence>
|
|
<xs:attribute type="xs:string" name="name" use="optional"/>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name="federationType">
|
|
<xs:sequence>
|
|
<xs:element type="urn:remote-domainType" name="remote-domain" maxOccurs="unbounded" minOccurs="0" xmlns:urn="urn:xmpp:serverinfo:0"/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name="domainType">
|
|
<xs:sequence>
|
|
<xs:element type="urn:federationType" name="federation" xmlns:urn="urn:xmpp:serverinfo:0"/>
|
|
</xs:sequence>
|
|
<xs:attribute type="xs:string" name="name"/>
|
|
</xs:complexType>
|
|
|
|
<xs:complexType name="serverinfoType">
|
|
<xs:sequence>
|
|
<xs:element type="urn:domainType" name="domain" xmlns:urn="urn:xmpp:serverinfo:0"/>
|
|
</xs:sequence>
|
|
</xs:complexType>
|
|
|
|
</xs:schema>
|
|
]]></code>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='acknowledgements'>
|
|
<p>Inspiration was taken from the (now defunct) 'server info' crawler by Thomas Leister. Many thanks to Dave Cridland, as well as 'zoidberg' and 'chewie' from the Ignite Realtime community for helping to test the initial implementation of a graphing implementation based on this XEP and to Florian Schmaus, Matthew Wild and Jonas Schäfer for their feedback on the earliest drafts of this document.</p>
|
|
</section1>
|
|
|
|
</xep>
|