moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-24 10:12:19 -05:00
Code Issues Releases Wiki Activity

Editorial

Browse Source
This commit is contained in:
Steve Kille 2018-05-21 09:05:17 +01:00
parent 8c2f8ef260
commit 3afbdf0ee4
1 changed files with 31 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

173
xep-0403.xml
View File

@ -30,6 +30,7 @@
<spec>XEP-0313</spec>
<spec>XEP-0369</spec>
<spec>XEP-0372</spec>
<spec>XEP-0405</spec>
</dependencies>
<supersedes/>
<supersededby/>
@ -58,7 +59,7 @@
<ol>
<li>The mechanism must work cleanly for participants with multiple clients.</li>
<li>Stanard presence messages must be used to share presence.</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 MIX-ANON is not used, participants must be able to directly contact other participants.</li>
@ -168,16 +169,15 @@ A user MAY share presence information with the channel, for one or more online c
<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>
A channel MAY require that all channel participants share presence information with the channel, which is represented in the "urn:xmpp:mix:nodes:presence" node. If sharing presences is mandated by the channel, a server complying to this specification and to MIX PAM MUST set the presence subscription to "on way" and MUST NOT set it to "none".
</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'>
<![CDATA[<presence xmlns='jabber:client'
from='hag66@shakespeare.example/UUID-a1j/7533'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
@ -191,7 +191,7 @@ A user MAY share presence information with the channel, for one or more online c
<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, with the 'publisher' attribute set to the user's participant identifier (the proxy JID). 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 is sent from the full proxy JID of the client updating status.
<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 is sent from the full proxy JID of the client updating status.
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'
@ -201,7 +201,11 @@ A user MAY share presence information with the channel, for one or more online c
<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. The history of this node will be held as PubSub format in the MAM archive, so that presence history can be viewed.
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>
</section3>
@ -211,121 +215,20 @@ A user MAY share presence information with the channel, for one or more online c
<section3 topic="Client Coming Online and Obtaining Presence from the Local Server" anchor="usecase-obtaining-presence">
<p>
The presence information for a channel is stored in the urn:xmpp:mix:nodes:presence node and distributed using standard presence stanzas to the server of each user subscribing to this presence node. The user's local server will then pass this presence information on to all online clients. This ensures that an online client is kept updated with presence.
When a client goes offline, it will cease getting presence updates. Presence updates will continue to flow to the user's local server, and so the local server is able maintain up to date presence state for the channel. The user's server MAY cache this presence information to optimize performance or MAY discard it.
</p>
<p>
When the client comes online, it will activate use of the MIX. The user's server will then send full presence status to the client using standard presence messages. This will enable the client to update presence information for the channel. Note that this does not need any interaction with the channel.
MIX Clients obtain presence from their local server. This is specified in MIX-PAM.
</p>
</section3>
<section3 topic="Updating Presence on User&apos;s Server" anchor="usecase-server-presence-update">
<p>
In normal operation a MIX participant's server will hold accurate presence status for the channel which it provides to clients when they are activated. Incoming presence updates are immediately sent to active MIX clients.
</p>
<p>
There are two situations where a MIX participant's server will need to get presence status from the channel. The first time is when a user joins the channel as a participant and subscribes to presence. Upon this subscription the MIX channel will send to the participant's server (using the user's bare JID) presence for all of the items in the presence node using standard presence stanzas. This will give the participant's full current presence for the channel.
</p>
<p>
The second scenario is when the MIX participant's server needs to load or refresh presence status for a channel. This will be needed when the participant's server is started. This MIX participant's server requests presence update by sending a directed presence stanza to the MIX channel from the user's bare JID. The MIX channel can distinguish this from a presence update, which will always be sent from the clients full JID. This special presence stanza will send to the participant's server (using the user's bare JID) presence for all of the items in the presence node using standard presence stanzas.
</p>
</section3>
<section3 topic="Determining Real JIDs" anchor="usecase-real-jids">
<p>
Presence information will provide a MIX client with the nicks and proxy JIDs for participants in a channel. Messages sent to a channel and retrieved from MAM archives will show the proxy JID and nick of the sender. It is sometimes useful to determine the real JID associated with proxy JID. This can always be done for JID Visible channels and can sometimes be done for JID Maybe Visible channels.
</p>
<p>
For current users JID visible rooms, the real JID is found by a PubSub lookup on the JID Map node. This is shown in the following example:
</p>
<example caption='Client looks up Real JID from Proxy JID'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.example'
type='get'>
<pubsub xlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'/>
</items>
</pubsub>
</iq>
<iq from='coven@mix.shakespeare.example'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<pubsub xlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<jid>hecate@mix.shakespeare.example</jid>
</participant>
</item>
</items>
</pubsub>
<items>
</iq>]]> </example>
<p>For JID Maybe Visible rooms the lookup is performed on the JID Maybe Visible Map node. Note that where a user prefers to not share real JID, the result of this lookup of proxy JID will be the (same) proxy JID. </p>
<p>
When an older message is considered, it is possible that the proxy JID of the sender is not current. Such a JID can be looked up in the MAM Archive of the JID Map Node. This is shown in the following example:
</p>
<example caption='Client looks up Real JID from Proxy JID in MAM Archive'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.example'
type='set'>
<query xlns='urn:xmpp:mam:2'
queryid='f28'
node='urn:xmpp:mix:nodes:jidmap'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:2</value>
</field>
<field var='id'>
<value>123456#coven@mix.shakespeare.example</value>
</field>
</x>
</query>
</iq>
<message id='iasd208' to='hag66@shakespeare.example/UUID-c8y/1573'>
<result xmlns='urn:xmpp:mam:2' queryid='f28' id='28482-20987-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns="jabber:client">
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<jid>hecate@mix.shakespeare.example</jid>
</participant>
</item>
</items>
</event>
</message>
</forwarded>
</result>
</message>
<iq from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
type='result'>
</iq>]]> </example>
</section3>
<section3 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. Handling by the MIX channel is slightly different.</p>
<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'
@ -334,7 +237,7 @@ A user MAY share presence information with the channel, for one or more online c
<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 reference the full proxy 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/678'
<![CDATA[<presence from='12345#coven@mix.shakespeare.example/UUID-a1j/7533'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='unavailable'/>]]></example>
@ -342,42 +245,22 @@ A user MAY share presence information with the channel, for one or more online c
<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>
</section3>
<section3 topic="User Leaving a Channel" anchor="usecase-presence-leave">
<p>
It is desirable to prevent clients from going offline briefly and then coming back online again, as this will lead to "flapping presence". The RECOMMENDED approach to achieve this is use of &xep0198; to maintain an XMPP client connection in the event of short term TCP failure.
The primary actions for a user leaving a channel are specified in MIX-CORE. 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'/>]]></example>
<p> *** LEAVE *** When the user leaves the channel, the MIX service is responsible for unsubscribing the user from all nodes in the channel and for removing the user from the participants and presence list. If the user has online presence when the user leaves the channel, the change of presence status caused by removing the user's entry or entries from the presence node will ensure that subscribers to the presence node are correctly updated on presence status, as specified in MIX-PRESENCE.
Deletion from the participants and presence functions as if the item (channel participant) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the deletion is sent to clients subscribed to the participants PubSub nodes, as shown in the example below.
</p>
<example caption="Reporting when User Leaves a Channel"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example' id='f5pp2toz'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items xmlns='urn:xmpp:mix:core:0' node='urn:xmpp:mix:nodes:participants'>
<item>
<retract id='123456#coven@mix.shakespeare.example'/>
</item>
</items>
</event>
</message>
<message from='coven@mix.shakespeare.example'
to='other-witch@shakespeare.example' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items xmlns='urn:xmpp:mix:core:0' node='urn:xmpp:mix:nodes:presence' >
<item>
<retract id='123456#coven@mix.shakespeare.example/8765'/>
</item>
</items>
</event>
</message>
]]></example>
</section3>