XEP-0282: DMUC2: Distributed MUC

This document is one of several proposals for distributing XMPP chat rooms across multiple chat services. It is expected that the various approaches will be refined and harmonized before a final protocol is developed.

The architecture is that of a single root node, called MASTER and several repeater nodes, each called SLAVE. Every stanza is submitted via the slaves to the master, control is centralized there. The master then sends a copy of the stanza to each of the slaves where it is processed and then distributed to each of the slave's leaf nodes, local users at this point. During redistribution, the slave shall not change the stanza's 'from' attribute, which is only possible if the slave is in the same security domain as the user. The result of that is a decreased number of messages on the server-to-server links between the master's server and each of the slave servers.

Note that this only applies to stanzas that are directed to all occupants, such as the change of availability status and messages whose 'type' attribute is set to 'groupchat'.

While 1-1 stanzas such as in-room private messages or vcard-temp requests may also travel along that path they are currently unaffected by this.

2. Requirements¶

3. Terminology¶

3.1 Dramatis Personae¶

Most of the examples in this document use the scenario of the 1990 war that split the Internet Relay Chat into several incompatible networks. The battlefield is represented here by the "wallops@channel.avalon.irc" chatroom. The characters are as follows:

Table 1: Dramatis Personae¶

Room Nickname	Full JID	Role
Wumpus	argl@killrc.oulubox.irc/laptop	Moderator
Valdis	valdis@killrc.oulubox.irc/desktop	Participant
Phaedrus	phaedrus@killrc.oulubox.irc/phone	Participant
WiZ	squit@eris.dclxvii.irc/jupiter	Moderator
Troy	troy@eris.dclxvii.irc/screwdriver	Moderator
BigCheese	rubenro@vesa.yeggmaex.irc/shaver	Participant
Efchen	msa@vesa.yeggmaex.irc/bicycle	Participant

In our example we are presuming that three slaves from three hosts have registered with the master for traffic redistribution. They are doing so using slave@host jids, but they could be using any temporary jid the implementor finds useful to choose.

4. MASTER/SLAVE Protocol¶

This section describes the protocol between the master and the slaves, the interaction between each slave and its users are described in the next section.

4.1 Slave Requirements¶

The slave

must be able to intercept any stanzas sent to the masters jid,
must be able to verify if a local user has sent directed presence to the masters jid,
must store room roster,
must store local room roster
must store room history (if desired by master)

4.2 Creating a Slave¶

to follow

Might include things like negotiation of keepalive frequency and amount of room might be useful to set some things like keepalive frequency, keeping/storing room history etc.

4.3 Initial Room Roster¶

After the creation of a new slave, the master must send the room roster (which at that time only consists of remote participants) to the slave:

Example 1. Master Sends Room Roster to Slave¶

<presence
    from='wallops@channel.avalon.irc/Wumpus'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Valdis'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Phaedrus'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/WiZ'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin' role='moderator'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Troy'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='participant' role='moderator'/>
  </x>
</presence>

4.4 Initial Room History¶

After the creation of a new slave, the master MAY also send the discussion history to the slave. The slave shall store this and deliver it to entering participants.

from=masterjid to=slavejid?

4.5 ENTER¶

If a new occupant requests to enter the room, the master first sends a presence update to all participants to inform them of the presence of the new user. Then, the master sends the affected slave a stanza requesting it to add the user to the distribution list

Example 2. Master informs Slave of New Occupant¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
    <enter jid='rubenro@vesa.yeggmaex.irc/shaver'/>
    <history maxstanzas='20'/>
  </x>
  ...
</presence>

The slave MUST verify that the user has sent directed presence to the masters JID before. This helps to ensure that the user intended to enter the room. If this is ture, the slave shall add the user to the distribution list and send the room roster, occupants own presence in room and discussion history to the full jid of the added user.

4.6 LEAVE¶

If an occupant sends an unavailable presence to the room, the master sends the affected slave a stanza requesting it to remove the user from the distribution list.

Example 3. Master informs Slave of Occupant's Departure¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'
    type='unavailable'>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
    <leave jid='rubenro@vesa.yeggmaex.irc/shaver'/>
  </x>
  ...
</presence>

The slave removes user and forwards the stanza to user.

The master then sends a presence update to all slaves to announce the occupants departure.

4.7 Presence Update¶

Presence updates are distributed by the master to all slaves.

