moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge branch 'feature/xep-0369'

This commit is contained in:
Jonas Wielicki 2018-05-10 17:52:22 +02:00
parent 711bab030e f103ed8047
commit f24226b35b
1 changed files with 303 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

507
xep-0369.xml
View File

@ -36,6 +36,24 @@
&ksmithisode;
&skille;
&stpeter;
<revision>
<version>0.10.0</version>
<date>2018-05-10</date>
<initials>sek</initials>
<remark><p>
Clarify Owner/Administrator separation from participants and descriptions of channel roles;
Clarify Owner handling on channel join;
New default for configuration nodes present;
Clarify configuration Last Change Made By;
Clarify Mandatory Presence;
Clarification of MIX annotation of roster updates;
Replace contents of section 6.3 (Ensuring Message Delivery) with reference to future XEP;
Add MIX Channels in Roster Section;
Add Proxy JID Architecture Section;
Add MUC Comparison Introduction Section;
Add requirement to clarify MIX is intended for non-human use;
</p></remark>
</revision>
<revision>
<version>0.9.6</version>
<date>2018-03-18</date>
@ -367,10 +385,44 @@
<li>Enable sharing of messages on a channel without requiring sharing of presence.</li>
<li>Enable sharing of presence without requiring message sending.</li>
<li>(Desirable) Make it easier to reduce duplicate traffic.</li>
<li>MIX should be suitable for use by humans and as a building block for other clients.</li>
</ol>
</section1>
<section1 topic='Concepts' anchor='concepts'>
<section2 topic="Comparsion to MUC" anchor="concepts-muc-comparison">
<p>
This section is written as an introduction to MIX for those with detailed knowledge of &xep0045;, to summarize key differences and some rationale for the differences. For those unfamiliar with MUC, this section should be ignored.
</p>
<p>
In MUC, a client joins a MUC room. After this, the client is sent history information, presences, and messages until the client leaves the room by going offline. Key MIX features as summarized below:
</p>
<ol>
<li>MIX has "channels", which are equivalent to MUC rooms.</li>
<li>MIX separates out various services, in particular messages and presence. A MUC channel is implemented as a set of PubSub nodes, and a user (not client) can subscribe to a set of nodes. This control means that users can subscribe to presence and/or messages, which gives useful flexibility. This addresses requirements 3 and 5. Subscribing to message and presence nodes gives a service broadly equivalent to MUC.</li>
<li>Messages and presence sent by a MIX channel use the same formats as MUC and do not use PubSub encodings.</li>
<li>Channels do not have a "subject". This MUC capability is not supported by core MIX.</li>
<li>Users join MIX channels for an extended period and participation is not impacted by clients going online and offline (requirement 1). This means that a MIX client uses channel subscriptions as negotiated by the MIX user.</li>
<li>MIX messages and presence are always sent and are addressed to the user (bare JID). This addressing is a consequence of users (not clients) being the participants in a MIX channel; It is a key difference between MUC and MIX. This addressing change means that the user's server needs to have MIX-specific behaviour to correctly distribute arriving messages and presence appropriately to MIX clients; there may be zero or more online clients that support MIX. This server behaviour is specified by MIX. </li>
<li>MIX messages are archived using MAM on the user's server. This enables flexible access to channel history, independent of the MIX channel server. </li>
<li>A user's roster contains the MIX channels to which the user is subscribed. A client can use a MIX roster extension to determine which MIX channels the user is subscribed to. When a client comes online, this will lead to directed presence for the client to be sent to each MIX channel. A MIX channel can then share the user's presence with channel participants that have subscribed to the presence. The MIX channel will also return to the client a full list of presence information for the channel. This means that when a client comes online, it will receive presence updates for the participants in all subscribed MIX channels.</li>
<li>In MIX, a Nick belongs to the user and not to each client.</li>
<li>
MUC semi-anonymous rooms are achieved by sharing on the Nick with room members. MIX provides a similar capability to address requirement 7, which is that channels have "JID Hidden" and "JID Visible" options. A mechanism is provided that is common for all channels, so that operation flow is the same for all channels and it is easy to switch between JID Visible and JID Hidden. Each channel participant has an anonymized proxy JID that references the user in the channel. There is a PubSub mechanism to map proxy JID to Nick which allows clients to look up (current) Nick for a proxy JID. There is also a PubSub mechanism to map from proxy JIDs to real JIDs. This mechanism is used by the channel to map JIDs and may be used by clients in JID Visible channels to determine the JID.
</li>
</ol>
</section2>
<section2 topic="Specification Appproach" anchor="concepts-approach">
<p>
MIX will enable a wide range of auxiliary services. The goal of the MIX specification is to set out the core capabilities needed for MIX. It is anticipated that additional XEPs will be written to extend the core MIX, and the core MIX specification notes some areas where this may happen. This approach will avoid the core MIX specification becoming unduly large. Profiles referencing sets of related MIX XEPs may be developed in the future.
@ -405,6 +457,18 @@
<section2 topic="MIX and MAM" anchor="concepts-mam">
<p> Historical data (such as the messages sent to the channel) is stored in an archive supporting Message Archive Management (MAM) so that clients can subsequently access this data with MAM. Each node can be archived separately (e.g., the presence node or the configuration node). MIX messages are archived by both the MIX channel and the user's server, so that clients can generally use their local MAM archiver. MIX clients can retrieve archived information with MAM in order to quickly resync messages with regard to a channel, and can do so without providing presence information.</p>
</section2>
<section2 topic="MIX Channels in Roster" anchor="concepts-roster">
<p>
When a user joins a MIX channel, the channel is included in the user's roster. 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="Behaviour of MIX Participant's Server" anchor="concepts-mix-participant-server">
<p>
A MIX channel does not send messages and presence directly to the MIX client of a channel participant, but addresses them to the participant using the participant's bare JID. The participant's server MUST then handle these messages and pass them on to zero, one or multiple clients. To enable MIX to work, this behaviour is necessary and so the server of every MIX client MUST follow the rules set out in this specification.
@ -450,6 +514,9 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</section2>
<section2 topic="Proxy JIDs and JID Visibility" anchor="proxy-jid">
<section3 topic="Services Provided" anchor="proxy-jid-services">
<p>
MIX channels have three modes controlling JID visibility:
</p>
@ -472,6 +539,27 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<p>
The default value is 'Prefer Hidden'.
</p>
</section3>
<section3 topic="Architecture" anchor="proxy-jid-architecture">
<p>
In order to address requirement 7 (a mechanism of JID harvesting), the JID visibility modes of the previous section are defined. MUC achieves this by using Nicks to identify room occupants. This has problems with Nick changing and with multiple active clients for the same user. MIX identifies channel participants by a proxy JID, which is an anonymized stable JID format identifier for each participant. This mapping is used for all channels, as it means that all channels have the same logic and it is straightforward to switch between JID visible and JID hidden channels.
MIX also standardizes the mechanism for mapping between proxy JID and the participant's real JID, so that this can be used by a MIX client. Note that a MUC implementation will need a similar mapping mechanism, but this mechanism is not standardized. MIX maintains three mappings as PubSub nodes to support the necessary mappings:
</p>
<ol>
<li>Participants. This is a list of proxy JIDs of users who have joined the channel. This list is visible to all channel participants. It MAY contain a Nick for each participant. This enables a MIX client to provide a user friendly display of each participant.</li>
<li>JID Map. This contains a mapping of each participant’s real JID with the associated proxy JID. It is used by the MIX channel. For JID Visible channels, it is also accessible to all channel participants, who may use it to display the real JID of each participant.</li>
<li>JIMD Maybe Visible Map. This is used for JID Maybe Visible channels. It contains a mapping from the participant’s real JID with the associated proxy JID, for participants that have elected to share their JID. This enables channel participants to access those JIDs that are shared in a JID Maybe Visible channel. </li>
</ol>
</section3>
<section3 topic="Detailed Specification" anchor="proxy-jid-specification">
<p>
The primary representation of a participant in a MIX channel is a proxy JID, which is an anonymized JID using the same domain as the channel and with the name of the channel encoded, using the format "&lt;generated identifier&gt;#&lt;channel&gt;@&lt;mix domain&gt;". The generated identifier MUST NOT contain the '#', '/' or '@' characters. The Channel name MAY contain the '#' character. For example in the channel 'coven@mix.shakespeare.example', the user 'hag66@shakespeare.example' might have a proxy JID of '123456#coven@mix.shakespeare.example'. The reason for the proxy JID is to support JID Hidden channels. Proxy JIDs are also used in JID Visible channels, for consistency and to enable switching of JID visibility. The "urn:xmpp:mix:nodes:jidmap" node maps from proxy JID to real JID. Servers and clients MUST determine that a JID is a proxy JID from context and MUST NOT infer that a JID is a proxy JID because it contains the '#' character.
</p>
@ -484,6 +572,8 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<p>
The full JIDs held in the presence nodes are anonymized using a similar mechanism. First the bare JID is mapped to a bare proxy JID, using the mapping held in the "urn:xmpp:mix:nodes:jidmap" node for the bare JID. Then the resource is replaced with a generated value. For example, 'hag66@shakespeare.example/UUID-a1j/7533' in the channel coven might have a proxy JID of '123456#coven@mix.shakespeare.example/789'. There is no client visible mapping of proxy full JIDs maintained as this is not needed. The MIX channel will need to maintain a mapping, to support directly addressing clients, such as for client to client disco#info queries. While an full proxy JID is held in the presence node, the mapping to real JID MUST NOT be changed. When adding a client to the presence node, the server MAY add the same anonymized JID as used before by that client, or it MAY create a different anonymized JID.
</p>
</section3>
</section2>
<section2 topic="Standard Nodes" anchor="concepts-nodes">
<p>MIX defines a number standard nodes are as follows. Note that all nodes are OPTIONAL and that not every channel will necessarily use each node:</p>
@ -527,7 +617,8 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<tr><td>Anyone</td><td>Any user, including users in the banned node.</td></tr>
</table>
<p>
There MUST always be at least one Owner for a Channel. Owners, Administrators, Participants, and Allowed are optional and do not need to be set. Where no owner is explicitly set, it is anticipated that a server administrator will have owner rights. Rights are defined in a strictly hierarchical manner following the order of this table, so that for example Owners will always have rights that Administrators have.
There MUST always be at least one Owner set for a Channel. Administrators are optional and do not need to be set. Administrators and Owners MAY be participants but are not required to be. Owners and Administrators are configured in the information node. Participants and Allowed are specified in separate nodes.
Rights are defined in a strictly hierarchical manner following the order of this table, so that for example Owners will always have rights that Administrators have.
</p>
</section3>
@ -588,11 +679,11 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<section3 topic="Presence Node" anchor="presence-node">
<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. Each item in the presence node is identified by the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza using a &lt;presence/&gt; element qualified by the 'jabber:client' namespace. The full proxy JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control MAY be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
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 the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza using a &lt;presence/&gt; element qualified by the 'jabber:client' namespace. The full proxy JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control MAY be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
</p>
<p>
This node MAY be subscribed to by users and this subscription MUST use 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 NOT using pubsub protocol. Clients MUST NOT directly access the presence node using pubsub. The Presence node is a permanent PubSub node.
This node MAY be subscribed to by users and this subscription MUST use 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.
</p>
<example caption="Value of Presence Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:presence'>
@ -684,7 +775,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<tr><td>'Owner'</td><td>Bare JIDs with Owner rights as defined in ACL node. When a channel is created, the JID creating the channel is configured as an owner, unless this attribute is explicitly configured to another value.</td><td>jid-multi</td><td>-</td><td>-</td></tr>
<tr><td>'Administrator'</td><td>Bare JIDs with Administrator rights.</td><td>jid-multi</td><td>-</td><td>-</td></tr>
<tr><td>'End of Life'</td><td>The date and time at which the channel will be automatically removed by the server. If this is not set, the channel is permanent.</td><td>text-single</td><td>-</td><td>-</td></tr>
<tr><td>'Nodes Present'</td><td>Specifies which nodes are present. Presence of config nodes is implicit. Jidmap node MUST be present if participants node is present. 'avatar' means that both Avatar Data and Avatar Metadata nodes are present.</td><td>list-multi</td><td>'participants'; 'presence'; 'information'; 'allowed'; 'banned'; 'jidmap-visible'; 'avatar'</td><td>-</td></tr>
<tr><td>'Nodes Present'</td><td>Specifies which nodes are present. Presence of config nodes is implicit. Jidmap node MUST be present if participants node is present. 'avatar' means that both Avatar Data and Avatar Metadata nodes are present.</td><td>list-multi</td><td>'participants'; 'presence'; 'information'; 'allowed'; 'banned'; 'jidmap-visible'; 'avatar'</td><td>'participants'; 'presence'; 'information'; 'allowed'; 'banned'; 'jidmap-visible'; 'avatar'</td></tr>
<tr><td>'Messages Node Subscription'</td><td>Controls who can subscribe to messages node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'</td><td>'participants'</td></tr>
<tr><td>'Presence Node Subscription'</td><td>Controls who can subscribe to presence node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'</td><td>'participants'</td></tr>
<tr><td>'Participants Node Subscription'</td><td>Controls who can subscribe to participants node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'; 'nobody'; 'admins'; 'owners'</td><td>'participants'</td></tr>
@ -852,7 +943,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
name='A Dark Cave'
type='mix'/>
<feature var='urn:xmpp:mix:1'/>
<feature var='urn:xmpp:mam:1'/>
<feature var='urn:xmpp:mam:2'/>
</query>
</iq>
]]></example>
@ -904,22 +995,22 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='result'>
<pubsub xlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:info'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.example</value>
</field>
</x>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.example</value>
</field>
</x>
</item>
</items>
</pubsub>
@ -945,18 +1036,18 @@ This approach enables flexible support of multiple clients for a MIX channel pa
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<pubsub xlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:participants'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<nick>thirdwitch</nick>
</participant>
</item>
<item id='87123#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<nick>top witch</nick>
</participant>
</item>
</items>
<items node='urn:xmpp:mix:nodes:participants'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<nick>thirdwitch</nick>
</participant>
</item>
<item id='87123#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:1'>
<nick>top witch</nick>
</participant>
</item>
</items>
</pubsub>
<items>
</iq>
@ -1114,7 +1205,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
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>
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request encoded as a &lt;update-subscription/$gt; child element of &lt;iq/&gt; element. The &lt;update-subscription/$gt; element is qualified by the 'urn:xmpp:mix:1' namespace. The requested notes are encoded as &lt;subscribe/&gt; child elements of the &lt;update-subscription/$gt; 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.
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request encoded as a &lt;update-subscription/&gt; child element of &lt;iq/&gt; element. The &lt;update-subscription/&gt; element is qualified by the 'urn:xmpp:mix:1' namespace. The requested notes are encoded as &lt;subscribe/&gt; child elements of the &lt;update-subscription/&gt; 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>
<example caption="User Modifies Subscription Request"><![CDATA[
<iq type='set'
@ -1138,8 +1229,8 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</section3>
<section3 topic="Roster Management" anchor="usecase-roster-management">
<p>
As part of the channel joining process, the user's server MUST add the MIX channel to the user's roster. This is done to share the user's presence status with the channel and channel participants subscribing to presence, when the user wishes this presence to be shared. These roster entries also enables the user's client to quickly determine which channels the user has joined.
This roster entry will lead to the user's server correctly sending user's presence from all the user's MIX clients to the MIX channel. Where the user wishes to share presence, the roster subscription is configured with one way presence, as presence is sent to the MIX channel but no presence information is sent about the MIX channel to the user.
As part of the channel joining process, the user's server MUST add the MIX channel to the user's roster. This is done to share the user's presence status with the channel and channel participants subscribing to presence, when the user wishes this presence to be shared. These roster entries also enables the user's client to quickly determine which channels the user has joined. The user's server will need to record those roster entries that are associated with MIX channels in order to correctly handle MIX processing.
This roster entry will lead to the user's server correctly sending user's presence from all the user's MIX clients to the MIX channel. Where the user wishes to share presence, the roster subscription is configured with one way presence, as presence is sent to the MIX channel but no presence information about the MIX channel is sent to the user.
</p>
<p>
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.
@ -1210,19 +1301,19 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:presence'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='JID Visibility'>
<value>never</value>
</field>
<field var='Private Messages'>
<value>allow</value>
</field>
<field var='vCard'>
<value>block</value>
</field>
</x>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='JID Visibility'>
<value>never</value>
</field>
<field var='Private Messages'>
<value>allow</value>
</field>
<field var='vCard'>
<value>block</value>
</field>
</x>
</join>
</iq>
]]></example>
@ -1241,23 +1332,23 @@ This approach enables flexible support of multiple clients for a MIX channel pa
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<user-preference xmlns='urn:xmpp:mix:1'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field type='list-single' label='Preference for JID Visibility'
var='JID Visibility'>
<option label='JID Never Shown'><value>Never</value></option>
<option label='Default Behaviour'>
<value>default</value></option>
<option label='Try not to show JID'>
<value>prefer not</value></option>
</field>
<field type='list-single' label='Example Custom Preference'
var='Custom Preference'>
<option label='One Option'><value>a</value></option>
<option label='Another Option'><value>b</value></option>
</field>
</x>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field type='list-single' label='Preference for JID Visibility
var='JID Visibility'>
<option label='JID Never Shown'><value>Never</value></option>
<option label='Default Behaviour'
<value>default</value></option>
<option label='Try not to show JID'>
<value>prefer not</value></option>
</field>
<field type='list-single' label='Example Custom Preference'
var='Custom Preference'>
<option label='One Option'><value>a</value></option>
<option label='Another Option'><value>b</value></option>
</field>
</x>
</user-preference>
</iq>
]]></example>
@ -1371,8 +1462,10 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example' id='f5pp2toz'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:participants'>
<retract id='123456#coven@mix.shakespeare.example'/>
<items xmlns='urn:xmpp:mix:1' node='urn:xmpp:mix:nodes:participants'>
<item>
<retract id='123456#coven@mix.shakespeare.example'/>
</item>
</items>
</event>
</message>
@ -1380,8 +1473,10 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<message from='coven@mix.shakespeare.example'
to='other-witch@shakespeare.example' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:presence'>
<retract id='123456#coven@mix.shakespeare.example/8765'/>
<items xmlns='urn:xmpp:mix:1' node='urn:xmpp:mix:nodes:presence' >
<item>
<retract id='123456#coven@mix.shakespeare.example/8765'/>
</item>
</items>
</event>
</message>
@ -1586,9 +1681,9 @@ This approach enables flexible support of multiple clients for a MIX channel pa
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>
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'/>
</items>
</pubsub>
</iq>
@ -1597,13 +1692,13 @@ This approach enables flexible support of multiple clients for a MIX channel pa
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>
<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>
@ -1619,35 +1714,35 @@ This approach enables flexible support of multiple clients for a MIX channel pa
id='kl2fax27'
to='coven@mix.shakespeare.example'
type='set'>
<query xlns='urn:xmpp:mam:2'
<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>
<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>
<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>
@ -1756,19 +1851,19 @@ This approach enables flexible support of multiple clients for a MIX channel pa
to='hag66@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<mix xmlns='urn:xmpp:mix:1'>
<nick>thirdwitch</nick>
<jid>123456#coven@mix.shakespeare.example</jid>
<submission-id>92vax143g</submission-id>
</mix>
<body>Harpier cries: 'tis time, 'tis time.</body>
<mix xmlns='urn:xmpp:mix:1'>
<nick>thirdwitch</nick>
<jid>123456#coven@mix.shakespeare.example</jid>
<submission-id>92vax143g</submission-id>
</mix>
</message>
]]></example>
</section3>
<section3 topic="Retracting a Message" anchor="usecase-retract">
<p>
A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. A MIX channel MAY limit the time frame in which a message is allowed to be retracted, for example to prevent retraction of very old messages. When a messages is retracted the original message MAY be replaced by a tombstone. Message retraction is done by sending a special message that identifies the original message. This mechanism allows the retraction to be distributed on the same path as the original message so that all participating servers and clients MAY honour the retraction. The protocol to request retraction does this by adding to a message a &lt;retract&gt; element qualified by the 'urn:xmpp:mix:1' namespace. A retract messages MUST NOT have a body. The &lt;retract&gt; element MUST include an &lt;id&gt; attribute that holds the MAM-ID of the original message. The message sender will need to look up the MAM-ID. The MAM-ID is the convenient message identification for message recipients. A message and it's retraction shown in the following example.
A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. A MIX channel MAY limit the time frame in which a message is allowed to be retracted, for example to prevent retraction of very old messages. When a messages is retracted the original message MAY be replaced by a tombstone. Message retraction is done by sending a special message that identifies the original message. This mechanism allows the retraction to be distributed on the same path as the original message so that all participating servers and clients MAY honour the retraction. The protocol to request retraction does this by adding to a message a &lt;retract&gt; element qualified by the 'urn:xmpp:mix:1' namespace. A retract messages MUST NOT have a body. The &lt;retract&gt; element MUST include an 'id' attribute that holds the MAM-ID of the original message. The message sender will need to look up the MAM-ID. The MAM-ID is the convenient message identification for message recipients. A message and it's retraction shown in the following example.
</p>
<example caption="User Retracts a Message"><![CDATA[
@ -1799,7 +1894,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</p>
<example caption="Retracted message tombstone in a MAM result"><![CDATA[
<message id='aeb213' to='juliet@capulet.example/UUID-e3r/9264'>
<result xmlns='urn:xmpp:mam:1' queryid='f27' id='28482-98726-73623'>
<result xmlns='urn:xmpp:mam:2' queryid='f27' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns='jabber:client' from="hag66@shakespeare.example"
@ -1824,7 +1919,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</p>
<ol>
<li>The inviter checks with disco that the invitee supports MIX.</li>
<li>The inviter checks using capability discovery that the invitee supports MIX.</li>
<li>The channel inviter sends to the channel requesting an invite for the invitee.</li>
<li>The channel sends an invitation to the inviter.</li>
<li>The inviter sends the invitation to the invitee.</li>
@ -1850,12 +1945,12 @@ This approach enables flexible support of multiple clients for a MIX channel pa
to='hag66@shakespeare.example/UUID-h5z/0253'
type='result'>
<invite xmlns='urn:xmpp:mix:1'>
<invitation>
<inviter>hag66@shakespeare.example</inviter>
<invitee>cat@shakespeare.example</invitee>
<channel>coven@mix.shakespeare.example</channel>
<token>ABCDEF</token>
</invitation>
<invitation>
<inviter>hag66@shakespeare.example</inviter>
<invitee>cat@shakespeare.example</invitee>
<channel>coven@mix.shakespeare.example</channel>
<token>ABCDEF</token>
</invitation>
<invite/>
</iq>
]]></example>
@ -1908,10 +2003,10 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<invitation-ack xmlns='urn:xmpp:mix:1'>
<value>Declined</value>
<invitation>
<inviter>hag66@shakespeare.example</inviter>
<invitee>cat@shakespeare.example</invitee>
<channel>coven@mix.shakespeare.example</channel>
<token>ABCDEF</token>
<inviter>hag66@shakespeare.example</inviter>
<invitee>cat@shakespeare.example</invitee>
<channel>coven@mix.shakespeare.example</channel>
<token>ABCDEF</token>
</invitation>
</invitation-ack>
</iq>
@ -2009,27 +2104,12 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</section2>
<section2 topic="Ensuring Message Delivery" anchor="use-ensure-delivery">
<p>
It is important that messages are all transferred from the MIX channel to the server associated with the each channel participant. Transfer between servers will typically happen quickly and &xep0198; will deal with short connection failures between servers. Longer connection failures could lead to message loss. This would lead to online users (who remain connected to their servers) missing messages, and to messages being missed out of the user archive. This section describes how MIX addresses this.
It is important that messages are all transferred from the MIX channel to the server associated with the each channel participant. Transfer between servers will typically happen quickly and &xep0198; will deal with short connection failures between servers. Longer connection failures could lead to message loss. This would lead to online users (who remain connected to their servers) missing messages, and to messages being missed out of the user archive.
</p>
<p>
When there is a long term connection failure, the MIX channel will receive an error from the XMPP server indicating that a message failed to transfer to a recipient. When this happens, the MIX channel MUST take responsibility to ensure that the message is retransmitted and delivered. When the MIX channel detects a failure it will make use of an IQ Marker message to determine when the connection to the peer server is working again. Once the channel has received a response to the marker IQ it will retransmit the pending messages. The marker is encoded as a &lt;marker/&gt; child element of an &lt;iq/&gt; element. The &lt;marker/&gt; element is qualified by the 'urn:xmpp:mix:1' namespace.
To avoid missing messages, use is made of "NEW XEP - TO BE WRITTEN".
</p>
<example caption="Channel Sends Marker Message" ><![CDATA[
<iq from='coven@mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example'
type='get'>
<marker xmlns='urn:xmpp:mix:1'/>
</iq>
<iq from='hag66@shakespeare.example'
id='lx09df27'
to='coven@mix.shakespeare.example'
type='result'>
<marker xmlns='urn:xmpp:mix:1'/>
</iq>
]]></example>
</section2>
<section2 topic="Use of MAM" anchor="use-mam">
@ -2108,7 +2188,10 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</iq>
]]></example>
<p>
The client MAY also include parameters in &xep0004; format as part of channel creation. If the client wishes to inspect configuration, channel administration procedures SHOULD be used.
The client MAY also include parameters in &xep0004; format as part of channel creation to set parameters in the configuration node. Note that any non-default values in the information node MUST be made as a separate change after the channel is created. If the client wishes to inspect configuration, channel administration procedures SHOULD be used.
</p>
<p>
When a channel is created with default parameters, the Owner in the configuration is set to the JID that creates the channel. Where parameters are included, the Owner or Owners MUST be specified explicitly. If an owner is specified that is not the JID creating the channel, the owner is recommended to verify that this user accepts the responsibility of being an owner of this channel. Protocol to support this verification may be specified in a future XEP. Note that the 'Last Change Made By' in configuration node MUST be set to the JID that creates the channel.
</p>
<example caption="Creating a Channel with Client Specified Parameters" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
@ -2173,8 +2256,8 @@ This approach enables flexible support of multiple clients for a MIX channel pa
A common use case for an ad hoc channel is where two users are engaged in a 1:1 chat and wish to broaden the discussion. Prior to bringing more users into a channel, using standard invitation process, there is a need to create and populate a channel. The first step is for one of the two users to create an ad hoc channel, as described in the previous section. The other user will then be invited, and can switch to the new channel.
</p>
<p>
It can also be useful to share some or all of the messages from the 1:1 discussion into the new channel. The mechanism to do this is to forward messages to be shared in the MUC using &xep0297;. A body SHOULD NOT be used in the outer message.
Sharing history is optional. If history is shared, it MUST be done by the user creating the channel before the other user is invited. Any other use of forwarded messages MUST be treated as a member of the MUC forwarding a message to the channel and MUST NOT be treated as history sharing.
It can also be useful to share some or all of the messages from the 1:1 discussion into the new channel. The mechanism to do this is to forward messages to be shared to the channel using &xep0297;. A body SHOULD NOT be used in the outer message.
Sharing history is optional. If history is shared, it MUST be done by the user creating the channel before the other user is invited. Any other use of forwarded messages MUST be treated as a channel participant forwarding a message to the channel and MUST NOT be treated as history sharing.
</p>
<example caption="Forwarding a message to create History" ><![CDATA[
<message from='hag66@shakespeare.example/UUID-a1j/7533'
@ -2194,7 +2277,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</message>
]]></example>
<p>
There are a number of security considerations with use of MUC history. There may be sensitive information in the 1:1 MUC history, and the user sharing this history should ensure that none of this is sensitive, prior to sharing in this way. The user creating the MUC has potential to inject history messages which were not part of the history. It is recommended that the second user joining the MUC to validate that the messages match the history and to take appropriate action if they do not.
There are a number of security considerations with sharing 1:1 history in a channel. There may be sensitive information in the 1:1 history, and the user sharing this history should ensure that none of this is sensitive, prior to sharing in this way. The user creating the channel has potential to inject history messages which were not part of the history. It is recommended that the second user joining the channel to validate that the messages match the history and to take appropriate action if they do not.
</p>
</section3>
@ -2245,23 +2328,25 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='result'>
<pubsub xmlns='http://jabber.org/protocol/'>
<items node='urn:xmpp:mix:nodes:info'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<item>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<title>Information Node Modification</title>
<field type='text-multi'
label='Channel Name'
var='Name'>
<value>Witches Coven</value>
</field>
<field type='text-multi'
label='Channel Description'
var='Description'/>
<field type='jid-single'
label='Channel Administrative Contact'
var='Contact'/>
</x>
</field>
<title>Information Node Modification</title>
<field type='text-multi'
label='Channel Name'
var='Name'>
<value>Witches Coven</value>
</field>
<field type='text-multi'
label='Channel Description'
var='Description'/>
<field type='jid-single'
label='Channel Administrative Contact'
var='Contact'/>
</x>
</item>
</items>
</pubsub>
</iq>
@ -2274,21 +2359,25 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:info'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
<items>
<item>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.example</value>
</field>
</x>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.example</value>
</field>
</x>
</item>
</items>
</publish>
</pubsub>
</iq>
@ -2299,14 +2388,16 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:info'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'/>
<items>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:1'/>
</items>
</publish>
</pubsub>
</iq>
]]></example>
</section3>
<section3 topic='Modifying Channel Configuration' anchor='usecase-admin-information'>
<p>Channel owners are allowed to modify the channel configuration. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the configuration node. Other clients MAY be authorized to use this command to see the channel configuration, but only owners MAY update the configuration. The values in the form show current values, which MAY be defaults or MAY have been explicitly set. The following example shows a short form returned to illustrate the syntax. A typical configuration form will be much larger with many fields. Modifying channel configuration is done directly by a client.
<p>Channel owners are allowed to modify the channel configuration. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the configuration node. Other clients MAY be authorized to use this command to see the channel configuration, but only owners MAY update the configuration. The values in the form show current values, which MAY be defaults or MAY have been explicitly set. The following example shows a short form returned to illustrate the syntax. A typical configuration form will be much larger with many fields. Modifying channel configuration is done directly by a client. Note that an Owner MUST be specified. When the configuration node is modified, the server MUST set the 'Last Change Made By' attribute to the JID of the user making the change.
</p>
<example caption="Getting Configuration Form" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
@ -2324,15 +2415,17 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items xmlns='urn:xmpp:mix:1' node='urn:xmpp:mix:nodes:config'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<title>Configuration Node Modification</title>
<field type='jid-multi'
label='Channel Administrator'
var='Administrator'/>
</x>
<item>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<title>Configuration Node Modification</title>
<field type='jid-multi'
label='Channel Administrator'
var='Administrator'/>
</x>
</item>
</items>
</pubsub>
</iq>
@ -2345,24 +2438,28 @@ This approach enables flexible support of multiple clients for a MIX channel pa
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:config'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Owner'>
<value>hecate@shakespeare.example</value>
<value>greymalkin@shakespeare.example</value>
</field>
<field var='Messages Node Subscription'>
<value>allowed</value>
</field>
<field var='JID Visibility'>
<value>jid-mandatory-visible</value>
</field>
<field var='No Private Messages'>
<value>true</value>
</field>
</x>
<items>
<item>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:1</value>
</field>
<field var='Owner'>
<value>hecate@shakespeare.example</value>
<value>greymalkin@shakespeare.example</value>
</field>
<field var='Messages Node Subscription'>
<value>allowed</value>
</field>
<field var='JID Visibility'>
<value>jid-mandatory-visible</value>
</field>
<field var='No Private Messages'>
<value>true</value>
</field>
</x>
<item/>
<items/>
</publish>
</pubsub>
</iq>
@ -2478,7 +2575,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
Messages from a MIX channel will usually go to 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.
</p>
<p>
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 participant's server MUST NOT make any other modifications to each message. The following example, repeated from earlier, shows a message distributed by a MIX channel and directed to the participant’s server with the participant's bare JID.
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 earlier, shows a message distributed by a MIX channel and directed to the participant’s server with the participant's bare JID.
</p>
<example caption="Channel Reflects Message to Participants"><![CDATA[
<message from='coven@mix.shakespeare.example'
@ -2643,7 +2740,9 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</item>
]]></example>
<p>
Once a client has made an IQ request to return additional MIX information, the server MUST return this information on all subsequent roster updates that are sent by the server to the client. The server MUST NOT send additional MIX information when this has not been explicitly requested. It is anticipated that a client will fetch the roster after connection has been established and will set it's preference for this MIX capability information at that time.
</p>
</section2>
<section2 topic="MAM Archive Support" anchor="proxy-mam">
@ -2801,7 +2900,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to the following who have made contributions: Dave Cridland, Tarun Gupta, Philipp Hancke, Waqas Hussain, Timothée Jaussoin, Evgeny Khramtsov, Georg Lukas, Tobias Markmann, Ralph Meijer, Edwin Mons, Emmanuel Gil Peyrot, Florian Schmaus, Lance Stout, Sam Whited, Jonas Wielicki, Matthew Wild and one anonymous reviewer.</p>
<p>Thanks to the following who have made contributions: Dave Cridland, Tarun Gupta, Philipp Hancke, Waqas Hussain, Timothée Jaussoin, Evgeny Khramtsov, Georg Lukas, Tobias Markmann, Ralph Meijer, Edwin Mons, Emmanuel Gil Peyrot, Manuel Rubio, Florian Schmaus, Lance Stout, Sam Whited, Jonas Wielicki, Matthew Wild and one anonymous reviewer.</p>
</section1>
</xep>