wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into module-presence

Browse source
This commit is contained in:
Kegan Dougal 2015-09-30 10:56:17 +01:00
commit 52f6496cf0
8 changed files with 76 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

4
scripts/nature.css
View file

@ -244,10 +244,6 @@ div.viewcode-block:target {
border-bottom: 1px solid #ac9;
}
p {
margin: 0;
}
ul li dd {
margin-top: 0;
}

69
specification/0-intro.rst
View file

@ -24,7 +24,6 @@ Introduction
The Matrix specification is still evolving: the APIs are not yet frozen
and this document is in places a work in progress or stale. We have made every
effort to clearly flag areas which are still being finalised.
We're publishing it at this point because it's complete enough to be more than
useful and provide a canonical reference to how Matrix is evolving. Our end
goal is to mirror WHATWG's `Living Standard
@ -34,10 +33,9 @@ Matrix is a set of open APIs for open-federated Instant Messaging (IM), Voice
over IP (VoIP) and Internet of Things (IoT) communication, designed to create
and support a new global real-time communication ecosystem. The intention is to
provide an open decentralised pubsub layer for the internet for securely
persisting and publishing/subscribing JSON objects.
This specification is the ongoing result of standardising the APIs used by the
various components of the Matrix ecosystem to communicate with one another.
persisting and publishing/subscribing JSON objects. This specification is the
ongoing result of standardising the APIs used by the various components of the
Matrix ecosystem to communicate with one another.
The principles that Matrix attempts to follow are:
@ -214,10 +212,8 @@ which have the form::
There is exactly one room ID for each room. Whilst the room ID does contain a
domain, it is simply for globally namespacing room IDs. The room does NOT
reside on the domain specified. Room IDs are not meant to be human readable.
They are case-sensitive.
The following conceptual diagram shows an ``m.room.message`` event being sent to
the room ``!qporfwt:matrix.org``::
They are case-sensitive. The following conceptual diagram shows an
``m.room.message`` event being sent to the room ``!qporfwt:matrix.org``::
{ @alice:matrix.org } { @bob:domain.com }
| ^
@ -258,28 +254,28 @@ the room ``!qporfwt:matrix.org``::
Federation maintains *shared data structures* per-room between multiple home
servers. The data is split into ``message events`` and ``state events``.
``Message events`` describe transient 'once-off' activity in a room such as an
instant messages, VoIP call setups, file transfers, etc. They generally describe
communication activity.
Message events:
These describe transient 'once-off' activity in a room such as an
instant messages, VoIP call setups, file transfers, etc. They generally
describe communication activity.
``State events`` describe updates to a given piece of persistent information
('state') related to a room, such as the room's name, topic, membership,
participating servers, etc. State is modelled as a lookup table of key/value
pairs per room, with each key being a tuple of ``state_key`` and ``event type``.
Each state event updates the value of a given key.
State events:
These describe updates to a given piece of persistent information
('state') related to a room, such as the room's name, topic, membership,
participating servers, etc. State is modelled as a lookup table of key/value
pairs per room, with each key being a tuple of ``state_key`` and ``event type``.
Each state event updates the value of a given key.
The state of the room at a given point is calculated by considering all events
preceding and including a given event in the graph. Where events describe the
same state, a merge conflict algorithm is applied. The state resolution
algorithm is transitive and does not depend on server state, as it must
consistently select the same event irrespective of the server or the order the
events were received in.
Events are signed by the originating server (the signature includes the parent
relations, type, depth and payload hash) and are pushed over federation to the
participating servers in a room, currently using full mesh topology. Servers may
also request backfill of events over federation from the other servers
participating in a room.
events were received in. Events are signed by the originating server (the
signature includes the parent relations, type, depth and payload hash) and are
pushed over federation to the participating servers in a room, currently using
full mesh topology. Servers may also request backfill of events over federation
from the other servers participating in a room.
Room Aliases
@ -324,12 +320,10 @@ Users in Matrix are identified via their matrix user ID (MXID). However,
existing 3rd party ID namespaces can also be used in order to identify Matrix
users. A Matrix "Identity" describes both the user ID and any other existing IDs
from third party namespaces *linked* to their account.
Matrix users can *link* third-party IDs (3PIDs) such as email addresses, social
network accounts and phone numbers to their user ID. Linking 3PIDs creates a
mapping from a 3PID to a user ID. This mapping can then be used by Matrix
users in order to discover the MXIDs of their contacts.
In order to ensure that the mapping from 3PID to user ID is genuine, a globally
federated cluster of trusted "Identity Servers" (IS) are used to verify the 3PID
and persist and replicate the mappings.
@ -367,6 +361,10 @@ dedicated API. The API is symmetrical to managing Profile data.
API Standards
-------------
.. TODO
Need to specify any HMAC or access_token lifetime/ratcheting tricks
We need to specify capability negotiation for extensible transports
The mandatory baseline for communication in Matrix is exchanging JSON objects
over HTTP APIs. HTTPS is mandated as the baseline for server-server
(federation) communication. HTTPS is recommended for client-server
@ -374,20 +372,11 @@ communication, although HTTP may be supported as a fallback to support basic
HTTP clients. More efficient optional transports for client-server
communication will in future be supported as optional extensions - e.g. a
packed binary encoding over stream-cipher encrypted TCP socket for
low-bandwidth/low-roundtrip mobile usage.
.. TODO
We need to specify capability negotiation for extensible transports
For the default HTTP transport, all API calls use a Content-Type of
``application/json``. In addition, all strings MUST be encoded as UTF-8.
Clients are authenticated using opaque ``access_token`` strings (see
`Client Authentication`_ for details), passed as a query string parameter on
all requests.
.. TODO
Need to specify any HMAC or access_token lifetime/ratcheting tricks
low-bandwidth/low-roundtrip mobile usage. For the default HTTP transport, all
API calls use a Content-Type of ``application/json``. In addition, all strings
MUST be encoded as UTF-8. Clients are authenticated using opaque
``access_token`` strings (see `Client Authentication`_ for details), passed as a
query string parameter on all requests.
Any errors which occur at the Matrix API level MUST return a "standard error
response". This is a JSON object which looks like::

