Skip to content

Room requirements

Jump to bottom
Marc Bauer edited this page Dec 19, 2023 · 4 revisions

General

Creating a room

Prose's muc_mod follows the standard procedure of creating a room, where a user requests a configuration form, fills and submits it. The main difference lies in the opinionated, minimal configuration:

<iq from='[email protected]'
    id='create1'
    to='[email protected]/desktop'
    type='result'>
  <query xmlns='http://jabber.org/protocol/muc#owner'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Configuration for "coven" Room</title>
      
      <field
          type='hidden'
          var='FORM_TYPE'>
        <value>http://jabber.org/protocol/muc#roomconfig</value>
      </field>
      
      <field
          label='Type of room to create'
          type='list-single'
          var='{http://prose.org/protocol/muc}roomconfig_roomtype'>
        <option label='Group'>
          <value>group</value>
        </option>
        <option label='Private Channel'>
          <value>private-channel</value>
          </option>
        <option label='Public Channel'>
          <value>public-channel</value>
        </option>
      </field>
      
      <field
          label='Room Name'
          type='text-single'
          var='muc#roomconfig_roomname'/>
      <field
          label='Short Description of Room'
          type='text-single'
          var='muc#roomconfig_roomdesc'/>
          
      <field type='fixed'>
        <value>
          Only required/applies when roomconfig_roomtype is 'group'.
          Must contain at least two entries.
        </value>
      </field>
      <field
          label='Room Owners'
          type='jid-multi'
          var='muc#roomconfig_roomowners'/>
    </x>
  </query>
</iq>

Instead of offering to configure each room attribute separately Prose's configuration form offers a custom field {http://prose.org/protocol/muc}roomconfig_roomtype with the options group, private-channel and public-channel. Once submitted the server creates a room with the attributes outlined below.

If roomconfig_roomtype is group, the field muc#roomconfig_roomowners is mandatory and must contain at least two entries. The specified users and the creator of the room will then be enlisted as owners of the room and will receive mediated invites. The creator may or may not be specified explicitly. The server also ensures that the room's JID has the shape org.prose.group.{$HASH} where $HASH is the SHA-1 checksum of all JIDs of the group's members (including the group's creator) sorted alphabetically. This is to ensure that a groups are unique and can be easily discovered.

If roomconfig_roomtype is not group the value of muc#roomconfig_roomowners is silently ignored.

Adding members to a room

When a user is added to a room, either during creation of a group or later by invitation to a channel, the server automatically injects a bookmark into the user's private PubSub node https://prose.org/protocol/bookmark.

<bookmark
  xmlns="https://prose.org/protocol/bookmark"
  jid="org.prose.group.499a6b0f4185a6e8cad7b2e9d9c6933d976d6228@groups.prose.org"
  name="Marc, Rémi, Valerian"
  type="group"
  sidebar="1"
/>

The server also automatically registers users with a room, when they are added as members, with a nickname that is their url-safe base64-encoded bare JID. I.e. [email protected] becomes dXNlckBwcm9zZS5vcmc. This is to prevent any nickname collisions with users from the same or other workspaces.

Inviting users to a room / MUC affiliation/roles

TBD: It seems that MUC affiliations may only complicate our implementation and that we should instead consider global roles and room-specific settings when evaluating the permissions of a user.

Renaming a room

Same as inviting users to a room. Standard behavior is that a MUC owner can rename a room but it seems that a better fit would be to consider global roles.

Destroying a room

Same problem as above. Standard behavior is that a MUC owner can destroy a room but it seems that a better fit would be to consider global roles.

Converting between room types

Prose's muc_mod follows the protocol for subsequent room configuration, with the same options as listed in room creation with two additions:

<field type='fixed'>
  <value>
    Only applies when adding participants to a group.
    Specify a stanza-id to copy all messages since (and including)
    that message to the new room. Leave blank if you want to start
    with an empty history.
  </value>
</field>
<field
  label='Copy messages since'
  type='text-single'
  var='{http://prose.org/protocol/muc}roomconfig_migratesincemessage'>

<field type='fixed'>
  <value>
    Only applies when converting from public-channel to 
    private-channel or when adding participants to a group.
    Leave blank to keep all members from the public-channel after 
    the conversion or specify the desired list of members.
  </value>
</field>
<field
  label='Room Owners'
  type='jid-multi'
  var='muc#roomconfig_roomowners'/>

