mirror of https://github.com/moparisthebest/xeps
307 lines
14 KiB
XML
307 lines
14 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>
|
||
<header>
|
||
<title>Service Outage Status</title>
|
||
<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>
|
||
<type>Standards Track</type>
|
||
<sig>Standards</sig>
|
||
<approver>Council</approver>
|
||
<dependencies>
|
||
<spec>XMPP Core</spec>
|
||
<spec>XEP-0060</spec>
|
||
<spec>XEP-0128</spec>
|
||
<spec>XEP-0222</spec>
|
||
</dependencies>
|
||
<supersedes/>
|
||
<supersededby/>
|
||
<shortname>NOT_YET_ASSIGNED</shortname>
|
||
<author>
|
||
<firstname>Mathieu</firstname>
|
||
<surname>Pasquet</surname>
|
||
<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>
|
||
<initials>XEP Editor (jsc)</initials>
|
||
<remark>Accepted by vote of Council on 2021-01-20.</remark>
|
||
</revision>
|
||
<revision>
|
||
<version>0.0.1</version>
|
||
<date>2021-01-18</date>
|
||
<initials>mp</initials>
|
||
<remark><p>First draft.</p></remark>
|
||
</revision>
|
||
</header>
|
||
<section1 topic='Introduction' anchor='intro'>
|
||
<p>The XMPP Network is a network of servers which each have their own administration policies, status reports, and other peculiarities. &xep0157; provides a consistent framework for reaching out to administrators and reporting abuse, incidents, or even giving feedback on the service, and the goal of this specification is to provide a similar framework for letting users (or other entities) know the server status in-band or out of band (in case of hard failures).</p>
|
||
<p>Centralized systems usually control both the infrastructure and client code, making it easy to hardcode information retrieval one way or the other.</p>
|
||
<p>The usual way of informing users of planned maintenance, partial or total outage was previously through "announce" modules that lets the admin broadcast server-wided messages. This approach has several drawbacks, as it will appear in most clients as a new discussion with the server JID, which can prove confusing. It also does not provide a way to reach the user when the XMPP server is offline.</p>
|
||
<p>This XEP provides:</p>
|
||
<ul>
|
||
<li>An informational way of exposing an external service endpoint containing machine-readable data using &xep0128;</li>
|
||
<li>A specification of the data this service should provide</li>
|
||
<li>A normative way of providing such information in-band, when the outage is not complete</li>
|
||
<li>A way to reference and archive such incidents, in a &xep0060; node</li>
|
||
</ul>
|
||
</section1>
|
||
<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[
|
||
<iq from='thirdwitch@shakespeare.lit/chamber'
|
||
to='shakespeare.lit'
|
||
id='disco1'
|
||
type='get'>
|
||
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||
</iq>
|
||
]]></example>
|
||
|
||
<example caption='Server communicates information'><![CDATA[
|
||
<iq from='shakespeare.lit'
|
||
to='thirdwitch@shakespeare.list/chamber'
|
||
id='disco1'
|
||
type='result'>
|
||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||
<identity category='server' type='im'/>
|
||
<feature var='http://jabber.org/protocol/disco'/>
|
||
<x xmlns='jabber:x:data' type='result'>
|
||
<field var='FORM_TYPE' type='hidden'>
|
||
<value>urn:xmpp:sos:0</value>
|
||
</field>
|
||
<field var='external-status-addresses'>
|
||
<value>http://secondary.shakespeare.lit/status.json</value>
|
||
</field>
|
||
</x>
|
||
</query>
|
||
</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>
|
||
|
||
</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,
|
||
"beginning": "2021-01-12T01:01:01Z",
|
||
"expected_end": "2021-01-12T05:00:00Z",
|
||
"message": {
|
||
"default": "Mise à jour du serveur",
|
||
"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 following JSON schema is provided as a means to describe and validate the
|
||
file exposed by the external service:</p>
|
||
|
||
<code><![CDATA[
|
||
{
|
||
"$id": "http://xmpp.org/server-outage-schema.json",
|
||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||
"title": "XMPP Server Outage Format",
|
||
"type": "object",
|
||
"required": ["beginning"],
|
||
"additionalProperties": true,
|
||
"properties": {
|
||
"outage": {
|
||
"type": "string",
|
||
"enum": ["partial", "complete"],
|
||
"description": "The outage status (partial or complete)."
|
||
},
|
||
"planned": {
|
||
"type": "boolean",
|
||
"description": "If the outage was planned or not."
|
||
},
|
||
"beginning": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "Approximate time of the start of the outage."
|
||
},
|
||
"expected_end": {
|
||
"type": "string",
|
||
"format": "date-time",
|
||
"description": "Estimated time of the end of the outage (if known)."
|
||
},
|
||
"message": {
|
||
"type": "object",
|
||
"description": "Textual message to service users, each key being 'defaul' or a BCP47 language tag.",
|
||
"required": ["default"],
|
||
"properties": {
|
||
"default": { "type": "string"}
|
||
},
|
||
"patternProperties": {
|
||
"default": {"type": "string"},
|
||
".*": {"type": "string"}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
]]></code>
|
||
</section2>
|
||
|
||
</section1>
|
||
<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'>
|
||
|
||
<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:sos:0'>
|
||
<item id="2021-01-01T01:01:01Z">
|
||
<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>
|
||
<expected_end>2021-01-01T05:00:00Z</expected_end>
|
||
</outage>
|
||
</item>
|
||
</publish>
|
||
</pubsub>
|
||
</iq>
|
||
]]></example>
|
||
|
||
<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:sos:0'>
|
||
<item id="2021-01-01T01:01:01Z">
|
||
<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>
|
||
<expected_end>2021-01-01T05:00:00Z</expected_end>
|
||
</outage>
|
||
</item>
|
||
</items>
|
||
</event>
|
||
</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>
|
||
|
||
<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:sos:0'>
|
||
<item id="2021-01-01T02:05:01Z">
|
||
<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>
|
||
</item>
|
||
</publish>
|
||
</pubsub>
|
||
</iq>
|
||
]]></example>
|
||
|
||
<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>
|
||
<ul>
|
||
<li>A client failing to connect to a server is able to display an informative message to the user if the server is having issues.</li>
|
||
<li>A server experiencing difficulties is able to communicate it to the users, and clients can display the information prominently.</li>
|
||
<li>An external service can keep track of the various outages, either for a single server or a number of them, and present the information in a structured manner.</li>
|
||
</ul>
|
||
</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 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>
|
||
</section1>
|
||
<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:sos:0" FORM_TYPE.</p>
|
||
<code caption='Registry Submission'><![CDATA[
|
||
<form_type>
|
||
<name>urn:xmpp:sos:0</name>
|
||
<doc>XEP-XXXXX</doc>
|
||
<desc>
|
||
Form enabling a the registration of a machine-readable
|
||
external file to describe a service status.
|
||
</desc>
|
||
<field
|
||
var='external-status-addresses'
|
||
type='list-multi'
|
||
label='One or more addresses containing a file with the server status'/>
|
||
</form_type>
|
||
]]></code>
|
||
</section2>
|
||
</section1>
|
||
<section1 topic='XML Schema' anchor='schema'>
|
||
<p>REQUIRED for protocol specifications.</p>
|
||
</section1>
|
||
</xep>
|