34
specification/1-client_server_api.rst
View file

@ -672,13 +672,10 @@ to add keys that are, for example offensive or illegal. Since some events
cannot be simply deleted, e.g. membership events, we instead 'redact' events.
This involves removing all keys from an event that are not required by the
protocol. This stripped down event is thereafter returned anytime a client or
remote server requests it.
Events that have been redacted include a ``redacted_because`` key whose value
is the event that caused it to be redacted, which may include a reason.
Redacting an event cannot be undone, allowing server owners to delete the
offending content from the databases.
remote server requests it. Redacting an event cannot be undone, allowing server
owners to delete the offending content from the databases. Events that have been
redacted include a ``redacted_because`` key whose value is the event that caused
it to be redacted, which may include a reason.
.. TODO
Currently, only room admins can redact events by sending a ``m.room.redaction``
@ -709,12 +706,10 @@ one of the following event types:
.. TODO
Need to update m.room.power_levels to reflect new power levels formatting
The redaction event should be added under the key ``redacted_because``.
When a client receives a redaction event it should change the redacted event
The redaction event should be added under the key ``redacted_because``. When a
client receives a redaction event it should change the redacted event
in the same way a server does.
Rooms
-----
@ -853,18 +848,14 @@ Permissions
Permissions for rooms are done via the concept of power levels - to do any
action in a room a user must have a suitable power level. Power levels are
stored as state events in a given room.
The power levels required for operations and the power levels for users are
defined in ``m.room.power_levels``, where both a default and specific users'
power levels can be set.
stored as state events in a given room. The power levels required for operations
and the power levels for users are defined in ``m.room.power_levels``, where
both a default and specific users' power levels can be set.
By default all users have a power level of 0, other than the room creator whose
power level defaults to 100. Users can grant other users increased power levels
up to their own power level. For example, user A with a power level of 50 could
increase the power level of user B to a maximum of level 50. Power levels for
users are tracked per-room even if the user is not present in the room.
The keys contained in ``m.room.power_levels`` determine the levels required for
certain operations such as kicking, banning and sending state events. See
`m.room.power_levels`_ for more information.
@ -881,10 +872,9 @@ room. There are several states in which a user may be, in relation to a room:
- Banned (the user is not allowed to join the room)
Some rooms require that users be invited to it before they can join; others
allow anyone to join.
Whether a given room is an "invite-only" room is determined by the room config
key ``m.room.join_rules``. It can have one of the following values:
allow anyone to join. Whether a given room is an "invite-only" room is
determined by the room config key ``m.room.join_rules``. It can have one of the
following values:
``public``
This room is free for anyone to join without an invite.

18
specification/3-application_service_api.rst
View file

@ -4,11 +4,9 @@ Application Service API
The Matrix client-server API and server-server APIs provide the means to
implement a consistent self-contained federated messaging fabric. However, they
provide limited means of implementing custom server-side behaviour in Matrix
(e.g. gateways, filters, extensible hooks etc).
The Application Service API defines a standard API to allow such extensible
functionality to be implemented irrespective of the underlying homeserver
implementation.
(e.g. gateways, filters, extensible hooks etc). The Application Service API
defines a standard API to allow such extensible functionality to be implemented
irrespective of the underlying homeserver implementation.
.. TODO-spec
Add in Client-Server services? Overview of bots? Seems weird to be in the spec
@ -18,12 +16,10 @@ Passive Application Services
----------------------------
"Passive" application services can only observe events from a given home server.
They cannot prevent events from being sent, nor can they modify the content of
the event being sent.
In order to observe events from a homeserver, the homeserver needs to be
configured to pass certain types of traffic to the application service. This
is achieved by manually configuring the homeserver with information about the
AS..
the event being sent. In order to observe events from a homeserver, the
homeserver needs to be configured to pass certain types of traffic to the
application service. This is achieved by manually configuring the homeserver
with information about the AS.
.. NOTE::
Previously, application services could register with a homeserver via HTTP

