archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix ASCII diagrams

Browse Source
pull/977/head
Will 4 years ago
parent 55aed1d296
commit 6c6bd57ebf
No known key found for this signature in database
GPG Key ID: 385872BB265E8BF8
11 changed files with 182 additions and 130 deletions
Show Stats Download Patch File Download Diff File

5
content/_index.md
Unescape Escape View File

@ -159,9 +159,9 @@ 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 B then receives the message from his homeserver via a long-lived GET
request. request.
How data flows between clients How data flows between clients:
==============================
```
{ Matrix client A } { Matrix client B } { Matrix client A } { Matrix client B }
^ | ^ | ^ | ^ |
| events | Client-Server API | events | | events | Client-Server API | events |
@ -173,6 +173,7 @@ request.
+------------------+ Server-Server API +------------------+ +------------------+ Server-Server API +------------------+
History Synchronisation History Synchronisation
(Federation) (Federation)
```
### Users ### Users

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

14
content/client-server-api/_index.md
Unescape Escape 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 At a high level, the requests made for an API call completing an auth
flow with three stages will resemble the following diagram: flow with three stages will resemble the following diagram:
```
_______________________ _______________________
| Stage 0 | | Stage 0 |
| No auth | | No auth |
@ -616,6 +617,7 @@ flow with three stages will resemble the following diagram:
| ___________________ | | ___________________ |
| |_Request_1_________| | <-- Returns API response | |_Request_1_________| | <-- Returns API response
|_______________________| |_______________________|
```
##### Authentication types ##### 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 For example, if an endpoint had events E1 -&gt; E15. The client wants
the last 5 events and doesn't know any previous events: the last 5 events and doesn't know any previous events:
```
S E S E
|-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-| |-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 GET /somepath?to=START&limit=5&dir=b&from=END
Returns: Returns:
E15,E14,E13,E12,E11 E15,E14,E13,E12,E11
```
Another example: a public room list has rooms R1 -&gt; R17. The client 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 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): now show page 3 (rooms R11 -&gt; 15):
```
S E S E
| 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stream token | 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 |-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 GET /roomslist?from=9&to=END&limit=5
Returns: R11,R12,R13,R14,R15 Returns: R11,R12,R13,R14,R15
```
Note that tokens are treated in an *exclusive*, not inclusive, manner. Note that tokens are treated in an *exclusive*, not inclusive, manner.
The end token from the initial request was '9' which corresponded to 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: You can visualise the range of events being returned as:
```
[E0]->[E1]->[E2]->[E3]->[E4]->[E5] [E0]->[E1]->[E2]->[E3]->[E4]->[E5]
^ ^ ^ ^
| | | |
prev_batch: '1-2-3' next_batch: 'a-b-c' prev_batch: '1-2-3' next_batch: 'a-b-c'
```
Clients then receive new events by "long-polling" the homeserver via the Clients then receive new events by "long-polling" the homeserver via the
`/sync` API, passing the value of the `next_batch` field from 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: The response for such an incremental sync can be visualised as:
```
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6] [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]
^ ^ ^ ^
| | | |
| next_batch: 'x-y-z' | next_batch: 'x-y-z'
prev_batch: 'a-b-c' prev_batch: 'a-b-c'
```
Normally, all new events which are visible to the client will appear in 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 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 of the message timeline. The client can fill these gaps using the
`/rooms/<room_id>/messages`\_ API. This situation looks like this: `/rooms/<room_id>/messages`\_ API. This situation looks like this:
```
| gap | | gap |
| <-> | | <-> |
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10] [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10]
^ ^ ^ ^
| | | |
prev_batch: 'd-e-f' next_batch: 'u-v-w' prev_batch: 'd-e-f' next_batch: 'u-v-w'
```
Warning Warning
@ -1785,6 +1797,7 @@ This room can only be joined if you were invited.
The allowable state transitions of membership are: The allowable state transitions of membership are:
```
/ban /ban
+------------------------------------------------------+ +------------------------------------------------------+
| | | |
@ -1811,6 +1824,7 @@ The allowable state transitions of membership are:
| | | | | |
----------------------------------------------+ +----------------------+ ----------------------------------------------+ +----------------------+
/ban /ban
```
{{list\_joined\_rooms\_cs\_http\_api}} {{list\_joined\_rooms\_cs\_http\_api}}

14
content/client-server-api/modules/end_to_end_encryption.md
Unescape Escape View File

