mirror of https://github.com/moparisthebest/xeps
XEP-0455: initial update after acceptance
- Address the issue of the tmp namespace - Fixup abstract - Restructure to use subsections - Clarify usage of future date times - Clarify the pubsub node a bit further - Add some business rules & security considerations
This commit is contained in:
mathieui
Jonas Schäfer
parent
bdfedd4e8c
commit
64b62599a8
116
xep-0455.xml
116
xep-0455.xml
|
|
@ -7,7 +7,8 @@
|
|||
<xep>
|
||||
<header>
|
||||
<title>Service Outage Status</title>
|
||||
<abstract>This document defines an XMPP protocol extension that enables a server to communicate issues with the server to all users in a semantic manner.</abstract>
|
||||
<abstract>This document defines an XMPP protocol extension that enables server administrators
|
||||
to communicate issues with the server to all users in a semantic manner.</abstract>
|
||||
&LEGALNOTICE;
|
||||
<number>0455</number>
|
||||
<status>Experimental</status>
|
||||
|
|
@ -29,6 +30,12 @@
|
|||
<email>mathieui@mathieui.net</email>
|
||||
<jid>mathieui@mathieui.net</jid>
|
||||
</author>
|
||||
<revision>
|
||||
<version>0.2.0</version>
|
||||
<date>2021-02-09</date>
|
||||
<initials></initials>
|
||||
<remark>Evolve the standard: Editorial restructuring, add business rules and security considerations and clarify some wording.</remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.1.0</version>
|
||||
<date>2021-02-09</date>
|
||||
|
|
@ -54,11 +61,12 @@
|
|||
<li>A way to reference and archive such incidents, in a &xep0060; node</li>
|
||||
</ul>
|
||||
</section1>
|
||||
<section1 topic='External endpoint discovery' anchor='external-disco'>
|
||||
<p>To make such discovery possible, we specify a &xep0128; mechanism that a server SHOULD return in response to service discovery information ("disco#info") requests sent to the bare domain of the server. This information MUST be scoped using a FORM_TYPE of "urn:xmpp:tmp:sos" (as already specified in <cite>XEP-0128</cite>) and data form fields registered for this purpose as defined in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document.</p>
|
||||
<section1 topic='External status' anchor='external-status'>
|
||||
<section2 topic='Discovery' anchor='external-disco'>
|
||||
<p>To make such discovery possible, we specify a &xep0128; mechanism that a server SHOULD return in response to service discovery information ("disco#info") requests sent to the bare domain of the server. This information MUST be scoped using a FORM_TYPE of "urn:xmpp:sos:0" (as already specified in <cite>XEP-0128</cite>) and data form fields registered for this purpose as defined in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document.</p>
|
||||
|
||||
<p>Values of 'external-status-addresses' form field MUST be valid URIs, i.e. comply with the 'xs:anyURI' datatype of &w3xmlschema2;.</p>
|
||||
<example caption='Entity queries server for information'><![CDATA[
|
||||
<p>Values of 'external-status-addresses' form field MUST be valid URIs, i.e. comply with the 'xs:anyURI' datatype of &w3xmlschema2;.</p>
|
||||
<example caption='Entity queries server for information'><![CDATA[
|
||||
<iq from='thirdwitch@shakespeare.lit/chamber'
|
||||
to='shakespeare.lit'
|
||||
id='disco1'
|
||||
|
|
@ -67,7 +75,7 @@
|
|||
</iq>
|
||||
]]></example>
|
||||
|
||||
<example caption='Server communicates information'><![CDATA[
|
||||
<example caption='Server communicates information'><![CDATA[
|
||||
<iq from='shakespeare.lit'
|
||||
to='thirdwitch@shakespeare.list/chamber'
|
||||
id='disco1'
|
||||
|
|
@ -77,7 +85,7 @@
|
|||
<feature var='http://jabber.org/protocol/disco'/>
|
||||
<x xmlns='jabber:x:data' type='result'>
|
||||
<field var='FORM_TYPE' type='hidden'>
|
||||
<value>urn:xmpp:tmp:sos</value>
|
||||
<value>urn:xmpp:sos:0</value>
|
||||
</field>
|
||||
<field var='external-status-addresses'>
|
||||
<value>http://secondary.shakespeare.lit/status.json</value>
|
||||
|
|
@ -87,15 +95,15 @@
|
|||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>Links present inside the 'external-status-addresses' field SHOULD use HTTP/HTTPS protocol and the resources referenced MUST be available without authentication.</p>
|
||||
<p>Links present inside the 'external-status-addresses' field SHOULD use HTTP/HTTPS protocol and the resources referenced MUST be available without authentication.</p>
|
||||
|
||||
</section1>
|
||||
<section1 topic='External status format' anchor='json-schema'>
|
||||
<p>TODO: do we want this to be XML or json? I have no real preference, in any case it should be preferably generated by a tool but easy to write by hand, as this needs to be usable in situations where time is the essence.</p>
|
||||
<p>The format used for the external status is defined here, to allow a wide range
|
||||
of compatibility across services and clients.</p>
|
||||
<p>A client MUST ignore unknown extra fields present in the JSON file, to allow extensibility, and implementations MAY add other fields.</p>
|
||||
<example caption='Example status'><![CDATA[
|
||||
</section2>
|
||||
<section2 topic='External status format' anchor='json-schema'>
|
||||
<p>TODO: do we want this to be XML or json? I have no real preference, in any case it should be preferably generated by a tool but easy to write by hand, as this needs to be usable in situations where time is the essence.</p>
|
||||
<p>The format used for the external status is defined here, to allow a wide range
|
||||
of compatibility across services and clients.</p>
|
||||
<p>A client MUST ignore unknown extra fields present in the JSON file, to allow extensibility, and implementations MAY add other fields.</p>
|
||||
<example caption='Example status'><![CDATA[
|
||||
{
|
||||
"outage": "complete",
|
||||
"planned": true,
|
||||
|
|
@ -106,17 +114,23 @@
|
|||
"en": "The serveur is being updated"
|
||||
}
|
||||
}
|
||||
]]></example>
|
||||
|
||||
<p>The "message" field MUST contain at least a message on the "default" key, that will be
|
||||
used by the client if the current user language is not found. It is left to the
|
||||
operator to determine which language is more relevant as a default, according to the
|
||||
server’s user base.</p>
|
||||
|
||||
<p>When the outage is over, the file SHOULD be replaced with an empty JSON object.</p>
|
||||
|
||||
<example caption='Empty file after resolution of the issue'><![CDATA[
|
||||
{}
|
||||
]]></example>
|
||||
|
||||
<p>The "message" field MUST contain at least a message on the "default" key, that will be
|
||||
used by the client if the current user language is not found. It is left to the
|
||||
operator to determine which language is more relevant as a default, according to the
|
||||
server’s user base.</p>
|
||||
<p>The following JSON schema is provided as a means to describe and validate the
|
||||
file exposed by the external service:</p>
|
||||
|
||||
<p>The following JSON schema is provided as a means to describe and validate the
|
||||
file exposed by the external service:</p>
|
||||
|
||||
<code><![CDATA[
|
||||
<code><![CDATA[
|
||||
{
|
||||
"$id": "http://xmpp.org/server-outage-schema.json",
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
|
|
@ -159,24 +173,28 @@
|
|||
}
|
||||
}
|
||||
]]></code>
|
||||
</section2>
|
||||
|
||||
</section1>
|
||||
<section1 topic="Pubsub Node" anchor="pubsubnode">
|
||||
<section1 topic="In-band status" anchor="in-band-status">
|
||||
<section2 topic='PubSub Node' anchor='pubsubnode'>
|
||||
<p>For in-band notifications of server issues, a service with this extension SHOULD expose a 'urn:xmpp:sos:0'
|
||||
pubsub node with the acess model defined in &xep0222; on its bare JID.
|
||||
This pubsub node contains items describing outages and outage resolutions, and each item MUST have an 'id' attribute value containing
|
||||
the outage date and time, in &xep0082; format.</p>
|
||||
<p>Clients implementing this extension SHOULD subscribe to the '+notify' on that node, as defined in &xep0060;.</p>
|
||||
<p>Entities from other servers MAY be allowed to subscribe to other server nodes, to allow external services
|
||||
to monitor the server. Doing so allows aggregation of XMPP outage events across the network, for a better
|
||||
transparency.</p>
|
||||
</section2>
|
||||
<section2 topic='Outage event' anchor='outage-event'>
|
||||
|
||||
<p>For in-band notifications of server issues, a service MUST expose a pubsub node with the acess model defined in &xep0222;.
|
||||
This pubsub node contains items describing outages, and each item MUST have an 'id' attribute value containing
|
||||
the publishing time, in &xep0082; format.</p>
|
||||
<p>Clients implementing this extension SHOULD subscribe to the '+notify' on that node, as defined in &xep0060;.</p>
|
||||
<p>Entities from other servers MAY be allowed to subscribe to other server nodes, to allow an external service
|
||||
to monitor the server. Doing so allows aggregation of XMPP outage events across the network, for a better
|
||||
transparency.</p>
|
||||
|
||||
<example caption='Server operator publishes an outage event'><![CDATA[
|
||||
<example caption='Server operator publishes an outage event'><![CDATA[
|
||||
<iq from='firstwitch@shakespeare.lit/broom' to='shakespeare.lit' type='set' id='pub1'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:tmp:sos'>
|
||||
<publish node='urn:xmpp:sos:0'>
|
||||
<item id="2021-01-01T01:01:01Z">
|
||||
<outage xmlns='urn:xmpp:tmp:sos'>
|
||||
<outage xmlns='urn:xmpp:sos:0'>
|
||||
<description xml:lang='en'>The ICQ and MSN gateways are down</description>
|
||||
<description xml:lang='fr'>Les passerelles ICQ et MSN sont mortes</description>
|
||||
<planned>false</planned>
|
||||
|
|
@ -188,15 +206,15 @@
|
|||
</iq>
|
||||
]]></example>
|
||||
|
||||
<example caption='Client subscribed receives an outage event'><![CDATA[
|
||||
<example caption='Client subscribed receives an outage event'><![CDATA[
|
||||
<message from='shakespeare.lit'
|
||||
to='macbeth@shakespeare.lit/throne'
|
||||
type='headline'
|
||||
id='outagefoo'>
|
||||
<event xmlns='http://jabber.org/protocol/pubsub#event'>
|
||||
<items node='urn:xmpp:tmp:sos'>
|
||||
<items node='urn:xmpp:sos:0'>
|
||||
<item id="2021-01-01T01:01:01Z">
|
||||
<outage xmlns='urn:xmpp:tmp:sos'>
|
||||
<outage xmlns='urn:xmpp:sos:0'>
|
||||
<description xml:lang='en'>The ICQ and MSN gateways are down</description>
|
||||
<description xml:lang='fr'>Les passerelles ICQ et MSN sont mortes</description>
|
||||
<planned>false</planned>
|
||||
|
|
@ -208,6 +226,9 @@
|
|||
</message>
|
||||
]]></example>
|
||||
|
||||
</section2>
|
||||
<section2 topic='Outage End Event' anchor='outage-end-event'>
|
||||
|
||||
<p>When the outage is over, servers operators SHOULD publish an <outage-end/> element
|
||||
with the item id matching the time at which the issue was resolved. It can optionally
|
||||
contain a description.</p>
|
||||
|
|
@ -215,9 +236,9 @@
|
|||
<example caption='Server operator publishes an end of outage event'><![CDATA[
|
||||
<iq from='firstwitch@shakespeare.lit/broom' to='shakespeare.lit' type='set' id='pub2'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:tmp:sos'>
|
||||
<publish node='urn:xmpp:sos:0'>
|
||||
<item id="2021-01-01T02:05:01Z">
|
||||
<outage-end xmlns='urn:xmpp:tmp:sos'>
|
||||
<outage-end xmlns='urn:xmpp:sos:0'>
|
||||
<description xml:lang="en">Everything has been fixed!</description>
|
||||
<description xml:lang="fr">Tout a été corrigé !</description>
|
||||
</outage-end>
|
||||
|
|
@ -229,7 +250,7 @@
|
|||
|
||||
<p>Clients receiving this notification SHOULD remove the information about the outage from the user’s view, and MAY
|
||||
display the new message briefly.</p>
|
||||
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Use Cases' anchor='usecases'>
|
||||
<p>This extension has been thought for several different cases of service outages:</p>
|
||||
|
|
@ -241,13 +262,20 @@
|
|||
</section1>
|
||||
<section1 topic='Business Rules' anchor='rules'>
|
||||
<p>A client implementing this extension MUST fetch the addresses of the external service and cache it
|
||||
for a reasonable amount of time (several days), to be able to use it when an issue occurs</p>
|
||||
for later use. Doing so allows the client to use this information when it is impossible to connect
|
||||
to the server.</p>
|
||||
<p>A client receiving an outage event for a time in the future SHOULD treat it as a planned event
|
||||
that is not already happening and adapt its display consequently.</p>
|
||||
<p>When connected, a client SHOULD NOT fetch the external file as the in-band notification provides
|
||||
the same information, if available.</p>
|
||||
</section1>
|
||||
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
||||
<p>Both the JSON and the XML format defined in this document allow for internationalization in the fields that are expected to be presented to the user as-is. The other fields are machine-readable and their various values SHOULD be translated in the implementing applications.</p>
|
||||
</section1>
|
||||
<section1 topic='Security Considerations' anchor='security'>
|
||||
<p>Client implementations MUST check the provenance of the pubsub notifications before displaying a notification, otherwise malicious entities could send fake outage events.</p>
|
||||
<p>Server administrators MUST ensure the servers provided in 'external-status-addresses' are trusted, as malicious administrators of this server could use the referenced file
|
||||
to display arbitrary messages to users.</p>
|
||||
</section1>
|
||||
<section1 topic='IANA Considerations' anchor='iana'>
|
||||
<p>This document requires no interaction with &IANA;.</p>
|
||||
|
|
@ -255,10 +283,10 @@
|
|||
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||||
<p>The ®ISTRAR; includes the following information in its registries.</p>
|
||||
<section2 topic='Field Standardization' anchor='registrar-formtype'>
|
||||
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace, and <cite>XEP-0128</cite> describes how to use field standardization in the context of service discovery. This section registers fields for server information scoped by the "urn:xmpp:tmp:sos" FORM_TYPE.</p>
|
||||
<p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace, and <cite>XEP-0128</cite> describes how to use field standardization in the context of service discovery. This section registers fields for server information scoped by the "urn:xmpp:sos:0" FORM_TYPE.</p>
|
||||
<code caption='Registry Submission'><![CDATA[
|
||||
<form_type>
|
||||
<name>urn:xmpp:tmp:sos</name>
|
||||
<name>urn:xmpp:sos:0</name>
|
||||
<doc>XEP-XXXXX</doc>
|
||||
<desc>
|
||||
Form enabling a the registration of a machine-readable
|
||||
|
|
|
|||
Loading…
Reference in New Issue