Example 4. Master sends presence update¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@killrc.oulubox.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@eris.dclxvii.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'>
  ...
</presence>

Note that the master MUST NOT send the full jid of the user to any slaves without members that are moderators.

When rebroadcasting this stanza to its local occupants, the slave MUST remove the participants full JID subject to the rules of XEP-0045. In addition, the slave stores the resulting changes to the room roster, so that it can send the correct state to entering users.

4.8 Slave Forwards Stanza to Master¶

The slave may relay messages from local users to the master. When doing so, it MUST NOT modify the stanzas 'from' attribute but MUST retain the original address of the sender.

Example 5. Slave Relays a Message to the Master¶

<message
    from='rubenro@vesa.yeggmaex.irc/shaver'
    to='wallops@channel.avalon.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>

4.9 Message Broadcast¶

When relaying a message, the master SHOULD add a urn:xmpp:delay element inside dmuc element so that the slave can provide proper timestamps to new users. The master then sends a copy of the stanza to each slave.

Example 6. Message from Master to all Slaves¶

<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@killrc.oulubox.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@eris.dclxvii.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>

After saving the stanza for the purpose of keeping a room history, the slave SHOULD remove the urn:xmpp:tmp:dmuc:0 element and send the stanza to each local user.

4.10 Master-Slave Keepalive¶

To ensure a working connecting, the master SHOULD send an XMPP Ping stanza to each slave if there has been no traffic for a certain amount of time.

Likewise, each slave should ping the master if there has been no traffic for more than the usual amount of time.

4.11 Netsplit¶

4.11.1 Netsplit Detection¶

A 'lost connection' can be detected by either slave or master when a stanza sent to the master or a slave respectively bounced.

4.11.1.1 At the Master

If the master receives a stanza with type=error from the slave JID, it MUST:

mark the slave as 'split', making sure that any further broadcasts are not sent to the affected slave
start sending pings to the slave with a higher frequency to get a timely notification if the slave reappears
resync when the slave reappears as described below

In addition, the master MAY send a presence update for each user on the affected slave, marking them as away.

4.11.1.2 At the Slave

If the slave receives a stanza with type=error from the master's JID, it MUST:

stop submitting messages to the master
react to people sending presence updates or leaving the room and broadcast those changes to local users

In addition, the slave MAY (and be careful when using this):

enable local participants to continue their in-room conversation with other local participants
enable local participants to continue 1-1 messaging in the context of a room (such as private chat or vcard retrieval)
enable local users to enter the room (DANGER!!!)
enable moderators (as designated by the master) to kick participants
mark non-local users as away

4.11.2 Netjoin¶

to follow

5. Use-Cases¶

This section narratively describes the master-slave protocol in context with client interactions.

5.1 Entering a Room¶

The user seeks to enter the wallops chatroom with the room nickname BigCheese:

Example 7. User Seeks to Enter Room¶

<presence
    from='rubenro@vesa.yeggmaex.irc/shaver'
    to='wallops@channel.avalon.irc/BigCheese'>
  <x xmlns='http://jabber.org/protocol/muc'/>
</presence>

The master sends the presence update to each slave to inform the current occupants of BigCheese's arrival:

Example 8. Master Sends Presence Update to all Slaves¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@killrc.oulubox.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@eris.dclxvii.irc'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'>
  ...
</presence>

Each slave then distributes this presence update:

Example 9. Slaves Distribute Presence Update to Users - killrc Slave¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='argl@killrc.oulubox.irc/laptop'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='valdis@killrc.oulubox.irc/desktop'>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='phaedrus@killrc.oulubox.irc/phone'>
  ...
</presence>

Example 10. Slaves Distribute Presence Update to Users - eris Slave¶

<presence
    from='wallops@channel.avalon.irc/WiZ'
    to='squit@eris.dclxvii.irc/jupiter'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>
<presence
    from='wallops@channel.avalon.irc/WiZ'
    to='troy@eris.dclxvii.irc/screwdriver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none'
          jid='rubenro@vesa.yeggmaex.irc/shaver'
          role='participant'/>
  </x>
  ...
</presence>

Example 11. Slaves Distribute Presence Update to Users - vesa Slave¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  ...
</presence>

The master then informs the slave of the entered user about a new occupant:

Example 12. Master Informs Slave of New Occupant¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
    <enter jid='rubenro@vesa.yeggmaex.irc/shaver'/>
  </x>
  ...
</presence>

