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

Fix ASCII diagrams

Browse source
This commit is contained in:
Will 2021-01-19 16:41:28 -08:00
parent 55aed1d296
commit 6c6bd57ebf
No known key found for this signature in database
GPG key ID: 385872BB265E8BF8
11 changed files with 178 additions and 126 deletions
Download patch file Download diff file Expand all files Collapse all files

15
content/_index.md
View file

@ -159,20 +159,21 @@ contents and then adds it to its copy of the room's event graph. Client
B then receives the message from his homeserver via a long-lived GET
request.
How data flows between clients
==============================
How data flows between clients:
```
{ Matrix client A } { Matrix client B }
^ | ^ |
| events | Client-Server API | events |
| V | V
^ | ^ |
| events | Client-Server API | events |
| V | V
+------------------+ +------------------+
| |---------( HTTPS )--------->| |
| homeserver | | homeserver |
| |<--------( HTTPS )----------| |
+------------------+ Server-Server API +------------------+
History Synchronisation
(Federation)
History Synchronisation
(Federation)
```
### Users

4
content/application-service-api.md
View file

@ -274,10 +274,13 @@ The application service API provides a transaction API for sending a
list of events. Each list of events includes a transaction ID, which
works as follows:
```
Typical
HS ---> AS : Homeserver sends events with transaction ID T.
<--- : Application Service sends back 200 OK.
```
```
AS ACK Lost
HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost.
@ -285,6 +288,7 @@ works as follows:
<--- : Application Service sends back 200 OK. If the AS had processed these
events already, it can NO-OP this request (and it knows if it is the
same events based on the transaction ID).
```
The events sent to the application service should be linearised, as if
they were from the event stream. The homeserver MUST maintain a queue of

64
content/client-server-api/_index.md
View file

@ -582,6 +582,7 @@ in the 'completed' array indicating whether that stage is complete.
At a high level, the requests made for an API call completing an auth
flow with three stages will resemble the following diagram:
```
_______________________
| Stage 0 |
| No auth |
@ -616,6 +617,7 @@ flow with three stages will resemble the following diagram:
| ___________________ |
| |_Request_1_________| | <-- Returns API response
|_______________________|
```
##### Authentication types
@ -1244,6 +1246,7 @@ the start and end of the data sets respectively.
For example, if an endpoint had events E1 -&gt; E15. The client wants
the last 5 events and doesn't know any previous events:
```
S E
|-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-|
| | |
@ -1253,11 +1256,13 @@ the last 5 events and doesn't know any previous events:
GET /somepath?to=START&limit=5&dir=b&from=END
Returns:
E15,E14,E13,E12,E11
```
Another example: a public room list has rooms R1 -&gt; R17. The client
is showing 5 rooms at a time on screen, and is on page 2. They want to
now show page 3 (rooms R11 -&gt; 15):
```
S E
| 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stream token
|-R1-R2-R3-R4-R5-R6-R7-R8-R9-R10-R11-R12-R13-R14-R15-R16-R17| room
@ -1268,6 +1273,7 @@ now show page 3 (rooms R11 -&gt; 15):
|
GET /roomslist?from=9&to=END&limit=5
Returns: R11,R12,R13,R14,R15
```
Note that tokens are treated in an *exclusive*, not inclusive, manner.
The end token from the initial request was '9' which corresponded to
@ -1511,10 +1517,12 @@ messages.
You can visualise the range of events being returned as:
```
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]
^ ^
| |
prev_batch: '1-2-3' next_batch: 'a-b-c'
```
Clients then receive new events by "long-polling" the homeserver via the
`/sync` API, passing the value of the `next_batch` field from the
@ -1526,11 +1534,13 @@ deprecated `/events` API) support long-polling in this way.
The response for such an incremental sync can be visualised as:
```
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]
^ ^
| |
| next_batch: 'x-y-z'
prev_batch: 'a-b-c'
```
Normally, all new events which are visible to the client will appear in
the response to the `/sync` API. However, if a large number of events
@ -1541,12 +1551,14 @@ timeline. The client may therefore end up with "gaps" in its knowledge
of the message timeline. The client can fill these gaps using the
`/rooms/<room_id>/messages`\_ API. This situation looks like this:
```
| gap |
| <-> |
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10]
^ ^
| |
prev_batch: 'd-e-f' next_batch: 'u-v-w'
```
Warning
@ -1785,32 +1797,34 @@ This room can only be joined if you were invited.
The allowable state transitions of membership are:
/ban
+------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | /leave | | | |
| | v v | |
```
/ban
+------------------------------------------------------+
| |
| +----------------+ +----------------+ |
| | /leave | | | |
| | v v | |
/invite +--------+ +-------+ | |
------------>| invite |<----------| leave |----+ | |
+--------+ /invite +-------+ | | |
| | ^ | | |
| | | | | |
/join | +---------------+ | | | |
| | /join if | | | |
| | join_rules | | /ban | /unban |
| | public /leave | | | |
v v or | | | |
+------+ /kick | | | |
------------>| join |-------------------+ | | |
/join +------+ v | |
if | +-----+ | |
join_rules +-------------------------->| ban |-----+ |
public /ban +-----+ |
^ ^ |
| | |
----------------------------------------------+ +----------------------+
/ban
------------>| invite |<----------| leave |----+ | |
+--------+ /invite +-------+ | | |
| | ^ | | |
| | | | | |
/join | +---------------+ | | | |
| | /join if | | | |
| | join_rules | | /ban | /unban |
| | public /leave | | | |
v v or | | | |
+------+ /kick | | | |
------------>| join |-------------------+ | | |
/join +------+ v | |
if | +-----+ | |
join_rules +-------------------------->| ban |-----+ |
public /ban +-----+ |
^ ^ |
| | |
----------------------------------------------+ +----------------------+
/ban
```
{{list\_joined\_rooms\_cs\_http\_api}}

