From 2d5bb01a63248e1301b56266ed9872c393994bff Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Wed, 12 Nov 2014 15:32:47 +0200 Subject: [PATCH] add in version, improve AS API a bit, move eventstream to the right place --- specification/00_basis.rst | 18 +++++++--- specification/10_events.rst | 35 ++++++++------------ specification/20_client_server_api.rst | 23 +++++++++++++ specification/30_server_server_api.rst | 1 + specification/40_application_service_api.rst | 30 ++++++++++++++++- 5 files changed, 81 insertions(+), 26 deletions(-) diff --git a/specification/00_basis.rst b/specification/00_basis.rst index 6c00d764..4cb815fb 100644 --- a/specification/00_basis.rst +++ b/specification/00_basis.rst @@ -7,6 +7,9 @@ Table of Contents .. contents:: Table of Contents .. sectnum:: +Introduction +============ + Matrix is a new set of open APIs for open-federated Instant Messaging and VoIP functionality, designed to create and support a new global real-time communication ecosystem on the internet. This specification is the ongoing @@ -78,6 +81,13 @@ instant messages, VoIP call setups, or any other objects that need to be reliably and persistently pushed from A to B in an interoperable and federated manner. +Version +======= + +The Matrix spec is currently rapidly evolving, and there have been no versioned +releases as yet. Versions should be identified by git revision, or failing that +timestamp. + Basis ===== @@ -136,8 +146,8 @@ context of a "Room". Room structure ~~~~~~~~~~~~~~ -A room is a conceptual place where users can send and receive events. Rooms can -be created, joined and left. Events are sent to a room, and all participants in +A room is a conceptual place where users can send and receive events. +Events are sent to a room, and all participants in that room with sufficient access will receive the event. Rooms are uniquely identified internally via a "Room ID", which look like:: @@ -267,7 +277,7 @@ action from the user; either sending a message to a room, or changing presence state from a lower to a higher level of availability (thus: changing state from ``unavailable`` to ``online`` will count as an action for being active, whereas in the other direction will not). This timestamp is presented via a key called -``last_active_ago``, which gives the relative number of miliseconds since the +``last_active_ago``, which gives the relative number of milliseconds since the message is generated/emitted, that the user was last seen active. Home servers can also use the user's choice of presence state as a signal for @@ -439,7 +449,7 @@ authorisation and distribution. These sections must not be encrypted. State Events ++++++++++++ -`State events` are events that update a section of the state of a graph. These +`State events` are events that update a section of state data for a room. These state events hold all the same properties of events, and are part of the event graph. The payload of the event is the replacement value for the particular section of state being updated. diff --git a/specification/10_events.rst b/specification/10_events.rst index 3b9c8e03..88b986e0 100644 --- a/specification/10_events.rst +++ b/specification/10_events.rst @@ -1,28 +1,14 @@ Events ====== -Receiving live updates on a client ----------------------------------- - -Clients can receive new events by long-polling the home server. This will hold -open the HTTP connection for a short period of time waiting for new events, -returning early if an event occurs. This is called the `Event Stream`_. All -events which are visible to the client will appear in the event stream. When -the request returns, an ``end`` token is included in the response. This token -can be used in the next request to continue where the client left off. +All communication in Matrix is expressed in the form of data objects calle +Events. These are the fundamental building blocks common to the client-server, +server-server and application-service APIs, and are described below. .. TODO-spec - How do we filter the event stream? - Do we ever return multiple events in a single request? Don't we get lots of request - setup RTT latency if we only do one event per request? Do we ever support streaming - requests? Why not websockets? - -When the client first logs in, they will need to initially synchronise with -their home server. This is achieved via the |initialSync|_ API. This API also -returns an ``end`` token which can be used with the event stream. + We *HAVE* to clarify the difference between "state events" and "non-state + events" here (or somewhere like it) -.. TODO-spec - We *HAVE* to clarify the difference between "state events" and "non-state events" here (or somewhere like it) Common event fields ------------------- @@ -320,6 +306,13 @@ m.room.message msgtypes .. TODO-spec How a client should handle unknown message types. +.. TODO-spec + We've forgotten m.file... + +.. TODO-spec + It's really confusing that the m. prefix is used both for event types and + for msgtypes. We should namespace them differently somehow. + Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type of message being sent. Each type has their own required and optional keys, as outlined below: @@ -445,8 +438,8 @@ perform extra roundtrips to query it. Voice over IP ------------- Matrix can also be used to set up VoIP calls. This is part of the core -specification, although is still in a very early stage. Voice (and video) over -Matrix is based on the WebRTC standards. +specification, although is at a relatively early stage. Voice (and video) over +Matrix is built on the WebRTC 1.0 standard. Call events are sent to a room, like any other event. This means that clients must only send call events to rooms with exactly two participants as currently diff --git a/specification/20_client_server_api.rst b/specification/20_client_server_api.rst index c0f9fd93..5adfe135 100644 --- a/specification/20_client_server_api.rst +++ b/specification/20_client_server_api.rst @@ -345,6 +345,29 @@ it should request a login fallback page:: This MUST return an HTML page which can perform the entire login process. +Events +------ + +Receiving live updates on a client +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Clients can receive new events by long-polling the home server. This will hold +open the HTTP connection for a short period of time waiting for new events, +returning early if an event occurs. This is called the `Event Stream`_. All +events which are visible to the client will appear in the event stream. When +the request returns, an ``end`` token is included in the response. This token +can be used in the next request to continue where the client left off. + +.. TODO-spec + How do we filter the event stream? + Do we ever return multiple events in a single request? Don't we get lots of request + setup RTT latency if we only do one event per request? Do we ever support streaming + requests? Why not websockets? + +When the client first logs in, they will need to initially synchronise with +their home server. This is achieved via the |initialSync|_ API. This API also +returns an ``end`` token which can be used with the event stream. + Rooms ----- diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index 47c773a5..94cd4169 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -298,6 +298,7 @@ destination home server names, and the actual nested content. Protocol URLs ------------- + .. WARNING:: This section may be misleading or inaccurate. diff --git a/specification/40_application_service_api.rst b/specification/40_application_service_api.rst index 11d9993f..687f477e 100644 --- a/specification/40_application_service_api.rst +++ b/specification/40_application_service_api.rst @@ -1,4 +1,32 @@ 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 application-layer logic in Matrix services, such as... +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). + +Defining a standard API to allow such extensible functionality to be implemented +irrespective of the underlying homeserver implementation is key to enabling +these services. + +Client-Server Services +---------------------- + +.. TODO-spec + Overview of bots + +Passive Application Services +---------------------------- + +.. TODO-spec + API that extends the client-server API to allow events to be + received with better-than-client permissions. + +Active Application Services +---------------------------- + +.. TODO-spec + API that provides hooks into the server so that you can intercept and + manipulate events, and/or insert virtual users & rooms into the server. +