|
- ===========
- Rooms Model
- ===========
-
- A description of the general data model used to implement Rooms, and the
- user-level visible effects and implications.
-
-
- Overview
- ========
-
- "Rooms" in Synapse are shared messaging channels over which all the participant
- users can exchange messages. Rooms have an opaque persistent identify, a
- globally-replicated set of state (consisting principly of a membership set of
- users, and other management and miscellaneous metadata), and a message history.
-
-
- Room Identity and Naming
- ========================
-
- Rooms can be arbitrarily created by any user on any home server; at which point
- the home server will sign the message that creates the channel, and the
- fingerprint of this signature becomes the strong persistent identify of the
- room. This now identifies the room to any home server in the network regardless
- of its original origin. This allows the identify of the room to outlive any
- particular server. Subject to appropriate permissions [to be discussed later],
- any current member of a room can invite others to join it, can post messages
- that become part of its history, and can change the persistent state of the room
- (including its current set of permissions).
-
- Home servers can provide a directory service, allowing a lookup from a
- convenient human-readable form of room label to a room ID. This mapping is
- scoped to the particular home server domain and so simply represents that server
- administrator's opinion of what room should take that label; it does not have to
- be globally replicated and does not form part of the stored state of that room.
-
- This room name takes the form
-
- #localname:some.domain.name
-
- for similarity and consistency with user names on directories.
-
- To join a room (and therefore to be allowed to inspect past history, post new
- messages to it, and read its state), a user must become aware of the room's
- fingerprint ID. There are two mechanisms to allow this:
-
- * An invite message from someone else in the room
-
- * A referral from a room directory service
-
- As room IDs are opaque and ephemeral, they can serve as a mechanism to create
- "ad-hoc" rooms deliberately unnamed, for small group-chats or even private
- one-to-one message exchange.
-
-
- Stored State and Permissions
- ============================
-
- Every room has a globally-replicated set of stored state. This state is a set of
- key/value or key/subkey/value pairs. The value of every (sub)key is a
- JSON-representable object. The main key of a piece of stored state establishes
- its meaning; some keys store sub-keys to allow a sub-structure within them [more
- detail below]. Some keys have special meaning to Synapse, as they relate to
- management details of the room itself, storing such details as user membership,
- and permissions of users to alter the state of the room itself. Other keys may
- store information to present to users, which the system does not directly rely
- on. The key space itself is namespaced, allowing 3rd party extensions, subject
- to suitable permission.
-
- Permission management is based on the concept of "power-levels". Every user
- within a room has an integer assigned, being their "power-level" within that
- room. Along with its actual data value, each key (or subkey) also stores the
- minimum power-level a user must have in order to write to that key, the
- power-level of the last user who actually did write to it, and the PDU ID of
- that state change.
-
- To be accepted as valid, a change must NOT:
-
- * Be made by a user having a power-level lower than required to write to the
- state key
-
- * Alter the required power-level for that state key to a value higher than the
- user has
-
- * Increase that user's own power-level
-
- * Grant any other user a power-level higher than the level of the user making
- the change
-
- [[TODO(paul): consider if relaxations should be allowed; e.g. is the current
- outright-winner allowed to raise their own level, to allow for "inflation"?]]
-
-
- Room State Keys
- ===============
-
- [[TODO(paul): if this list gets too big it might become necessary to move it
- into its own doc]]
-
- The following keys have special semantics or meaning to Synapse itself:
-
- m.member (has subkeys)
- Stores a sub-key for every Synapse User ID which is currently a member of
- this room. Its value gives the membership type ("knocked", "invited",
- "joined").
-
- m.power_levels
- Stores a mapping from Synapse User IDs to their power-level in the room. If
- they are not present in this mapping, the default applies.
-
- The reason to store this as a single value rather than a value with subkeys
- is that updates to it are atomic; allowing a number of colliding-edit
- problems to be avoided.
-
- m.default_level
- Gives the default power-level for members of the room that do not have one
- specified in their membership key.
-
- m.invite_level
- If set, gives the minimum power-level required for members to invite others
- to join, or to accept knock requests from non-members requesting access. If
- absent, then invites are not allowed. An invitation involves setting their
- membership type to "invited", in addition to sending the invite message.
-
- m.join_rules
- Encodes the rules on how non-members can join the room. Has the following
- possibilities:
- "public" - a non-member can join the room directly
- "knock" - a non-member cannot join the room, but can post a single "knock"
- message requesting access, which existing members may approve or deny
- "invite" - non-members cannot join the room without an invite from an
- existing member
- "private" - nobody who is not in the 'may_join' list or already a member
- may join by any mechanism
-
- In any of the first three modes, existing members with sufficient permission
- can send invites to non-members if allowed by the "m.invite_level" key. A
- "private" room is not allowed to have the "m.invite_level" set.
-
- A client may use the value of this key to hint at the user interface
- expectations to provide; in particular, a private chat with one other use
- might warrant specific handling in the client.
-
- m.may_join
- A list of User IDs that are always allowed to join the room, regardless of any
- of the prevailing join rules and invite levels. These apply even to private
- rooms. These are stored in a single list with normal update-powerlevel
- permissions applied; users cannot arbitrarily remove themselves from the list.
-
- m.add_state_level
- The power-level required for a user to be able to add new state keys.
-
- m.public_history
- If set and true, anyone can request the history of the room, without needing
- to be a member of the room.
-
- m.archive_servers
- For "public" rooms with public history, gives a list of home servers that
- should be included in message distribution to the room, even if no users on
- that server are present. These ensure that a public room can still persist
- even if no users are currently members of it. This list should be consulted by
- the dirctory servers as the candidate list they respond with.
-
- The following keys are provided by Synapse for user benefit, but their value is
- not otherwise used by Synapse.
-
- m.name
- Stores a short human-readable name for the room, such that clients can display
- to a user to assist in identifying which room is which.
-
- This name specifically is not the strong ID used by the message transport
- system to refer to the room, because it may be changed from time to time.
-
- m.topic
- Stores the current human-readable topic
-
-
- Room Creation Templates
- =======================
-
- A client (or maybe home server?) could offer a few templates for the creation of
- new rooms. For example, for a simple private one-to-one chat the channel could
- assign the creator a power-level of 1, requiring a level of 1 to invite, and
- needing an invite before members can join. An invite is then sent to the other
- party, and if accepted and the other user joins, the creator's power-level can
- now be reduced to 0. This now leaves a room with two participants in it being
- unable to add more.
-
-
- Rooms that Continue History
- ===========================
-
- An option that could be considered for room creation, is that when a new room is
- created the creator could specify a PDU ID into an existing room, as the history
- continuation point. This would be stored as an extra piece of meta-data on the
- initial PDU of the room's creation. (It does not appear in the normal previous
- PDU linkage).
-
- This would allow users in rooms to "fork" a room, if it is considered that the
- conversations in the room no longer fit its original purpose, and wish to
- diverge. Existing permissions on the original room would continue to apply of
- course, for viewing that history. If both rooms are considered "public" we might
- also want to define a message to post into the original room to represent this
- fork point, and give a reference to the new room.
-
-
- User Direct Message Rooms
- =========================
-
- There is no need to build a mechanism for directly sending messages between
- users, because a room can handle this ability. To allow direct user-to-user chat
- messaging we simply need to be able to create rooms with specific set of
- permissions to allow this direct messaging.
-
- Between any given pair of user IDs that wish to exchange private messages, there
- will exist a single shared Room, created lazily by either side. These rooms will
- need a certain amount of special handling in both home servers and display on
- clients, but as much as possible should be treated by the lower layers of code
- the same as other rooms.
-
- Specially, a client would likely offer a special menu choice associated with
- another user (in room member lists, presence list, etc..) as "direct chat". That
- would perform all the necessary steps to create the private chat room. Receiving
- clients should display these in a special way too as the room name is not
- important; instead it should distinguish them on the Display Name of the other
- party.
-
- Home Servers will need a client-API option to request setting up a new user-user
- chat room, which will then need special handling within the server. It will
- create a new room with the following
-
- m.member: the proposing user
- m.join_rules: "private"
- m.may_join: both users
- m.power_levels: empty
- m.default_level: 0
- m.add_state_level: 0
- m.public_history: False
-
- Having created the room, it can send an invite message to the other user in the
- normal way - the room permissions state that no users can be set to the invited
- state, but because they're in the may_join list then they'd be allowed to join
- anyway.
-
- In this arrangement there is now a room with both users may join but neither has
- the power to invite any others. Both users now have the confidence that (at
- least within the messaging system itself) their messages remain private and
- cannot later be provably leaked to a third party. They can freely set the topic
- or name if they choose and add or edit any other state of the room. The update
- powerlevel of each of these fixed properties should be 1, to lock out the users
- from being able to alter them.
-
-
- Anti-Glare
- ==========
-
- There exists the possibility of a race condition if two users who have no chat
- history with each other simultaneously create a room and invite the other to it.
- This is called a "glare" situation. There are two possible ideas for how to
- resolve this:
-
- * Each Home Server should persist the mapping of (user ID pair) to room ID, so
- that duplicate requests can be suppressed. On receipt of a room creation
- request that the HS thinks there already exists a room for, the invitation to
- join can be rejected if:
- a) the HS believes the sending user is already a member of the room (and
- maybe their HS has forgotten this fact), or
- b) the proposed room has a lexicographically-higher ID than the existing
- room (to resolve true race condition conflicts)
-
- * The room ID for a private 1:1 chat has a special form, determined by
- concatenting the User IDs of both members in a deterministic order, such that
- it doesn't matter which side creates it first; the HSes can just ignore
- (or merge?) received PDUs that create the room twice.
|