diff --git a/xep-0369-PAM.xml b/xep-0369-PAM.xml index ee71cd4d..24fe6a4e 100644 --- a/xep-0369-PAM.xml +++ b/xep-0369-PAM.xml @@ -86,7 +86,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- This section defines behaviour REQUIRED by MIX for servers supporting MIX participants. This provides the full MIX specification for clients and servers is set out in a single document. This functionality MUST be provided by servers used by clients that participate in MIX channels. In future, this specification MAY be incorporated into + This section defines behaviour REQUIRED by MIX for servers supporting MIX participants. This functionality MUST be provided by servers used by clients that participate in MIX channels. In future, this specification MAY be incorporated into &xep0376; (PAM) which follows a similar model.

@@ -99,7 +99,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- Messages from a MIX channel will usually be handled by the participant's server. The only exception to this is where the MIX channel is responding directly to messages from the client. Messages and presence distributed but a MIX channel will always be sent to the participant's server and addressed to the user's bare JID. The participant's server will simply send on the messages from the channel to each of the user's online clients which advertise MIX capability. If there are no such clients activated, the message is dropped. + Messages from a MIX channel will usually be handled by the participant's server. The only exception to this is where the MIX channel is responding directly to messages from the client. Messages and presence distributed by a MIX channel will always be sent to the participant's server and addressed to the user's bare JID. The participant's server will archive the message in MAM and send on the messages from the channel to each of the user's online clients which advertise MIX capability. If there are no such clients activated, the message is not sent to any clients.

Messages sent to the participant's sever will always be addressed to the user's bare JID. The participant’s server will modify the recipient to the full JID of each client to which the message is forwarded. The following example, repeated from MIX-CORE, shows a message distributed by a MIX channel and directed to the participant’s server with the participant's bare JID. @@ -158,7 +158,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- Servers supporting this specification MUST advertise this to clients. A client wishing to use MIX MUST check for this capability in the local server before using MIX. The capability is represented by the 'urn:xmpp:mix:account:0' feature. + Servers supporting this specification MUST advertise this to clients. A client wishing to use MIX MUST check for this capability in the local server before using MIX. The capability is represented by the 'urn:xmpp:mix:pam:0' feature.

- + ]]> @@ -181,25 +181,29 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- Most interaction between a MIX client and a MIX channel is directly between the client and the channel. The participant's server relays the message but does not modify the messages. In particular configuration management and discovery is direct. Interaction will be direct, unless explicitly stated otherwise. + Most interaction between a MIX client and a MIX channel is directly between the client and the channel. The participant's server relays the message but does not modify the messages. In particular configuration management and discovery is direct. Interaction will be direct, unless explicitly stated otherwise in this specification.

- +

- Channel Join and Leave functions operate indirectly through the participant's server. The reason for this is that where a channel shares user presence, the channel is included in the user's roster which is managed in the local server. The Join and Leave functions lead to roster changes and so they MUST go through the participant's server. This is included in each of the operations that work in this manner. The general mechanism to achieve this is illustrated by example in this section. - The client addresses indirect messages to the user's own bare JID, indicating the channel with the channel attribute. This is illustrated below. - + Channel Join and Leave functions operate indirectly through the participant's server. The reason for this is that where a channel shares user presence, the channel is included in the user's roster which is managed in the local server. The Join and Leave functions lead to roster changes and so they MUST go through the participant's server. To achieve this, this specification wraps the operations so that the server can correctly route messages.

- - - + + + + + + +

A user joins a channel by sending a MIX "client-join" command from one of the user's clients, which wraps the "join" command specified in MIX-CORE. MIX-CORE specifies how the join command works, and so this specification considers only the wrapping and client actions. + The <client-join/> is a child element of <iq/> element. The <client-join/> element is qualified by the 'urn:xmpp:mix:pam:0' namespace. The channel being joined is specified by a 'channel' attribute in the <client-join/> element, which is used by the server to correctly address the join. The <join> is specified in MIX-CORE and is a child element of <client-join/>. +

+ - - + @@ -210,7 +214,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa ]]> -

This is then modified by the local server and sent to the MIX channel. This is shown in the following example, repeated from the earlier specification of channel behaviour.

+

The information in this message is used to derive the message sent to the MIX channel. The 'from' is the bare JID of the user. The 'to' is the channel from the client join 'channel' attribute. The 'id' is taken from the client join message. The <join> is taken from the client join message. This is shown in the following example, repeated from the earlier specification of channel behaviour.

- The MIX service will send the IQ response to indirect messages to the user's server using the user's bare JID. The user's server will then route the response back to the user's client. + The MIX service will process this request and respond as specified by MIX-CORE. An example response taken from MIX-CORE is shown below.

- - - - - -

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. - 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. - -

-

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.

- -

- 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 will then pass the request to the MIX channel, with the request coming from the user's bare JID. -

- - - - - - - - -]]> -

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.

+

- 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: + The user's server will then make roster modifications as set out in a later section of this specification. + After making these changes, the user's server will send the client-join response containing the server's join response back to the client that made the join request. This has the 'from' set to the user's bare JID and the 'to' set to the client's full JID. This is illustrated below:

- - - - - - + + + + + + + + ]]> -

- 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. -

-

- 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.

- -

- 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 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.

- - - - - - third witch - hag66@shakespeare.example - - - - - -]]> -

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.

-

