1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 02:02:16 -05:00
xeps/xep-0403.xml
2018-06-06 14:28:47 +01:00

460 lines
23 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'?>
<?xml-stylesheet type="text/css" href="xmpp.css"?>
<xep>
<header>
<title>Mediated Information eXchange (MIX): Presence Support.</title>
<abstract>This document defines an extension to Mediated Information eXchange (MIX) specified in XEP-0369 to provide presence information for MIX clients to MIX channel participants. It also specifies relay of IQ stanzas through a MIX channel. </abstract>
&LEGALNOTICE;
<number>0403</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0054</spec>
<spec>XEP-0060</spec>
<spec>XEP-0084</spec>
<spec>XEP-0128</spec>
<spec>XEP-0198</spec>
<spec>XEP-0292</spec>
<spec>XEP-0297</spec>
<spec>XEP-0313</spec>
<spec>XEP-0369</spec>
<spec>XEP-0372</spec>
<spec>XEP-0404</spec>
<spec>XEP-0405</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>MIX-PRESENCE</shortname>
&ksmithisode;
&skille;
<revision>
<version>0.3.0</version>
<date>2018-06-06</date>
<initials>sek</initials>
<remark><p>
Allow mapped resource in presence;
Remove extraneous vCard checks;
</p></remark>
</revision>
<revision>
<version>0.2.0</version>
<date>2018-06-05</date>
<initials>sek</initials>
<remark><p>
Change JID Addressing of IQs and Presence;
Clarify routing if IQs through channel;
Add vCard routing;
Add mix information to presence;
</p></remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2018-05-21</date>
<initials>sek</initials>
<remark><p>
Split out from MIX 0.10.0;
</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The Mediated Information eXchange (MIX) protocol framework and core capabilities for message distribution are specified in &xep0369; (MIX-CORE). This specification enables presence status of online clients belonging to channel participants to be shared through the channel with participants that wish to see this presence status. This is a achieved by a MIX presence node, which channel participants may subscribe to.
</p>
<p>
MIX-CORE shares participant JIDs, which enables messages to be exchange directly.
To facilitate communication between clients IQ stanzas MAY be routed through a MIX channel. This is needed because IQ stanzas from an unknown JID may be blocked. Routing IQ stanzas through the channel avoids this.
</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This specification addressed a number of presence requirements:</p>
<ol>
<li>The mechanism must work cleanly for participants with multiple clients.</li>
<li>Standard presence messages must be used to share presence.</li>
<li>Nick changes should be visible as changes (and not as a new user).</li>
<li>Where &xep0404; (MIX-ANON) is not used, a mechanism is needed so that participants are able to directly contact other participants.</li>
<li>IQ stanzas, including vCard, can be be sent indirectly through a MIX channel.</li>
</ol>
</section1>
<section1 topic='Concepts' anchor='concepts'>
<section2 topic="Participant Information in Presence" anchor="concept-participant-info">
<p>
A MIX channel implementing this specification MUST be able to distribute presence information about channel participants. In order to share JID and Nick information about a participant, this information is encoded in the presence message. This allows full presence information to be shared for each participant without the need for the client to perform any lookup.
</p>
</section2>
<section2 topic="Partipant JID Addressing for Presence and IQ relay" anchor="concept-jid-address">
<p>
Participants in Presence messages and in IQ messages relayed through a channel are identified by an encoded JID of the form are encoded, using the format "&lt;stable-participant-identifier&gt;#&lt;channel&gt;@&lt;mix domain&gt;". This provides a stable JID for each participant. This JID format is used in three places:
</p>
<ol>
<li>The 'from' of presence stanzas generated by the channel, where the from encodes the Stable Participant ID of the participant to which the presence stanza relates.</li>
<li>The 'to' of IQ stanzas being addresses to a participant and being sent to the channel for indirect communication.</li>
<li>The 'from' of IQ stanzas coming from the channel, to reflect the sending participant where this stanza is being relayed by the channel.</li>
</ol>
<p>
These JIDs will be used to represent specific JID clients. The resource associated with the encoded JID can be either of the follipwing two options:
</p>
<ol>
<li>The resource value from the associated client JID; or</li>
<li>A mapped valued to an anonymized value. This approach MUST be used with MIX-ANON.</li>
</ol>
</section2>
<section2 topic="User Presence in MIX" anchor="concepts-presence">
<p>
MIX channels store presence of each online client for a user that chooses to publish presence, in the format that is distributed as presence. Presence is stored in the presence node with an item for each client that is publishing presence. Each item is named with an encoded JID and contains the presence information that is distributed. Where a user publishes presence for one or more clients, this information is available to all users subscribing to the channel presence.
</p>
<p>
A client participating in a MUC channel MAY send it's presences status to the MIX channel using standard presence. The mechanisms to do this are summarized in the next section and standardized in &xep0405;.
</p>
<p>
The MIX channel will distribute received presence to participants that have subscribed to the participants node. The client to which each presence update refers is identified by the &lt;from&gt; of the presence sent by the MIX channel, using the encoded JID format.
</p>
<p>
Presence updates are distributed by a channel to the bare JID of each participant and then the subscriber's server will distribute to each of the participant's currently online clients following the rules set out in &xep0405;.
</p>
</section2>
<section2 topic="MIX Channels in Roster" anchor="concepts-roster">
<p>
When a user joins a MIX channel, the channel MUST be added to the user's roster, as specified in &xep0405;. There are two reasons for this.
</p>
<ol>
<li>It enables a client to determine which channels the user has joined and so may expect messages and/or presence updates from (dependent on what the user has subscribed to).</li>
<li>
When the user has chosen to share presence with the channel, it enables this to happen using standard presence mechanisms. This avoids the need for MIX-specific mechanisms for clients to update presence on a channel. When a client comes online, presence information will be sent to each MIX channel that the user participates in. This will update other channel participants. It will also lead to a presence update for each MIX channel being sent to the client. So a user will receive channel presence information as the user comes online, in contrast to being subsequent to a MUC Join.
</li>
</ol>
</section2>
<section2 topic="Presence Node" anchor="presence-node">
<p>MIX defines one node to support presence, as summarized in the table below. This node is required to support this specification.</p>
<table caption="MIX Presence Node">
<tr><th>Name</th><th>Node</th><th>Description</th><th>Update</th><th>Distribution</th></tr>
<tr><td>Presence</td><td>'urn:xmpp:mix:nodes:presence'</td><td>For storing information about the availability status of online participants, which MAY include multiple clients for a single participant.</td><td>Presence</td><td>Presence</td></tr>
</table>
<p>
The presence node contains the presence value for clients belonging to participants that choose to publish presence to the channel. A MIX channel MAY require that all participants publish presence, so that active channel participants are visible. It is not possible to enforce this in the server, so participants in a channel with this option MUST publish presence. Each item in the presence node is identified by an encoded JID. The presence is encoded as a standard a presence stanza using a &lt;presence/&gt; element qualified by the 'jabber:client' namespace.
</p>
<p>
MIX extends the &lt;presence&gt; stanza using a &lt;mix&gt; element qualified by the 'urn:xmpp:mix:presence:0' namespace. This enables any receiver of presence to identify the JID of the client to which the presence presence refers and to have a nick to display. This element contains two child elements:
</p>
<ol>
<li>A &lt;nick&gt; element that contains the Nick of the message sender, taken from the Participants Node. This MUST be present if a Nick is defined for the user.</li>
<li>A &lt;jid&gt; element containing the full JID of the client. This MUST be present, unless following the "JID Hidden" model defined in MIX-ANON. If this element is omitted, the &lt;nick&gt; element MUST be present.</li>
</ol>
<p>
This node MAY be subscribed to by users using the user's bare JID. So presence of online clients is sent to the user's server for each user subscribed to this node. Presence is always sent using standard presence protocol and MUST NOT be sent using pubsub protocol. Clients MUST NOT directly access the presence node using pubsub. The Presence node is a permanent PubSub node. The following example shows a presence node value for the client with full JID 'hecate@shakespeare.example/UUID-x4r/2491'.
</p>
<example caption="Value of Presence Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:presence'>
<item id='123456#coven@mix.shakespeare.example/UUID-x4r/2491'>
<presence xmlns='jabber:client'>
<mix xmlns='urn:xmpp:presence:0'>
<jid>hecate@shakespeare.example/UUID-x4r/2491</jid>
<nick>thirdwitch</jid>
</mix>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
</item>
</items>
]]></example>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Setting User Presence' anchor='usecase-user-presence'>
<p>
A user joins a channel over an extended period, and participation in a channel does not generally change when user goes online or offline. The user's participation in a channel is reflected by the user's bare JID in the participant node. All messages to the channel are sent to this JID.
</p>
<p>
A user MAY share presence information with the channel, for one or more online clients. The channel is entered by the user's server into the user's roster when the user subscribes to the channel as specified in &xep0405;. Where a user shares presence information with a channel, the subscription is configured with one way presence, which will cause all presence changes for the client to be sent to the channel.
When an XMPP client comes online or changes presence status, this will be communicated by the user to the user's server using broadcast presence. The user's XMPP server is then responsible to share this presence information to each entry in the roster and in particular to each MIX channel in the roster.
</p>
<p>
The MIX channel will update the "urn:xmpp:mix:nodes:presence" node with any change of status and the updated presence information and then share this updated presence with users subscribed to this node, as described below. When the user sets an explicit status, this is used to modify the presence node in the channel. When a client being used by the user goes offline, the associated server will send presence status "unavailable" to the MIX channel, which will cause the node item for that client to be removed from the presence node.
</p>
<p>
Presence status and availability is set in a MIX channel by standard presence stanzas sent to the MIX channel by the user's server. Users wishing to receive presence updates will subscribe to the MIX channel presence node. Presence updates are sent out to subscribing participants using standard presence stanzas.
</p>
<p>
A user setting status is now used as an example. Unlike in &xep0045; where coming online is a special action, coming online in MIX is implicit when presence status is set. Going offline is a achieved by setting presence status to unavailable, which removes the client full JID entry from the presence node. When a user sets a presence status, the user's server sends updated presence to the MIX channel, and the MIX service then publishes the user's availability to the "urn:xmpp:mix:nodes:presence" node. If there is not an item named by the full JID of the client with updated presence status, this item is created. The sequence is shown in the following examples, starting with a client setting presences status on the connected server.</p>
<example caption="Client Sets Presence Status on Server">
<![CDATA[<presence xmlns='jabber:client'
from='hag66@shakespeare.example/UUID-a1j/7533'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
<p>
The server then sends the presence information to roster entries. The following example then shows the presence message from the client's server to the MIX channel.
</p>
<example caption="Server sends Presence Status to MIX Channel">
<![CDATA[<presence from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
<p>The user's presence information is then published by the service to the "urn:xmpp:mix:nodes:presence" node. The MIX channel then broadcasts the presence change to all users who are subscribed to the "urn:xmpp:mix:nodes:presence" node. The presence stanza 'from' uses an encoded JID.
Note that presence is associated with a client and so will have a full JID. The following example shows a presence message as distributed by the server to a presences subscriber.</p>
<example caption="Channel Distributes Presence">
<![CDATA[<presence from='123435#coven@mix.shakespeare.example/UUID-a1j/7533'
to='hag99@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
<mix xmlns='urn:xmpp:presence:0'>
<jid>hecate@shakespeare.example/UUID-x4r/2491</jid>
<nick>thirdwitch</jid>
</mix>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
<p>
The presence is distributed to those subscribing to the MIX channel presence node using a standard XMPP presence stanza. The presence change is recorded on the "urn:xmpp:mix:nodes:presence" node.
</p>
<p>
The history of the presence node MAY be archived using MAM. The MAM archive stores the node in PubSub format, following the node specification. This enables presence history to be retrieved using PubSub.
</p>
</section2>
<section2 topic="Client Coming Online and Obtaining Presence from the Local Server" anchor="usecase-obtaining-presence">
<p>
MIX Clients obtain presence from their local server. This is specified in &xep0405;.
</p>
</section2>
<section2 topic='Going Offline' anchor='usecase-user-offline'>
<p>When a client goes offline, this presence update is sent by the client's server to the MIX channel. From the client perspective, this is the same as any other presence change. The MIX Channel also needs to remove the client from the participant's node.</p>
<example caption="Client Goes Offline in the Channel"><![CDATA[
<presence type='unavailable'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'/>
]]></example>
<p>The MIX channel will retract (remove) the item in the presence node of the MIX channel identified by the client's full JID. The MIX channel will notify subscribers to the presence node of the user going offline by sending a presence stanza to the full JID of each client. The presence stanza will use the encoded JID of the client that is going offline, as shown in the following example:</p>
<example caption="Channel Distributes Notification of Client going Offline">
<![CDATA[<presence from='12345#coven@mix.shakespeare.example/UUID-a1j/7533'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='unavailable'>
<mix xmlns='urn:xmpp:presence:0'>
<jid>hecate@shakespeare.example/UUID-x4r/2491</jid>
<nick>thirdwitch</jid>
</mix>
</presence>]]></example>
<p>
There is the possibility that the message associated with the user going offline will be lost. If this happens, "ghost" entries will appear in the presence node. A MIX service MAY take steps to address this, for example by probing client with a disco for presence items that remain unchanged for a long period.
</p>
</section2>
<section2 topic="User Leaving a Channel" anchor="usecase-presence-leave">
<p>
The primary actions for a user leaving a channel are specified in &xep0369;. This section sets out additional actions for handling presence. When a user leaves the channel, all entries for the user's clients MUST be removed from the participants node. The MIX channel MUST distribute unavailable presence notifications for each client removed to all subscribers of the participants node.
</p>
<example caption="Channel Distributes Notification when User Leaves Channel">
<![CDATA[<presence from='12345#coven@mix.shakespeare.example/UUID-a1j/7533'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='unavailable'>
<mix xmlns='urn:xmpp:presence:0'>
<jid>hecate@shakespeare.example/UUID-x4r/2491</jid>
<nick>thirdwitch</jid>
</mix>
</presence>]]></example>
</section2>
<section2 topic="Relaying IQ Stanzas" anchor="usecase-iq-relay">
<p>
MIX channels MAY relay IQ stanzas between participants. This is often useful to obtain client information where a direct request to the client would be blocked. When a client sends an IQ stanza through a MIX channel, it will set the 'from' to its own JID and set the 'to' to the encoded JID of the recipient. Participants may be addressed by full JID or bare JID. The MIX channel will modify the JIDs in the outgoing message, so that the 'to' is the full JID of the recipient and the 'from' is the encoded JID of the sender. This is illustrated in the vCard section below.
</p>
</section2>
<section2 topic="Requesting a vCard through a Channel" anchor="usecase-vcard">
<p>A client MAY request the vCard of a channel participant through a MIX channel, for example to get an avatar. The MIX channel MAY pass this request on or MAY block it. vCard requests MAY use &xep0054; (vcard-temp) or &xep0292; (vCard4 over XMPP). The MIX channel does not process the vCard requests, but simply relays them on to real bare JID of the target. A MIX service MAY choose to relay one or both protocols. In the following example, using vcard-temp, the requesting client sends a message to the encoded JID of the channel participant for which the vCard is desired.</p>
<example caption="Client directly requests vCard through channel" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='lx09df27'
to='989898#coven@mix.shakespeare.example'
type='get'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>The MIX channel MAY pass on the vCard request or MAY reject with an error, dependent on channel policy. The MIX service will then address the vCard request to the user's server (using bare JID) using an the encoded JID of the requester in the 'from'. </p>
<example caption="Channel passes on vCard request to the User&apos;s Server" ><![CDATA[
<iq from='123456#coven@mix.shakespeare.example/6789'
id='lx09df27'
to='peter@shakespeare.example'
type='get'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>
The user's server, on behalf of the user, MUST send a response or reject with an error. The user's server will send the vCard back to the channel.
</p>
<example caption="User's Server sends vCard Response via MIX channel" ><![CDATA[
<iq from='peter@shakespeare.example'
id='lx09df27'
to='123456#coven@mix.shakespeare.example/6789'
type='result'>
<vCard xmlns='vcard-temp'>
<FN>Peter Saint-Andre</FN>
<N>
<FAMILY>Saint-Andre</FAMILY>
<GIVEN>Peter</GIVEN>
<MIDDLE/>
</N>
<NICKNAME>stpeter</NICKNAME>
<URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
</vCard>
<query xmlns='http://jabber.org/protocol/disco#info'>
</iq>
]]></example>
<p>
The MIX channel will then send the vCard response to the requesting client on behalf of the client sending the response.
</p>
<example caption="MIX Channel sends vCard responst to Client" ><![CDATA[
<iq from='989898#coven@mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<vCard xmlns='vcard-temp'>
<FN>Peter Saint-Andre</FN>
<N>
<FAMILY>Saint-Andre</FAMILY>
<GIVEN>Peter</GIVEN>
<MIDDLE/>
</N>
<NICKNAME>stpeter</NICKNAME>
<URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
</vCard>
</iq>
]]></example>
</section2>
</section1>
<section1 topic="Presence Initializion" anchor="use-presence-initialize">
<p>
For an active MIX Channel, the presence node is updated as channel participants change status and presence information is sent to the channel. When a MIX channel starts, typically when the associated MIX Service and Server start, there is a need to initialize the presence node. This is done by the XMPP server associated with the MIX channel sending out a presence probe for each channel participant, following the presence probe process specified in &rfc6121;. A presence probe MUST NOT be sent for users who have set presence preference to not sharing.
</p>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>See considerations in &xep0369;.
</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>See considerations in &xep0369;.</p>
<p>
When converting a 1:1 conversation to a channel there is potential to expose sensitive information and to present invalid information.
</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>None.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>The urn:xmpp:mix namespace needs to be registered.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To be supplied when MIX progresses to proposed standard.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>See &xep0369; for a list of contributors to the MIX Family of specifications.</p>
</section1>
</xep>