mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 00:35:02 -05:00
inbox: add ProtoXEP "Service Outage Status"
This commit is contained in:
mathieui
parent
0d45eb27b4
commit
d58d4e3c25
272
inbox/service-outage-status.xml
Normal file
272
inbox/service-outage-status.xml
Normal file
@ -0,0 +1,272 @@
|
||||
<?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 a server to communicate issues with the server to all users in a semantic manner.</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-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.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 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>
|
||||
|
||||
<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:tmp:sos</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>
|
||||
|
||||
</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[
|
||||
{
|
||||
"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>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>
|
||||
|
||||
</section1>
|
||||
<section1 topic="Pubsub Node" anchor="pubsubnode">
|
||||
|
||||
<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[
|
||||
<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'>
|
||||
<item id="2021-01-01T01:01:01Z">
|
||||
<outage xmlns='urn:xmpp:tmp:sos'>
|
||||
<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:tmp:sos'>
|
||||
<item id="2021-01-01T01:01:01Z">
|
||||
<outage xmlns='urn:xmpp:tmp:sos'>
|
||||
<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>
|
||||
|
||||
<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:tmp:sos'>
|
||||
<item id="2021-01-01T02:05:01Z">
|
||||
<outage-end xmlns='urn:xmpp:tmp:sos'>
|
||||
<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>
|
||||
|
||||
</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 a reasonable amount of time (several days), to be able to use it when an issue occurs</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>
|
||||
</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:tmp:sos" FORM_TYPE.</p>
|
||||
<code caption='Registry Submission'><![CDATA[
|
||||
<form_type>
|
||||
<name>urn:xmpp:tmp:sos</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>
|
||||
Loading…
Reference in New Issue
Block a user