147 lines
4.9 KiB
ReStructuredText
147 lines
4.9 KiB
ReStructuredText
Failures
|
|
--------
|
|
|
|
A server may encouter an error when trying to process an event received from a
|
|
remote server. In these cases the server may send a `failure` to the remote.
|
|
|
|
A `failure` references both the event that it was trying to process and the
|
|
event that triggered the processing. For example, a failure may be emitted if
|
|
one of the parents of the received events was not authorized.
|
|
|
|
A failure also includes a `severity` field that indicates what action was taken
|
|
by the server. There are three valid values:
|
|
|
|
* `Fatal`: The server failed to parse the event. The event is dropped by the
|
|
server as well as all descendants.
|
|
* `Error`: The server rejected the event, for example due to authorization.
|
|
That event is dropped, but descendants may be accepted.
|
|
* `Warn`: The server accepted all events, but believes the remote did
|
|
something wrong. For example, references an event the local server believes
|
|
is unauthorized.
|
|
|
|
|
|
Data Flows
|
|
----------
|
|
|
|
Invite
|
|
++++++
|
|
|
|
To invite a remote user to an existing room a server distributes an invitiation
|
|
event signed by the remote invitee's server (allowing other servers in the room
|
|
to be sure that the invitee's server had seen the invite.)
|
|
|
|
To get the remote server's signature on the event it is sent in a special
|
|
request to the remote server, which then responds with the signed invite (if it
|
|
accepted it as valid.) The remote server may respond with an error if the user
|
|
does not exist.
|
|
|
|
Join
|
|
++++
|
|
|
|
If a server is already in the room it can simply emit a join event for the user
|
|
joining.
|
|
|
|
If the server is not currently in the room it needs to join via a remote server
|
|
in the room, therefore to join a room a server must have have both the room id
|
|
and a list of remote servers that may be in the room.
|
|
|
|
To join via a remote server the local server first requests a valid join event
|
|
for the room from the remote server. The local then fills it out, signs it, and
|
|
then sends the final join event to the remote server for distribution. The
|
|
remore responds to this second request with the current state of the room at
|
|
the join request and the auth chain for that state.
|
|
|
|
|
|
Authorization
|
|
-------------
|
|
|
|
The authorization for an event depends solely on the current state at that
|
|
event. If a policy server is configured for the room, then the authorization
|
|
for the event is the signature of the policy server.
|
|
|
|
The state events that affect whether an event is authorized are called
|
|
`protocol events`, and are:
|
|
|
|
* `m.room.create`
|
|
* `m.room.power_levels`
|
|
* `m.room.member`
|
|
* `m.room.join_rules`
|
|
|
|
All events *must* list all the protocol events that grant them their
|
|
authorization. All origin servers *must* serve up on request the full graph of
|
|
protocol events for all events it has sent. The graph of protocol events is the
|
|
connected directed acyclic graph with events as nodes and the list of protocol
|
|
events their edges.
|
|
|
|
|
|
Join
|
|
++++
|
|
|
|
A user may join a room if:
|
|
|
|
* The join rule is "public".
|
|
* The join rule is "invite" and the user has been invited by a user that has
|
|
already joined.
|
|
* The user is in the `may_join` list.
|
|
|
|
|
|
Invite
|
|
++++++
|
|
|
|
A user may invite another user if the join rule is either "public" or "invite"
|
|
and the user has joined the room.
|
|
|
|
|
|
Creation
|
|
++++++++
|
|
|
|
A `m.room.create` must be the first event in the room.
|
|
|
|
|
|
Ban, Kick and Redaction
|
|
+++++++++++++++++++++++
|
|
|
|
To ban or kick another user in the room, or to redact an event, then the user
|
|
must have a power level of at least that specificied in the
|
|
`m.room.power_level` event for kick, ban and redactions.
|
|
|
|
|
|
Other Events
|
|
++++++++++++
|
|
|
|
A user may send an event if all the following hold true:
|
|
|
|
* The user is in the room.
|
|
* If the type of the event is listed in the `m.room.power_levels`, then the
|
|
user must have at least that power level. Otherwise, the user must have a
|
|
power level of at least `events_default` or `state_default`, depending on
|
|
if the event is a message or state event respectively.
|
|
|
|
|
|
Unauthorized Events
|
|
-------------------
|
|
|
|
An unauthorized event should not be accepted into the event graph, i.e. new
|
|
events should not reference any unauthorized events. There are situations where
|
|
this can happen and so it is not considered an error to include an unauthorized
|
|
event in the event graph. It is an error for events to refer unauthorized
|
|
events in their `auth_events` section and will in turn be considered
|
|
unauthorized.
|
|
|
|
A server may choose to store only the redacted form of an unauthorized event if
|
|
it is included in the event graph.
|
|
|
|
A server may emit a warning to a remote server if it references an event it
|
|
considers unauthorized.
|
|
|
|
|
|
State and Authorization Querying
|
|
--------------------------------
|
|
|
|
A local server may become aware that it and a remote server's view of the
|
|
current state are inconsistent. The local server may then send its current
|
|
state to the remote, which responds with its view of the current state. Both
|
|
servers should then recompute the local state. If they are conforming
|
|
implementations then they will reach the same conclusions.
|
|
|