@ -22,30 +22,36 @@ exchange fingerprints between users to build a web of trust.
device. This may include long-term identity keys, and/or one-time device. This may include long-term identity keys, and/or one-time
keys. keys.
```
+----------+ +--------------+ +----------+ +--------------+
| Bob's HS | | Bob's Device | | Bob's HS | | Bob's Device |
+----------+ +--------------+ +----------+ +--------------+
| | | |
|<=============| |<=============|
/keys/upload /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 | | Alice's Device | | Alice's HS | | Bob's HS |
+----------------+ +------------+ +----------+ +----------------+ +------------+ +----------+
| | | | | |
|=================>|==============>| |=================>|==============>|
/keys/query <federation> /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 | | Alice's Device | | Alice's HS | | Bob's HS |
+----------------+ +------------+ +----------+ +----------------+ +------------+ +----------+
| | | | | |
|=================>|==============>| |=================>|==============>|
/keys/claim <federation> /keys/claim <federation>
```
##### Key algorithms ##### 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 Alice's first device is not involved in the request or verification
process. process.
```
+---------------+ +---------------+ +-------------+ +-------------+ +---------------+ +---------------+ +-------------+ +-------------+
| AliceDevice1 | | AliceDevice2 | | BobDevice1 | | BobDevice2 | | AliceDevice1 | | AliceDevice2 | | BobDevice1 | | BobDevice2 |
+---------------+ +---------------+ +-------------+ +-------------+ +---------------+ +---------------+ +-------------+ +-------------+
@ -468,6 +475,7 @@ process.
| | m.key.verification.cancel | | | | m.key.verification.cancel | |
| |-------------------------------------------------->| | |-------------------------------------------------->|
| | | | | | | |
```
After the handshake, the verification process begins. 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 The wire protocol looks like the following between Alice and Bob's
devices: devices:
```
+-------------+ +-----------+ +-------------+ +-----------+
| AliceDevice | | BobDevice | | AliceDevice | | BobDevice |
+-------------+ +-----------+ +-------------+ +-----------+
@ -593,6 +602,7 @@ devices:
| m.key.verification.mac | | m.key.verification.mac |
|<--------------------------------| |<--------------------------------|
| | | |
```
###### Error and exception handling ###### Error and exception handling
@ -805,6 +815,7 @@ she can trust Bob's device if:
The following diagram illustrates how keys are signed: The following diagram illustrates how keys are signed:
```
+------------------+ .................. +----------------+ +------------------+ .................. +----------------+
| +--------------+ | .................. : | +------------+ | | +--------------+ | .................. : | +------------+ |
| | v v v : : v v v | | | | 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 In the diagram, boxes represent keys and lines represent signatures with
the arrows pointing from the signing key to the key being signed. Dotted 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 The following diagram illustrates Alice's view, hiding the keys and
signatures that she cannot see: signatures that she cannot see:
```
+------------------+ +----------------+ +----------------+ +------------------+ +----------------+ +----------------+
| +--------------+ | | | | +------------+ | | +--------------+ | | | | +------------+ |
| | v v | v v v | | | | v v | v v v | |
@ -854,6 +867,7 @@ signatures that she cannot see:
| | | ... | | ... | | | | | | ... | | ... | | |
| +------+ | | +----+ | | +------+ | | +----+ |
+----------------+ +--------------+ +----------------+ +--------------+
```
[Verification methods](#device-verification) can be used to verify a [Verification methods](#device-verification) can be used to verify a
user's master key by using the master public key, encoded using unpadded user's master key by using the master public key, encoded using unpadded

3
content/client-server-api/modules/push.md
Unescape Escape View File

@ -5,6 +5,7 @@ weight: 130
### Push Notifications ### Push Notifications
```
+--------------------+ +-------------------+ +--------------------+ +-------------------+
Matrix HTTP | | | | Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor | Notification Protocol | App Developer | | Device Vendor |
@ -23,8 +24,8 @@ weight: 130
+---+ | +---+ |
| | Provider Push Protocol | | Provider Push Protocol
+----+ +----+
Mobile Device or Client Mobile Device or Client
```
This module adds support for push notifications. Homeservers send This module adds support for push notifications. Homeservers send
notifications of events to user-configured HTTP endpoints. Users may notifications of events to user-configured HTTP endpoints. Users may

2
content/client-server-api/modules/sso_login.md
Unescape Escape View File

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

6
content/client-server-api/modules/third_party_invites.md
Unescape Escape 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 yields a result for a Matrix User ID then the normal invite process can
be initiated. This process ends up looking like this: be initiated. This process ends up looking like this:
```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
| Client | | Homeserver | | IdentityServer | | Client | | Homeserver | | IdentityServer |
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -67,12 +68,14 @@ be initiated. This process ends up looking like this:
| Complete the /invite request | | | Complete the /invite request | |
|<------------------------------------| | |<------------------------------------| |
| | | | | |
```
However, if the lookup does not yield a bound User ID, the homeserver 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 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 `m.room.third_party_invite` event to the room. This process ends up
looking like this: looking like this:
```
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
| Client | | Homeserver | | IdentityServer | | Client | | Homeserver | | IdentityServer |
+---------+ +-------------+ +-----------------+ +---------+ +-------------+ +-----------------+
@ -100,6 +103,7 @@ looking like this:
| Complete the /invite request | | | Complete the /invite request | |
|<------------------------------------| | |<------------------------------------| |
| | | | | |
```
All homeservers MUST verify the signature in the event's All homeservers MUST verify the signature in the event's
`content.third_party_invite.signed` object. `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 would look like the following. This diagram assumes H1 and H2 are
residents of the room while H3 is attempting to join. residents of the room while H3 is attempting to join.
```
+-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+ +-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+
| UserA | | ThirdPartyUser | | H1 | | H2 | | H3 | | IS | | 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 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 not have to block on either server's receipt of the event. Likewise, H1

4
content/client-server-api/modules/voip_events.md
Unescape Escape 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: A call is set up with message events exchanged as follows:
```
Caller Callee Caller Callee
[Place Call] [Place Call]
m.call.invite -----------> m.call.invite ----------->
@ -30,15 +31,18 @@ A call is set up with message events exchanged as follows:
<--------------- m.call.answer <--------------- m.call.answer
[Call is active and ongoing] [Call is active and ongoing]
<--------------- m.call.hangup <--------------- m.call.hangup
```
Or a rejected call: Or a rejected call:
```
Caller Callee Caller Callee
m.call.invite ------------> m.call.invite ------------>
m.call.candidate ---------> m.call.candidate --------->
[..candidates..] ---------> [..candidates..] --------->
[Rejects call] [Rejects call]
<-------------- m.call.hangup <-------------- m.call.hangup
```
Calls are negotiated according to the WebRTC specification. Calls are negotiated according to the WebRTC specification.

2
content/proposals.md
Unescape Escape View File

@ -278,6 +278,7 @@ corresponding labels for each stage on the
[matrix-doc](https://github.com/matrix-org/matrix-doc) issue and pull [matrix-doc](https://github.com/matrix-org/matrix-doc) issue and pull
request trackers. request trackers.
```
+ + + +
Proposals | Spec PRs | Additional States Proposals | Spec PRs | Additional States
+-------+ | +------+ | +---------------+ +-------+ | +------+ | +---------------+
@ -324,6 +325,7 @@ request trackers.
+-----------------+ | +-----------------+ |
| | | |
+ + + +
```
# Lifetime States # Lifetime States

2
content/push-gateway-api.md
Unescape Escape View File

@ -36,6 +36,7 @@ A client's homeserver forwards information about received events to the
push gateway. The gateway then submits a push notification to the push push gateway. The gateway then submits a push notification to the push
notification provider (e.g. APNS, GCM). notification provider (e.g. APNS, GCM).
```
+--------------------+ +-------------------+ +--------------------+ +-------------------+
Matrix HTTP | | | | Matrix HTTP | | | |
Notification Protocol | App Developer | | Device Vendor | Notification Protocol | App Developer | | Device Vendor |
@ -56,6 +57,7 @@ notification provider (e.g. APNS, GCM).
+----+ +----+
Mobile Device or Client Mobile Device or Client
```
## Homeserver behaviour ## Homeserver behaviour

2
content/server-server-api.md
Unescape Escape 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 potentially involve anywhere from two to four homeservers, though most
in practice will use just two. in practice will use just two.
```
Client Joining Directory Resident Client Joining Directory Resident
Server Server Server Server Server Server
@ -705,6 +706,7 @@ in practice will use just two.
<------------------------------- send_join response <------------------------------- send_join response
| |
<---------- join response <---------- join response
```
The first part of the handshake usually involves using the directory The first part of the handshake usually involves using the directory
server to request the room ID and join candidates through the server to request the room ID and join candidates through the

Write Preview
Loading…
Cancel
Save