The slave sends presence from existing occupants to new occupant:

Example 13. Slave Sends Presence from Existing Occupants to New Occupant¶

<presence
    from='wallops@channel.avalon.irc/Wumpus'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Valdis'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Phaedrus'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/WiZ'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='admin' role='moderator'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Troy'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='participant' role='moderator'/>
  </x>
</presence>
<presence
    from='wallops@channel.avalon.irc/Efchen'
    to='rubenro@vesa.yeggmaex.irc/shaver'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='none' role='participant'/>
  </x>
</presence>

and concludes the room roster by sending the new occupant's presence to the new occupant:

Example 14. Slave Sends New Occupant's Presence to New Occupant¶

<presence
    from='wallops@channel.avalon.irc/BigCheese'
    to='rubenro@vesa.yeggmaex.irc/shaver'
  ...
</presence>

After that, the slave will send the discussion history to the new occupant:

Example 15. Slave Sends Discussion History to New Occupant¶

<message from='wallops@channel.avalon.irc/Trillian'
    to='rubenro@vesa.yeggmaex.irc/shaver'
    type='groupchat'>
    <body>Honest! He did!!</body>
    <delay xmlns='urn:xmpp:delay'
      from='wallops@channel.avalon.irc/Trillian'
      stamp='1990-01-23T19:50:01Z'/>
</message>
<message from='wallops@channel.avalon.irc/BlondeBoy'
    to='rubenro@vesa.yeggmaex.irc/shaver'
    type='groupchat'>
    <body>Was that absolutely necessary????????</body>
    <delay xmlns='urn:xmpp:delay'
      from='wallops@channel.avalon.irc/BlondeBoy'
      stamp='1990-01-23T19:50:30Z'/>
</message>
<message from='wallops@channel.avalon.irc/DCLXVI'
    to='rubenro@vesa.yeggmaex.irc/shaver'
    type='groupchat'>
    <body>SUUUUUUURE he did</body>
    <delay xmlns='urn:xmpp:delay'
      from='wallops@channel.avalon.irc/DCLXVI'
      stamp='1990-01-23T19:50:51Z'/>
</message>
<message from='wallops@channel.avalon.irc/Cerebus'
    to='rubenro@vesa.yeggmaex.irc/shaver'
    type='groupchat'>
    <body>He did.  really truly he did.</body>
    <delay xmlns='urn:xmpp:delay'
      from='wallops@channel.avalon.irc/Cerebus'
      stamp='1990-01-23T19:51:20Z'/>
</message>

5.2 Sending a Message to All Occupants¶

Example 16. Occupant Sends a Message to All Occupants¶

<message
    from='rubenro@vesa.yeggmaex.irc/shaver'
    to='wallops@channel.avalon.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>

The master will broadcast this message to all slaves:

Example 17. Master Distributes Message to all Slaves¶

<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@killrc.oulubox.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@eris.dclxvii.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='slave@vesa.yeggmaex.irc'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
  <x xmlns='urn:xmpp:tmp:dmuc:0'>
      <delay xmlns='urn:xmpp:delay'
        from='wallops@channel.avalon.irc/BigCheese'
	stamp='1990-10-13T23:58:37Z'/>
  </x>
</message>

And each slave distributes to local occupants

Example 18. Slave Distributes Message to Occupants - killrc Slave¶

<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='argl@killrc.oulubox.irc/laptop'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='valdis@killrc.oulubox.irc/desktop'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='phaedrus@killrc.oulubox.irc/phone'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>

Example 19. Slave Distributes Message to Occupants - eris Slave¶

<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='squit@eris.dclxvii.irc/jupiter'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='troy@eris.dclxvii.irc/screwdriver'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>

Example 20. Slave Distributes Message to Occupants - vesa Slave¶

<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='rubenro@vesa.yeggmaex.irc/shaver'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>
<message
    from='wallops@channel.avalon.irc/BigCheese'
    to='msa@vesa.yeggmaex.irc/bicycle'
    type='groupchat'>
  <body>Phaedrus, we're all having a truly rotten time.</body>
</message>

6. Security Considerations¶

7. IANA Considerations¶

8. XMPP Registrar Considerations¶

9. XML Schema¶

Appendices

Appendix A: Document Information¶

Appendix B: Author Information¶

Carlo von Loesch

Philipp Hancke

Appendix C: Legal Notices¶

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP¶

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Appendix F: Requirements Conformance¶

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".