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

add in version, improve AS API a bit, move eventstream to the right place

Browse source
This commit is contained in:
Matthew Hodgson 2014-11-12 15:32:47 +02:00
parent b2295b9bc7
commit 2d5bb01a63
5 changed files with 81 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

18
specification/00_basis.rst
View file

@ -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.

35
specification/10_events.rst
View file

@ -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?
We *HAVE* to clarify the difference between "state events" and "non-state
events" here (or somewhere like it)
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.
.. 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

23
specification/20_client_server_api.rst
View file

@ -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
-----

1
specification/30_server_server_api.rst
View file

@ -298,6 +298,7 @@ destination home server names, and the actual nested content.
Protocol URLs
-------------
.. WARNING::
This section may be misleading or inaccurate.

30
specification/40_application_service_api.rst
View file

@ -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.