synapse/docs/model/rooms

===========
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.