Shared room attributes

  • Rooms are members-only so that the Prose client can load and display the list of online and offline members.
  • Rooms are non-anonymous so that members can see the real JID of each other.

Discovering rooms

When making disco#items requests against the MUC service the server returns public channels as well as private channels which the requesting user is a member of. The server includes Prose-specific room information in an x element.

<!-- Client -->
<iq type="get" to="conference.prose.org">
  <query xmlns="http://jabber.org/protocol/disco#items"/>
</iq>

<!-- Server -->
<iq from='conference.prose.org' type='result' to='[email protected]'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='[email protected]' name='General'>
      <x xmlns='http://prose.org/protocol/muc#room'>
        <topic>Room topic</topic>
        <room-type>public-channel</room-type>
        <num_members>0</num_members>
      </x>
    </item>
    <item>...</item>
    <item>...</item>
    <item>...</item>
  </query>
</iq>

Querying for room information

Like disco#items requests sent to the MUC server, room disco#info requests may also contain Prose-specific metadata:

<!-- Client -->
<iq type="get" to="[email protected]">
  <query xmlns="http://jabber.org/protocol/disco#info"/>
</iq>

<!-- Server -->
<iq from='[email protected]' type='result' to='[email protected]'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='conference' type='text' name='General'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='muc_membersonly'/>
    <x xmlns='http://prose.org/protocol/muc#room'>
        <topic>Room topic</topic>
        <room-type>public-channel</room-type>
        <num_members>0</num_members>
      </x>
  </query>
</iq>

Registering with a public channel

Full members or higher should be able to register themselves with the room. The Prose server handles registration slightly differently from what is described in XEP-0045, insofar that it does return the registration form but instead always returns a result that the user is already registered.

<!-- User Requests Registration Requirements -->
<iq from='[email protected]/resource'
    id='jw81b36f'
    to='[email protected]'
    type='get'>
  <query xmlns='jabber:iq:register'/>
</iq>

<!-- Server returns result with user's hashed JID as nickname -->
<iq from='[email protected]'
    id='jw81b36f'
    to='[email protected]/resource'
    type='result'>
  <query xmlns='jabber:iq:register'>
    <registered/>
    <username>dXNlckBwcm9zZS5vcmc</username>
  </query>
</iq>

Globally unique channel names

When creating, converting or renaming channels the Prose server always ensures that the specified channel name is not taken already. Otherwise it will return a conflict error. The names of channels are globally unique, regardless if they are public or private since these can be converted back and forth.

Group

Attributes

  • Immutable
    • A Group can be created with a set of members which cannot be extended. To "extend" the Group, a new Group must be created with the additional members added.
    • If a user tries to send a direct or mediated invitation to another user to join a group, the server responds with a not-allowed error.
    • If a user tries to revoke their membership, the server responds with a not-allowed error.
  • Private
    • Only users on the member list are allowed to join.
  • Hidden
    • Only members should be able to discover groups.
  • Limited number of members
    • The number of members in a group should be limited to 9.
  • JID contains hash of all members

Available conversions

  • A Group can be converted to a Private Channel, with the option to copy messages to the Private Channel (see 'Converting between room types'). The server automatically adds the members of the original Group to the Private Channel. After the conversion is complete, the server destroys the original Group and specifies the Private Channel as the alternate destination.
  • To add members to a group the Prose client starts the process as described in Converting between room types, leaves {http://prose.org/protocol/muc}roomconfig_roomtype set to group and modifies muc#roomconfig_roomowners to reflect the desired set of members. Note that the new set of members must be a strict superset of the former set of members, if this is not the case the server responds with a not-allowed error. If a valid configuration is submitted, the server creates a new Group, copies the specified messages to the new Group and adds the specified members. The old Group is left untouched.

Private Channel

  • Mutable
    • Members can be added/removed/leave at any time.
  • Private
    • Only users on the member list are allowed to join.
  • Hidden
    • Only members should be able to discover private channels.
  • Globally unique name

Available conversions

  • Workspace admins and owners can convert a Private Channel to a Public Channel. When a channel is converted, the server posts a message in the channel to let members know that it’s been converted.

Public Channel

  • Mutable
    • Members can be added/removed/join/leave at any time.
  • Semi-Private
    • All full members or higher are allowed to register with the room.
  • Hidden
    • Only members should be able to discover private channels.
  • Globally unique name

Available conversions

  • Workspace admins and owners can convert a Public Channel to a Private Channel. When a channel is converted, the server posts a message in the channel to let members know that it’s been converted.
Clone this wiki locally