diff --git a/content/_index.md b/content/_index.md index 7740f2d1..66c4709b 100644 --- a/content/_index.md +++ b/content/_index.md @@ -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 diff --git a/content/application-service-api.md b/content/application-service-api.md index 9ef44d6d..089d8884 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -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 diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 34dad1bc..e3bec2f1 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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 -> 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 -> 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 -> 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 -> 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//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}} diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 598c5c9f..d0af1e8a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -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. - - +----------+ +--------------+ - | Bob's HS | | Bob's Device | - +----------+ +--------------+ - | | - |<=============| - /keys/upload - - 2) Alice requests Bob's public identity keys and supported algorithms. - +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 +``` + +2) Alice requests Bob's public identity keys and supported algorithms. + +``` +----------------+ +------------+ +----------+ | Alice's Device | | Alice's HS | | Bob's HS | +----------------+ +------------+ +----------+ | | | |=================>|==============>| /keys/query +``` - 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 +``` ##### 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 diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index b377715c..e3ca6ebf 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -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 diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 99787bf7..7137aaa7 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -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 diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index 1c689fe5..0a1296bc 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -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 diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 9c155708..4b1cd1bd 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -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. diff --git a/content/proposals.md b/content/proposals.md index 28d56419..f0682f2e 100644 --- a/content/proposals.md +++ b/content/proposals.md @@ -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 diff --git a/content/push-gateway-api.md b/content/push-gateway-api.md index 92a6ca32..ba9dd5b7 100644 --- a/content/push-gateway-api.md +++ b/content/push-gateway-api.md @@ -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 - +----+ - - Mobile Device or Client + Client/Server API + | | | | | + | | +--------------------+ +-------------------+ + | +--+-+ | + | | <-------------------------------------------+ + +---+ | + | | Provider Push Protocol + +----+ + + Mobile Device or Client +``` ## Homeserver behaviour diff --git a/content/server-server-api.md b/content/server-server-api.md index 025457e3..e499d626 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -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