mirror of https://github.com/moparisthebest/xeps
Remove stuff that should be in MIX-PAM and clarify
This commit is contained in:
Steve Kille
parent
0591736423
commit
5967d067d5
116
xep-0369.xml
116
xep-0369.xml
|
|
@ -37,7 +37,7 @@
|
|||
&skille;
|
||||
<revision>
|
||||
<version>1.0.0</version>
|
||||
<date>2018-05-99</date>
|
||||
<date>2018-05-15</date>
|
||||
<initials>sek</initials>
|
||||
<remark><p>
|
||||
Remove PSA as author (as he requested);
|
||||
|
|
@ -885,36 +885,22 @@
|
|||
|
||||
<section1 topic='Use Cases' anchor='usecases'>
|
||||
<section2 topic='Common User Use Cases' anchor='usecases-user'>
|
||||
<section3 topic="Model for Join and Leave" anchor="usecase-jl-model">
|
||||
<p>
|
||||
MIX Join and Leave communication goes through the clients server. The full specification of client interaction with the client's server is specified in MIX-PAM. This specification shows the protocol between the user's server and the MIX server and sets out behaviour of the MIX server.
|
||||
</p>
|
||||
</section3>
|
||||
<section3 topic='Joining a Channel' anchor='usecase-user-join'>
|
||||
<p>A user joins a channel by sending a MIX "join" command from one of the user's clients. There is no default set of nodes, so the user MUST specify the set of nodes to be subscribed to. To achieve the equivalent service to MUC, a user would subscribe to both messages and presence nodes. A user will typically subscribe to at least the message and/or presence nodes but MAY join and not subscribe to any nodes. Note that the presence node is specified in MIX-PRESECNCE. The <join/> is a child element of <iq/> element. The <join/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The channel is specified by a 'channel' attribute in the <join/> element. The requested nodes are encoded as <subscribe/> child elements of the <join/> element.
|
||||
<p>A user joins a channel by sending a MIX "join" command from one of the user's clients, which will be relayed to the server as specified in MIX-PAM. There is no default set of nodes, so the user MUST specify the set of nodes to be subscribed to. To achieve the equivalent service to MUC, a user would subscribe to both messages and presence nodes. A user will typically subscribe to at least the message and/or presence nodes but MAY join and not subscribe to any nodes. Note that the presence node is specified in MIX-PRESENCE. The <join/> is a child element of <iq/> element. The <join/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The requested nodes are encoded as <subscribe/> child elements of the <join/> element.
|
||||
The join leads to the server subscribing the user to each of the requested nodes associated with the channel. The MIX service will also add the user to the participant list by injecting a new item into the "urn:xmpp:mix:nodes:participants" node automatically.
|
||||
|
||||
</p>
|
||||
<p>The default MIX model is that only channel participants are allowed to subscribe to nodes. A MIX channel MAY allow non-participant subscription. This will be handled by clients directly subscribing to the desired PubSub nodes.</p>
|
||||
<p>The default MIX model is that only channel participants are allowed to subscribe to nodes. A MIX channel MAY allow non-participant subscription to some nodes. This will be handled by clients directly subscribing to the desired PubSub nodes.</p>
|
||||
|
||||
<p>
|
||||
The user's server needs to make roster changes as part of the join functionality. Because of this, the join and leave operations need to operate indirectly. This is fully specified in MIX-PAM.
|
||||
For this reason the initial join request is sent to the local server with the MIX channel specified as an attribute to the join. The join is sent from a client identified by a full JID to the user's bare JID.
|
||||
The user's server needs to make roster changes as part of the join functionality, as specified in MIX-PAM. This means that the join request to the MIX service will come from the user's server from the user's bare JID.
|
||||
</p>
|
||||
|
||||
<example caption="Client sends request to Local Server to Join a Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
to='hag66@shakespeare.example'
|
||||
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||
<join xmlns='urn:xmpp:mix:core:0'
|
||||
channel='coven@mix.shakespeare.example'>
|
||||
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>
|
||||
The user’s server will then pass the request to the MIX channel, with the request coming from the user's bare JID.
|
||||
</p>
|
||||
<example caption="User's Server sends Join request to MIX Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example'
|
||||
|
|
@ -928,7 +914,8 @@
|
|||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The channel responds to the user's sever with an IQ-result addressed to the user's bare JID. This stanza includes the nodes to which the user has been successfully subscribed, as well as the bare JID that will be used for the user in this channel and added to the participant list. The JID returned in the join is the user's bare proxy JID. The following example shows the result of the above request when the request is completed in full. </p>
|
||||
|
||||
<p>The channel responds to the user's sever with an IQ-result addressed to the user's bare JID, which will be processed as specified in MIX-PAM. This stanza includes the nodes to which the user has been successfully subscribed, as well as the bare JID that will be used for the user in this channel and added to the participant list. The JID returned in the join is the user's bare proxy JID. The following example shows the result of the above request when the request is completed in full. </p>
|
||||
<example caption="Channel responds to User's Server"><![CDATA[
|
||||
<iq type='result'
|
||||
from='coven@mix.shakespeare.example'
|
||||
|
|
@ -943,34 +930,12 @@
|
|||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>
|
||||
The user's server will then make roster modifications as set out in the next section.
|
||||
After making these changes, the user's server will send the join response back to the client that made the join request, identified by the full JID. This is illustrated below:
|
||||
</p>
|
||||
|
||||
<example caption="User's Server sends response to Client"><![CDATA[
|
||||
<iq type='result'
|
||||
from='hag66@shakespeare.example'
|
||||
to='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||
<join xmlns='urn:xmpp:mix:core:0' jid='123456#coven@mix.shakespeare.example'>
|
||||
<subscribe node='urn:xmpp:mix:nodes:messages'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:presence'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:participants'/>
|
||||
<subscribe node='urn:xmpp:mix:nodes:info'/>
|
||||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>
|
||||
This response informs the client that initiated the join request that the request has been completed. Note that the roster changes described in MIX-PAM will lead to roster update information being sent to all of the user's online clients, so that all of the user's clients will be updated with the new MIX channel information.
|
||||
</p>
|
||||
<p>
|
||||
If a user cannot be subscribed to one or more of the requested nodes (e.g., because the node does not exist), but can be subscribed to some the response simply lists the nodes successfully subscribed. If at least one node is requested and none of the nodes requested are successfully subscribed to, an error response is sent indicating the reason that the first node requested was not subscribed to. This error response will also include other nodes requested where subscription failed for the same reason. </p>
|
||||
|
||||
<p>
|
||||
The following response example shows a successful response to the initial request example where
|
||||
the participant is not subscribed to all nodes associated with the channel (in this case only messages, participants, and information). This example shows the message from the MIX channel to the user's server, which will be modified and sent to the client.
|
||||
the participant is not subscribed to all nodes associated with the channel (in this case only messages, participants, and information). This example shows the message from the MIX channel to the user's server.
|
||||
</p>
|
||||
<example caption="Channel Processes Join With Some Nodes Not Subscribed To"><![CDATA[
|
||||
<iq type='result'
|
||||
|
|
@ -984,7 +949,9 @@
|
|||
</join>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>The channel also adds the user to the participants node and sends a notification to subscribers of the participants node. The following example shows such a notification.</p>
|
||||
<p>
|
||||
After a successful join and before sending the response, the channel MUST subscribe the user to the negotiated nodes and
|
||||
adds the user to the participants node. When these changes are made, the MIX channel MUST send a PubSub notification of the change to subscribers of the participants node. The following example shows such a notification.</p>
|
||||
<example caption="Channel Distributes New Participant Information"><![CDATA[
|
||||
<message from='coven@mix.shakespeare.example'
|
||||
to='hecate@shakespeare.example'
|
||||
|
|
@ -993,7 +960,6 @@
|
|||
<items node='urn:xmpp:mix:nodes:participants'>
|
||||
<item id='123456#coven@mix.shakespeare.example'>
|
||||
<participant xmlns='urn:xmpp:mix:core:0'>
|
||||
<nick>third witch</nick>
|
||||
<jid>hag66@shakespeare.example</jid>
|
||||
</participant>
|
||||
</item>
|
||||
|
|
@ -1001,10 +967,9 @@
|
|||
</event>
|
||||
</message>
|
||||
]]></example>
|
||||
<p>The user that has been added to the channel is identified by the item id of the item added to the Participants node, which is the proxy JID of the new channel participant. Note that the <participant> element MUST NOT include a nick of the user being added. The nick MAY be set after the join.</p>
|
||||
<p>
|
||||
At the same time the participant MUST be added to the JID Map node, to map from proxy JID to real JID. For a JID Maybe Visible channel, the participant MUST be added to the JID Maybe Visible Map node. The value in this node MUST reflect the user's visibility preference for the channel and MUST be updated to reflect any changes to this preference.
|
||||
</p>
|
||||
<p>The user that has been added to the channel is identified by the item id of the item added to the Participants node, which is the proxy JID of the new channel participant. The <participant> element MUST include a <jid> element with the JID of the participant, unless MIX-ANON is being followed to hide participant JIDs. The <nick> element will not be included at this point, unless it is automatically generated by the channel. In the likely event that a Nick is subsequently added, an update with the <nick> element will be distributed.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request encoded as a <update-subscription/> child element of <iq/> element. The <update-subscription/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The requested notes are encoded as <subscribe/> child elements of the <update-subscription/> element with the node name encoded as a 'node' attribute. This modification goes directly from client to MIX channel, as this change does not impact the roster and so does not need any local action. The following example shows subscription modification.
|
||||
</p>
|
||||
|
|
@ -1034,23 +999,9 @@
|
|||
|
||||
|
||||
<section3 topic='Leaving a Channel' anchor='usecase-user-leaving'>
|
||||
<p>Users generally remain in a channel for an extended period of time. In particular the user remains as a participant the channel when the user goes offline. Note that this is different to &xep0045;, where the client leaves a room when going offline. So, leaving a MIX channel is a permanent action for a user across all clients. In order to leave a channel, a user sends a MIX "leave" command to the channel. The leave command is encoded as a <leave/> child element of <iq/> element. The <leave/> element is qualified by the 'urn:xmpp:mix:core:0' namespace, with the channel specified as a 'channel" attribute. When a user leaves the channel, the user's server will remove the channel from the user's roster. Leave commands are sent indirectly through the user's server, to enable roster removal. Leaving is initiated by a client request, as shown in the following example.</p>
|
||||
<p>Users generally remain in a channel for an extended period of time. In particular the user remains as a participant the channel when the user goes offline. Note that this is different to &xep0045;, where the client leaves a room when going offline. So, leaving a MIX channel is a permanent action for a user across all clients. In order to leave a channel, the user's server sends a MIX "leave" command to the channel, as specified in MIX-PAM. The leave command is encoded as a <leave/> child element of <iq/> element. The <leave/> element is qualified by the 'urn:xmpp:mix:core:0' namespace. The following example shows a leave request to a MIX channel. </p>
|
||||
|
||||
|
||||
<example caption="Client Requests to Leave a Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
to='hag66@shakespeare.example'
|
||||
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||
<leave xmlns='urn:xmpp:mix:core:0'
|
||||
channel='coven@mix.shakespeare.example'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
|
||||
<p>
|
||||
The user's server will then generate a matching request to the MIX channel.
|
||||
</p>
|
||||
|
||||
<example caption="User's Server sends Leave Request to a Channel"><![CDATA[
|
||||
<iq type='set'
|
||||
from='hag66@shakespeare.example'
|
||||
|
|
@ -1073,22 +1024,10 @@
|
|||
]]></example>
|
||||
|
||||
|
||||
<p>
|
||||
After receiving the confirmation that the user has left the MIX channel, the user's server will remove the MIX channel entry from the user's roster. The user's server will then notify the client that requested to leave.
|
||||
</p>
|
||||
|
||||
<example caption="User's Server Confirms Leave to Client"><![CDATA[
|
||||
<iq type='result'
|
||||
from='hag66@shakespeare.example'
|
||||
to='hag66@shakespeare.example/UUID-a1j/7533'
|
||||
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
|
||||
<leave xmlns='urn:xmpp:mix:core:0'/>
|
||||
</iq>
|
||||
]]></example>
|
||||
<p>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.
|
||||
<p>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 list. Presence removal is 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.
|
||||
Deletion from the participants node functions as if the item (channel participant) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the participant deletion is sent to clients subscribed to the participants PubSub node, as shown in the example below.
|
||||
</p>
|
||||
<example caption="Reporting when User Leaves a Channel"><![CDATA[
|
||||
<message from='coven@mix.shakespeare.example'
|
||||
|
|
@ -1101,17 +1040,6 @@
|
|||
</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>
|
||||
|
||||
|
||||
|
|
@ -1198,7 +1126,7 @@
|
|||
<li>A <proxy-jid> element contains the sender's proxy JID. This MUST be present if <jid> is omitted and MUST not be present if <jid> is present.</li>
|
||||
</ol>
|
||||
<p>The MIX channel then puts a copy of the message into the MAM archive for the channel and sends a copy of the message to each participant in
|
||||
standard groupchat format. These messages sent by the channel are addressed to the bare JID of each participant and this will be handled by the participant's local server. The message 'from' attribute is the JID of the channel. The id of the message is the ID from the MAM archive and NOT the id used by the sender. The message placed in the MAM archive is the reflected message without a 'to' attribute.</p>
|
||||
standard groupchat format. These messages sent by the channel are addressed to the bare JID of each participant and this will be handled by the participant's local server as specified in MIX-PAM. The message 'from' attribute is the JID of the channel. The id of the message is the ID from the MAM archive and NOT the id used by the sender. The message placed in the MAM archive is the reflected message without a 'to' attribute.</p>
|
||||
|
||||
|
||||
<example caption="Channel Puts Message in MAM Archive"><![CDATA[
|
||||
|
|
|
|||
Loading…
Reference in New Issue