# GC3 - Register/unregister - Affiliation versioning - Offline presence - Occupant IDs - RAI (Room Activity Indicator) --- **Notes from sprint** - Nicknames should be injected by the server - Request a unique room JID - Auto-reserve nickname module should update the reserved nick on nickname changes - Include nickname on each message - In Prosody, switch to nick enforcement by default after next major release. - Presence probes in MUC - Adopt mod_muc_batched_probe - Pagination for affiliations (RSM) - Update affiliation versioning to support a 'max' number of results in the response, and a way to request the full list with pagination (e.g. if the response was too large). - Ordering of response (e.g. last interaction, name, etc.) - `<item/>` in GC3 namespace should have occupant-id attribute. - PMs: send chat request to another occupant containing your real JID (or a burner JID, perhaps?) - Self-registered users become a new affiliation (TBD?), which could map to member+visitor in MUC. - Registration should be easy for clients (e.g. auto-registration based on information in initial presence). - It is permitted for participants to send messages to the group, even if they are not currently subscribed to live messages. --- **Notes from after the sprint:** - We probably want to have the affiliation list separate to the occupant list, actually. To allow for the case where e.g. a domain could be added as a member. - This does raise the complexity, it is probably worth it - the ability to add groups of people to the affiliation list is one that is generally useful. - This split could remove the need for an additional affiliation (because now it will be legal to appear in the occupant list, but not (explicitly) appear in the affiliation list) - Affiliation lists -> access lists? - Some configuration options SHOULD be immutable after group creation - particularly those that belong to the profile of the room (public channel, private group, etc.). Although this doesn't protect from a malicious server, it allows simplified client design if a group's type can be assumed to be stable. - Introduce an error redirect in response to join that indicates an alternative ("real") JID for the room. This allows us to have alias JIDs, which can be created/deleted/renamed as needed without needing to recreate the room itself. --- ## Terminology Throughout this document we try to maintain consistent terminology. This is sometimes tricky, as there are a number of terms that are frequently used interchangeably, some have changed meaning over time and some meanings differ between communities. - **Group**: we used this to refer to a single group chat on the server. Other terms commonly used for this include "MUC", "room", "channel", "conference", "group chat". - **Participant**: we use this to refer to a user that is part of a group (at least able to receive messages from it). This is not to be confused with the "participant" role defined by XEP-0045. ## Background The goal of this specification is to define a new baseline group chat functionality for XMPP. Previous such attempts have been (in chronological order): Groupchat 1.0, MUC (XEP-0045) and MIX (XEP-0369). Of these specifications, MUC is by far the most widely implemented, deployed and used solution for group chats on XMPP today. Therefore, this specification aims to document a new group chat functionality for XMPP that is derived from the existing MUC protocol and has an easy transition path from MUC. To achieve this, we build upon the existing MUC protocol where that makes sense, we define new pieces of protocol where necessary, and we deprecate parts of the old protocol for functionality that is no longer used or required. ## Requirements For the rationale behind these requirements, please see the the 'Design considerations' below. - Support explicit "join" and "leave" actions that are separate from the user/client's connectivity. - Allow a participant to receive notifications if they are not connected (i.e. "push notifications"). - Allow clients to retrieve a list of group participants, regardless of whether those participants are currently online. - Allow fetching the participant list to be optional, to reduce overhead of extremely large groups. - Make presence/connectivity status optional (optionally at the group level, and when a client simply does not need/want that information). - It should be possible for two participants to use the group to bootstrap private communication (if both participants agree to do so). The following functionality from MUC shall be preserved: - The ability to hide the "real" JIDs of participants from other participants (i.e. what MUC calls "semi-anonymous" mode). The following kinds of groups should be possible: - **Public groups** (aka "chat rooms" or "channels"): These are typically topic-based, open to a wide range of people (often network-wide, but some restrictions may be applied, such as limiting to a certain organizational domain). - **Private groups**: These groups typically consist of participants that already know each other, e.g. as family, friends, colleagues or similar relationships. Participants are added/invited by group administrators or existing participants (depending on configuration). - **Announcement groups**: These groups are "read-only" for the majority of participants, and are used to distribute information such as news or alerts to a large number of interested users. Although read-only, selected traffic such as reactions and read markers may be permitted from participants. In addition, the following features should be supported: - Integration with "hats" - Explicit creation of groups ## Design considerations This section explains the rationale used to determine the requirements and protocol defined by this specification. ### Protocol reuse XEP-0045 MUC is already supported in almost every XMPP IM implementation. To allow a smooth transition to a newer protocol, it makes sense to build any replacement upon the existing one as far as it makes sense. This allows both clients and servers to gradually implement new features, and easily support clients/servers that have not yet updated to the new protocol until the transition is complete. ### MUC problems: Occupancy is based on presence A common complaint about MUC is that group occupancy relies on presence from the user's client. This implies that the client cannot be "in" the group when the client is offline. Not being "in" the group can have some negative consequences: - You will not be displayed in the group occupant list - Other group users will not be able to mention/autocomplete you - You will not receive notifications about activity/mentions All these problems can be solved by having explicit actions to "join" and "leave" a group, which are separate from any of your clients going online/offline. Thankfully MUC already has solutions for this, that are simply underused or not used in the way that people want. This specification uses those to support explicit join/leave. ### Participant listings Related to the above issue about occupancy being based on presence, some clients already started moving to using affiliations as a more stable participant list. This works well, and we chose to build the new protocol on top of that. However standard MUC requires three separate queries to retrieve the full list of affiliations, and it doesn't support versioning the responses, so they would need fetching every time the client wanted to check for a change. This was fixed with the introduction of [XEP-0463: MUC Affiliations Versioning](https://xmpp.org/extensions/xep-0463.html), which this new protocol integrates as required functionality. ### Routing to participants As there is not a 1-to-1 mapping between participants and full JIDs (i.e. in the case that a participant has multiple clients), MUC has struggled to adopt appropriate routing rules. `<iq/>` in particular has been tricky. This protocol requires that all stanzas addressed to a participant, if allowed by the group/service policy, are relayed to the participant's real bare JID. This will break certain uses of `<iq/>` between participants, e.g. for file transfers and calls, which (partially) work in MUC, although the behaviour is unspecified. To allow such functionality between GC3 participants, we propose use of a second protocol, such as [XEP-0276](https://xmpp.org/extensions/xep-0276.html) which allows a recipient to explicitly opt in to (at least temporarily) sharing their real presence. ### Stable participant identifiers Traditionally MUC did not have stable participant identifiers - only a user-chosen nickname, which can change and does not exist while the participant is offline. This was fixed with the introduction of [XEP-0421: Anonymous unique occupant identifiers for MUC](https://xmpp.org/extensions/xep-0421.html). We choose to build further upon this, making it a core part of this new protocol. ### Explicit group creation MUC supported implicit creation of groups (join one that doesn't exist, and it will be auto-created). This led to confusing UX, and accidental re-creation of MUCs. For example: 1. Owner creates MUC and invites users 2. Users join the MUC and add it to their auto-join list 3. Owner destroys the MUC 4. Users auto-join and the MUC gets implicitly created by whichever occupant rejoins it first, potentially using unintended default settings. In GC3, creation is performed using a simple `<iq/>`: ```xml <iq type="set" to="groups.example.com" id="create-1"> <create xmlns="urn:xmpp:gc3:0"> <config defaults="urn:xmpp:gc3:0#channel"> <x xmlns="jabber:x:data" type="result"> <field var="muc#roomconfig_roomname"> <value>A Good Place</value> </field> <field var='muc#roomconfig_roomdesc'> <value>The place to be!</value>value> </field> </x> </config> </create> </iq> ``` The `<config/>` element allows the creator to select from a number of default configurations, and/or include a configuration form for fine-grained control. ### Integration with "hats" Hats are a way to define extensible roles and titles within a server. The specification described how to convey them from a MUC server to clients, but little more than that. Ideally a new protocol provides a clear path to supporting custom roles and permissions, and the hats protocol is a sensible foundation for that. ### Invitations The "mediated invitations" mechanism defined in XEP-0045 is deprecated (though a GC3 service may choose to implement it for backwards compatibility). In many cases, an inviter can use [XEP-0249: Direct MUC Invitations](https://xmpp.org/extensions/xep-0249.html) instead. For private groups, you can either grant JIDs membership before you invite them, or you can obtain a join token from the GC3 group that will grant access when presented by the joiner. This can be done using [XEP-0488: MUC Token Invite](https://xmpp.org/extensions/xep-0488.html). The inviter sends the invitation to their contact, with the join token as the password, and an indication that the group supports the GC3 protocol: ```xml <message from='inviter@example.com/client' to='contact@example.com'> <x xmlns='jabber:x:conference' jid='mygroup@groups.example.com' password='qg0aSwGdXVdvKE65R8A6OX' reason='Join our new group!' > <supported xmlns="urn:xmpp:gc3:0"/> </x> </message> ``` For compatibility with MUC clients, a GC3 group SHOULD accept a join token in the 'password' field of a legacy MUC join request. Clients that receive an invitation can join directly using the GC3 protocol if the invitation claims GC3 support. ### Configuration GC3 has a configuration mechanism built on dataforms. GC3 defines a core set of form fields, but the form may be extended with additional fields by implementations and deployments. GC3 configuration is similar to the MUC configuration mechanism defined in XEP-0045. Most of the core GC3 form fields map directly to configuration options defined in XEP-0045. However, some fields defined in XEP-0045 have no standard equivalent in GC3. **Note:** 'Required' in the table below means support is required, not that the configuration option is required to be set on any particular group. | Field | Support | Type | MUC equivalent | Description | |------------|----------|-------------|-----------------------|-------------| | `gc3#lang` | Required | text-single | `muc#roomconfig_lang` | Natural languages used in the group's messages (space and/or comma delimited). | | `gc3#closed` | Required | boolean | `muc'roomconfig_membersonly` | Whether the group only permits access to affiliated participants. | | `gc3#visible` | Required | boolean | `muc#roomconfig_publicroom` | Whether the group should be publicly listed. | | `gc3#reveal_jids` | Required | boolean | `muc#roomconfig_whois` (see note 1) | Whether the real JIDs of participants are visible to other participants. | | `gc3#history_days` | Optional | integer-or-max (see note 2) | None | Number of days of history to record (implementations exposing this MUST support ). A '0' value indicates message history will not be stored. | | `gc3#roominfo_logs` | Optional | text-single | `muc#roominfo_logs` | URL where discussion logs can be viewed | | `.` **Note 1:** The MUC equivalent field, `muc#roomconfig_whois` is of a different type (list-single). XEP-0045 defines this field as having two values, so it can be mapped to a boolean. In this case implementations MUST map the value "moderators" to boolean false, and "anyone" to the boolean value true. **Note 2:** The integer-or-max field type is defined in XEP-0060. A value of 'max' in this case means that history is stored indefinitely (forever, or up to a global limit imposed by the server). #### MUC config fields with no equivalent `muc#roomconfig_persistentroom` : Deprecated. GC3 groups always persist, even when all participants are offline. Servers may clean up rooms that have had no activity for a period of time, but this is a deployment decision. `muc#roomconfig_enablearchiving` / `muc#roomconfig_mam` / `mam` : Deprecated. This was not actually defined in XEP-0045, but many implementations used non-standard fields to control whether MAM archiving is enabled for the group. GC3 groups always have MAM archiving enabled, and only retention is configurable. `muc#maxhistoryfetch` : Deprecated. GC3 does not use the history mechanism defined in XEP-0045. GC3 uses MAM instead. `muc#roomconfig_getmemberlist` : Deprecated. GC3 allows anyone able to see participant JIDs to also fetch the affiliation list. `muc#roomconfig_enablelogging` : Deprecated. Before XEP-0313 (MAM) was developed, this option was used to enable public static logs of chat messages, which would be the only form of long-term history retention. Today, the source of truth for retained chat history can be accessed using XEP-0313 if the requester has permission. If the group is public and history retention is enabled, the history may be publicly accessed. The methods by which the history may be viewed are up to the implementation/deployment. The following fields are deprecated and replaced by ACLs: - `muc#roomconfig_allowpm` - `muc#roomconfig_allowinvites` - `muc#roomconfig_changesubject` ### ACLs --- **Note:** This section is certainly liable to change. See [this draft](https://github.com/swift/protoxeps/blob/master/acl.md) for a potential replacement system. --- Some actions in a GC3 group are protected by an Access Control List system. ```xml <iq type="set" to="mygroup@groups.example.com"> <access xmlns="urn:xmpp:gc3:0"> <action type="private-message" default="allow" /> <action type="change-subject" default="deny"> <allow>member</allow> </action> </access> </iq> ``` Any action that is not updated explicitly by the client in an ACL modification remains at its current value. The following actions are defined: - ... ## Fetching the participant list ... ## Roster flow To facilitate joining a groupchat via a roster item, GC3 groupchats should support the following behaviours: - Join via subscription request - Opt in to presence and messages via caps (similar to PEP's +notify) - Leave via unsubscribe - Relay received presence