36
content/client-server-api/modules/end_to_end_encryption.md
View file

@ -18,34 +18,40 @@ exchange fingerprints between users to build a web of trust.
##### Overview
1) Bob publishes the public keys and supported algorithms for his
device. This may include long-term identity keys, and/or one-time
keys.
1) Bob publishes the public keys and supported algorithms for his
device. This may include long-term identity keys, and/or one-time
keys.
+----------+ +--------------+
| Bob's HS | | Bob's Device |
+----------+ +--------------+
| |
|<=============|
/keys/upload
```
+----------+ +--------------+
| Bob's HS | | Bob's Device |
+----------+ +--------------+
| |
|<=============|
/keys/upload
```
2) Alice requests Bob's public identity keys and supported algorithms.
2) Alice requests Bob's public identity keys and supported algorithms.
```
+----------------+ +------------+ +----------+
| Alice's Device | | Alice's HS | | Bob's HS |
+----------------+ +------------+ +----------+
| | |
|=================>|==============>|
/keys/query <federation>
```
3) Alice selects an algorithm and claims any one-time keys needed.
3) Alice selects an algorithm and claims any one-time keys needed.
```
+----------------+ +------------+ +----------+
| Alice's Device | | Alice's HS | | Bob's HS |
+----------------+ +------------+ +----------+
| | |
|=================>|==============>|
/keys/claim <federation>
```
##### Key algorithms
@ -452,6 +458,7 @@ request, and Alice's second device initiates the request. Note how
Alice's first device is not involved in the request or verification
process.
```
+---------------+ +---------------+ +-------------+ +-------------+
| AliceDevice1 | | AliceDevice2 | | BobDevice1 | | BobDevice2 |
+---------------+ +---------------+ +-------------+ +-------------+
@ -468,6 +475,7 @@ process.
| | m.key.verification.cancel | |
| |-------------------------------------------------->|
| | | |
```
After the handshake, the verification process begins.
@ -571,6 +579,7 @@ The process between Alice and Bob verifying each other would be:
The wire protocol looks like the following between Alice and Bob's
devices:
```
+-------------+ +-----------+
| AliceDevice | | BobDevice |
+-------------+ +-----------+
@ -593,6 +602,7 @@ devices:
| m.key.verification.mac |
|<--------------------------------|
| |
```
###### Error and exception handling
@ -805,6 +815,7 @@ she can trust Bob's device if:
The following diagram illustrates how keys are signed:
```
+------------------+ .................. +----------------+
| +--------------+ | .................. : | +------------+ |
| | v v v : : v v v | |
@ -825,6 +836,7 @@ The following diagram illustrates how keys are signed:
| | | ... | | ... | | |
| +------+ | | +----+ |
+----------------+ +--------------+
```
In the diagram, boxes represent keys and lines represent signatures with
the arrows pointing from the signing key to the key being signed. Dotted
@ -834,6 +846,7 @@ the user who created them.
The following diagram illustrates Alice's view, hiding the keys and
signatures that she cannot see:
```
+------------------+ +----------------+ +----------------+
| +--------------+ | | | | +------------+ |
| | v v | v v v | |
@ -854,6 +867,7 @@ signatures that she cannot see:
| | | ... | | ... | | |
| +------+ | | +----+ |
+----------------+ +--------------+
```
[Verification methods](#device-verification) can be used to verify a
user's master key by using the master public key, encoded using unpadded

39
content/client-server-api/modules/push.md
View file

@ -5,26 +5,27 @@ weight: 130
### Push Notifications
+--------------------+ +-------------------+
Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor |
| | | |
+-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | |
| Matrix homeserver +-----> Push Gateway +------> Push Provider | |
| | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | |
```
+--------------------+ +-------------------+
Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor |
| | | |
+-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | |
| Matrix homeserver +-----> Push Gateway +------> Push Provider | |
| | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | |
Matrix | | | | | |
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
```
This module adds support for push notifications. Homeservers send
notifications of events to user-configured HTTP endpoints. Users may

2
content/client-server-api/modules/sso_login.md
View file

@ -64,6 +64,7 @@ opening an embedded web view.
These steps are illustrated as follows:
```
Matrix Client Matrix Homeserver Auth Server
| | |
|-------------(0) GET /login----------->| |
@ -82,6 +83,7 @@ These steps are illustrated as follows:
| | |
|---(5) POST /login with login token--->| |
|<-------------access token-------------| |
```
Note

6
content/client-server-api/modules/third_party_invites.md
View file

@ -46,6 +46,7 @@ third party identifier with the provided identity server. If the lookup
yields a result for a Matrix User ID then the normal invite process can
be initiated. This process ends up looking like this:
```
+---------+ +-------------+ +-----------------+
| Client | | Homeserver | | IdentityServer |
+---------+ +-------------+ +-----------------+
@ -67,12 +68,14 @@ be initiated. This process ends up looking like this:
| Complete the /invite request | |
|<------------------------------------| |
| | |
```
However, if the lookup does not yield a bound User ID, the homeserver
must store the invite on the identity server and emit a valid
`m.room.third_party_invite` event to the room. This process ends up
looking like this:
```
+---------+ +-------------+ +-----------------+
| Client | | Homeserver | | IdentityServer |
+---------+ +-------------+ +-----------------+
@ -100,6 +103,7 @@ looking like this:
| Complete the /invite request | |
|<------------------------------------| |
| | |
```
All homeservers MUST verify the signature in the event's
`content.third_party_invite.signed` object.
@ -127,6 +131,7 @@ and an identity server IS, the full sequence for a third party invite
would look like the following. This diagram assumes H1 and H2 are
residents of the room while H3 is attempting to join.
```
+-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+
| UserA | | ThirdPartyUser | | H1 | | H2 | | H3 | | IS |
+-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+
@ -181,6 +186,7 @@ residents of the room while H3 is attempting to join.
| | | | | | |
| | | | |<----------------------- |
| | | | | |
```
Note that when H1 sends the `m.room.member` event to H2 and H3 it does
not have to block on either server's receipt of the event. Likewise, H1

4
content/client-server-api/modules/voip_events.md
View file

@ -21,6 +21,7 @@ send call events to rooms with exactly two participants.
A call is set up with message events exchanged as follows:
```
Caller Callee
[Place Call]
m.call.invite ----------->
@ -30,15 +31,18 @@ A call is set up with message events exchanged as follows:
<--------------- m.call.answer
[Call is active and ongoing]
<--------------- m.call.hangup
```
Or a rejected call:
```
Caller Callee
m.call.invite ------------>
m.call.candidate --------->
[..candidates..] --------->
[Rejects call]
<-------------- m.call.hangup
```
Calls are negotiated according to the WebRTC specification.

94
content/proposals.md
View file

@ -278,52 +278,54 @@ corresponding labels for each stage on the
[matrix-doc](https://github.com/matrix-org/matrix-doc) issue and pull
request trackers.
+ +
Proposals | Spec PRs | Additional States
+-------+ | +------+ | +---------------+
| |
+----------------------+ | +---------+ | +-----------+
| | | | | | | |
| Proposal | | +------= Spec PR | | | Postponed |
| Drafting and Initial | | | | Missing | | | |
| Feedback Gathering | | | | | | +-----------+
| | | | +----+----+ |
+----------+-----------+ | | | | +----------+
| | | v | | |
v | | +-----------------+ | | Closed |
+-------------------+ | | | | | | |
| | | | | Spec PR Created | | +----------+
| Proposal PR | | | | and In Review | |
| In Review | | | | | |
| | | | +--------+--------+ |
+---------+---------+ | | | |
| | | v |
v | | +-----------+ |
+----------------------+ | | | | |
| | | | | Spec PR | |
| Proposed Final | | | | Merged! | |
| Comment Period | | | | | |
| | | | +-----------+ |
+----------+-----------+ | | |
| | | |
v | | |
+----------------------+ | | |
| | | | |
| Final Comment Period | | | |
| | | | |
+----------+-----------+ | | |
| | | |
v | | |
+----------------------+ | | |
| | | | |
| Final Comment Period | | | |
| Complete | | | |
| | | | |
+----------+-----------+ | | |
| | | |
+-----------------+ |
| |
+ +
```
+ +
Proposals | Spec PRs | Additional States
+-------+ | +------+ | +---------------+
| |
+----------------------+ | +---------+ | +-----------+
| | | | | | | |
| Proposal | | +------= Spec PR | | | Postponed |
| Drafting and Initial | | | | Missing | | | |
| Feedback Gathering | | | | | | +-----------+
| | | | +----+----+ |
+----------+-----------+ | | | | +----------+
| | | v | | |
v | | +-----------------+ | | Closed |
+-------------------+ | | | | | | |
| | | | | Spec PR Created | | +----------+
| Proposal PR | | | | and In Review | |
| In Review | | | | | |
| | | | +--------+--------+ |
+---------+---------+ | | | |
| | | v |
v | | +-----------+ |
+----------------------+ | | | | |
| | | | | Spec PR | |
| Proposed Final | | | | Merged! | |
| Comment Period | | | | | |
| | | | +-----------+ |
+----------+-----------+ | | |
| | | |
v | | |
+----------------------+ | | |
| | | | |
| Final Comment Period | | | |
| | | | |
+----------+-----------+ | | |
| | | |
v | | |
+----------------------+ | | |
| | | | |
| Final Comment Period | | | |
| Complete | | | |
| | | | |
+----------+-----------+ | | |
| | | |
+-----------------+ |
| |
+ +
```
# Lifetime States

38
content/push-gateway-api.md
View file

@ -36,26 +36,28 @@ A client's homeserver forwards information about received events to the
push gateway. The gateway then submits a push notification to the push
notification provider (e.g. APNS, GCM).
+--------------------+ +-------------------+
Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor |
| | | |
+-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | |
| Matrix homeserver +-----> Push Gateway +------> Push Provider | |
| | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | |
```
+--------------------+ +-------------------+
Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor |
| | | |
+-------------------+ | +----------------+ | | +---------------+ |
| | | | | | | | | |
| Matrix homeserver +-----> Push Gateway +------> Push Provider | |
| | | | | | | | | |
+-^-----------------+ | +----------------+ | | +----+----------+ |
| | | | | |
Matrix | | | | | |
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
Mobile Device or Client
```
## Homeserver behaviour

2
content/server-server-api.md
View file

@ -690,6 +690,7 @@ candidate may be used at each time. Thus, any join handshake can
potentially involve anywhere from two to four homeservers, though most
in practice will use just two.
```
Client Joining Directory Resident
Server Server Server
@ -705,6 +706,7 @@ in practice will use just two.
<------------------------------- send_join response
|
<---------- join response
```
The first part of the handshake usually involves using the directory
server to request the room ID and join candidates through the