- 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. -

-

- 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. -

- - - - - - - - - - - -]]> - - + + + - -

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.

+ +

Users generally remain in a channel for an extended period of time. The process for leaving a MIX channel is specified in MIX-CORE. When a user desires to leave a channel, it will issue a client-leave request to the local server. + + The <client-leave/> is a child element of <iq/> element. The <client-leave/> element is qualified by the 'urn:xmpp:mix:pam:0' namespace. The channel being left is specified by a 'channel' attribute in the <client-leave/> element, which is used by the server to correctly address the join. The <leave> is specified in MIX-CORE and is a child element of <client-leave/>. + This shown in the following example.

- + + + ]]>

- The user's server will then generate a matching request to the MIX channel. + The user's server will then generate a matching leave request to the MIX channel based on this information. This example is taken from MIX-CORE.

- The MIX channel will then remove the user from the channel, as described below. A response is sent to the user's server. + The MIX channel will then process the leave and respond. The following example is taken from MIX-CORE.

- 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. + 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 and follow other processing as specified below. The user's server will then notify the client with the servers response. + This wraps the response from the server with a client-leave, with the 'from' set to the user's bare JID and the 'to' set to the client's full JID. This is illustrated below:

- + + + ]]> -

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. - - - 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. -

- - - - - - - - - - - - - - - - - - - -]]> + - - + + @@ -481,7 +358,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- If the user does not wish to publish presence information to the channel, the user's server will add the roster entry with mode subscription=none. The roster entry will be present to record that the user has joined the channel, but it will not send presence information to the channel. The user's server MUST do this when the user has chosen Presence preference of 'not share' as described below. If the user changes the value of the preference, the server MUST modify subscription mode to reflect this. + If the user does not wish to publish presence information to the channel, the user's server will add the roster entry with mode subscription=none. The roster entry will be present to record that the user has joined the channel, but it will not send presence information to the channel. The user's server MUST do this when the user has chosen Presence preference of 'not share' as specified in MIX-ANON. If the user changes the value of the preference, the server MUST modify subscription mode to reflect this.

@@ -501,27 +378,21 @@ This approach enables flexible support of multiple clients for a MIX channel pa

- 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. + A user joins a channel over an extended period, and participation in a channel does not generally change when a user clients go online or offline. The user's participation in a channel is reflected by the user's bare JID in the participant node. When a user subscribes to presence as specified in MIX-PRESENCE, all presence messages are sent to this JID. Presence updates are sent out to subscribing participants using standard presence stanzas.

- 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 MIX-PAM. 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. + A user MAY share presence information with the channel, for the user's online clients. + + This is achieved by a roster entry for the channel configured with one way presence, which will cause all presence changes for the user's MIX clients 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.

-

- The MIX channel will update the 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 specified in MIX-CORE. 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. -

+ -

- 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 MUST set the presence subscription to "one way" and MUST NOT set it to "none". -

- -

- 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. -

+

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 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.

@@ -531,7 +402,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa ]]>

- 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. + 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. The presence is then handled as specified in MIX-CORE.

dnd Making a Brew ]]> -

The user's presence information is then published by the service to the presence node. The MIX channel then broadcasts the presence change to all users who are subscribed to the presence node. The presence stanza is sent from a JID comprising the bare proxy JID of the client that is assigned by the MIX channel and the resource provided by the client. - The following example shows a presence message as distributed by the server to a presences subscriber.

- - + + +

+ A MIX channel will send out presence information to participants that subscribe to the presence node, as specified in MIX-PRESENCE. An example is shown below: +

+ + - thirdwitch dnd Making a Brew ]]>

- 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 presence node. The history of this node MAY be held as PubSub format in the MAM archive, so that presence history can be viewed. + The user's server will then pass this on to all online clients, with 'from' unchanged and 'to' set to the client receiving presence. An example is shown below:

+ + + dnd + Making a Brew +]]> + +

+ The user's local server will will receive a flow of all presence updates for the user. It will 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, even when there are no online clients. When a user had no online clients the user's server MAY continue to maintain MIX presence status for the user or MAY discard inbound MIX presence information. +

+ + + + -

- The presence information for a channel is stored in the 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, even when there are no online clients. When a user had no online clients the user's server MAY continue to maintain MIX presence status for the user or MAY discard inbound MIX presence information. -

+

When the client comes online, it will activate use of the MIX. When the user's server has been maintaining MIX presence, it will then send full presence status to the client using standard presence messages. This will enable the client to update presence information for the subscribed MIX channels. Note that this does not need any interaction with MIX servers.

- - - -

-The previous section notes how client update works when the local server is keeping MIX presence up to date. - 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. +

+ + + There are two situations where a MIX participant's server will need to get presence status from the channel, before it can send presence to the client. 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.

- 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 and when the server chooses to not maintain presence for a user when all clients go offline. 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 will cause the MIX channel to send a full presence update for the channel. + 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 or when the server chooses to not maintain presence for a user when all clients go offline. 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 will cause the MIX channel to send a full presence update for the channel.

@@ -585,19 +471,12 @@ The previous section notes how client update works when the local server is keep -

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.

- 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. Going online and offline will simply be presence updates.

+ ]]> -

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:

- - - ]]>

@@ -608,15 +487,7 @@ The previous section notes how client update works when the local server is keep - - - - -

- 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 as specified in MIX-ANON. -

- - +