12
specification/4-server_server_api.rst
View file

@ -59,13 +59,11 @@ and an optional TLS port.
.. **
If the port is present then the server is discovered by looking up an AAAA or
A record for the DNS name and connecting to the specified TLS port.
If the port is absent then the server is discovered by looking up a
``_matrix._tcp`` SRV record for the DNS name. If this record does not exist
then the server is discovered by looking up an AAAA or A record on the DNS
name and taking the default fallback port number of 8448.
A record for the DNS name and connecting to the specified TLS port. If the port
is absent then the server is discovered by looking up a ``_matrix._tcp`` SRV
record for the DNS name. If this record does not exist then the server is
discovered by looking up an AAAA or A record on the DNS name and taking the
default fallback port number of 8448.
Home servers may use SRV records to load balance requests between multiple TLS
endpoints or to failover to another endpoint if an endpoint fails.

24
specification/modules/content_repo.rst
View file

@ -56,21 +56,21 @@ Homeservers must never upscale images.
Security considerations
-----------------------
Clients may try to upload very large files. Homeservers should not store files
that are too large and should not serve them to clients.
- Clients may try to upload very large files. Homeservers should not store files
that are too large and should not serve them to clients.
Clients may try to upload very large images. Homeservers should not attempt to
generate thumbnails for images that are too large.
- Clients may try to upload very large images. Homeservers should not attempt to
generate thumbnails for images that are too large.
Remote homeservers may host very large files or images. Homeserver should not
proxy or thumbnail large files or images from remote homeservers.
- Remote homeservers may host very large files or images. Homeserver should not
proxy or thumbnail large files or images from remote homeservers.
Clients may try to upload a large number of files. Homeservers should limit the
number and total size of media that can be uploaded by clients.
- Clients may try to upload a large number of files. Homeservers should limit the
number and total size of media that can be uploaded by clients.
Clients may try to access a large number of remote files through a homeserver.
Homeservers should restrict the number and size of remote files that it caches.
- Clients may try to access a large number of remote files through a homeserver.
Homeservers should restrict the number and size of remote files that it caches.
Clients or remote homeservers may try to upload malicious files targeting
vulnerabilities in either the homeserver thumbnailing or the client decoders.
- Clients or remote homeservers may try to upload malicious files targeting
vulnerabilities in either the homeserver thumbnailing or the client decoders.

17
specification/modules/push_cs_api.rst
View file

@ -99,16 +99,13 @@ be redundant. Actions for the highest priority rule and only that rule apply
(for example, a set_tweak action in a lower priority rule will not apply if a
higher priority rule matches, even if that rule does not specify any tweaks).
Rules also have an identifier, rule_id, which is a string. The rule_id is
unique within the kind of rule and scope: rule_ids need not be unique between
rules of the same kind on different devices.
A home server may also have server default rules of each kind and in each scope.
Server default rules are lower priority than user-defined rules in each scope.
Server default rules (and only server default rules) begin with a dot ('.')
character.
In addition, all rules may be enabled or disabled. Disabled rules never match.
Rules also have an identifier, ``rule_id``, which is a string. The ``rule_id``
is unique within the kind of rule and scope: ``rule_ids`` need not be unique
between rules of the same kind on different devices. A home server may also have
server default rules of each kind and in each scope. Server default rules are
lower priority than user-defined rules in each scope. Server default rules (and
only server default rules) begin with a dot ('.') character. In addition, all
rules may be enabled or disabled. Disabled rules never match.
If no rules match an event, the Home Server should not notify for the message
(that is to say, the default action is "dont-notify"). Events that the user sent

9
specification/modules/voip_events.rst
View file

@ -44,11 +44,10 @@ Glare
This specification aims to address the problem of two users calling each other
at roughly the same time and their invites crossing on the wire. It is a far
better experience for the users if their calls are connected if it is clear
that their intention is to set up a call with one another.
In Matrix, calls are to rooms rather than users (even if those rooms may only
contain one other user) so we consider calls which are to the same room. The
rules for dealing with such a situation are as follows:
that their intention is to set up a call with one another. In Matrix, calls are
to rooms rather than users (even if those rooms may only contain one other user)
so we consider calls which are to the same room. The rules for dealing with such
a situation are as follows:
- If an invite to a room is received whilst the client is preparing to send an
invite to the same room, the client should cancel its outgoing call and