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

Add git versions to other parts of the spec

Browse source
This commit is contained in:
Richard van der Hoff 2016-05-06 09:49:26 +01:00
parent 0e4a4e1e44
commit 5cc9066159
4 changed files with 66 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

42
specification/application_service_api.rst
View file

@ -15,6 +15,13 @@ irrespective of the underlying homeserver implementation.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
Application Services
--------------------
Application services are passive and can only observe events from a given
@ -48,9 +55,9 @@ Application services register "namespaces" of user IDs, room aliases and room ID
These namespaces are represented as regular expressions. An application service
is said to be "interested" in a given event if one of the IDs in the event match
the regular expression provided by the application service. An application
service can also state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive"
namespace. An exclusive namespace prevents humans and other application
service can also state whether they should be the only ones who
can manage a specified namespace. This is referred to as an "exclusive"
namespace. An exclusive namespace prevents humans and other application
services from creating/deleting entities in that namespace. Typically,
exclusive namespaces are used when the rooms represent real rooms on
another service (e.g. IRC). Non-exclusive namespaces are used when the
@ -104,12 +111,12 @@ events. Each list of events includes a transaction ID, which works as follows:
Typical
HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK.
AS ACK Lost
HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost.
HS ---> AS : Homeserver retries with the same transaction ID of T.
<--- : AS sends back 200 OK. If the AS had processed these events
<--- : AS 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).
@ -163,11 +170,11 @@ homeserver.
Identity assertion
++++++++++++++++++
The client-server API infers the user ID from the ``access_token`` provided in
The client-server API infers the user ID from the ``access_token`` provided in
every request. It would be an annoying amount of book-keeping to maintain tokens
for every virtual user. It would be preferable if the application service could
use the CS API with its own ``as_token`` instead, and specify the virtual user
they wish to be acting on behalf of. For real users, this would require
they wish to be acting on behalf of. For real users, this would require
additional permissions granting the AS permission to masquerade as a matrix user.
Inputs:
@ -177,7 +184,7 @@ Inputs:
Notes:
- This will apply on all aspects of the CS API, except for Account Management.
- The ``as_token`` is inserted into ``access_token`` which is usually where the
client token is. This is done on purpose to allow application services to
client token is. This is done on purpose to allow application services to
reuse client SDKs.
::
@ -187,7 +194,7 @@ Notes:
Query Parameters:
access_token: The application service token
user_id: The desired user ID to act as.
Timestamp massaging
+++++++++++++++++++
The application service may want to inject events at a certain time (reflecting
@ -199,7 +206,7 @@ Inputs:
- Desired timestamp
Notes:
- This will only apply when sending events.
::
/path?access_token=$token&ts=$timestamp
@ -230,7 +237,7 @@ including the AS token on a ``/register`` request, along with a login type of
::
/register?access_token=$as_token
Content:
{
type: "m.login.application_service",
@ -278,12 +285,12 @@ at the cost of an extra round trip (of which the response can be cached).
Munging the URI would allow clients to apply the mapping locally, but would force
user X on service Y to always map to the same munged user ID. Considering the
exposed API could just be applying this munging, there is more flexibility if
an API is exposed.
an API is exposed.
::
GET /_matrix/app/%CLIENT_MAJOR_VERSION%/user?uri=$url_encoded_uri
Returns 200 OK:
{
user_id: <complete user ID on local HS>
@ -297,22 +304,22 @@ e.g. IRC rooms. We don't want to expose every 3P network room though, e.g.
exposed as an alias by the application service. Private rooms
(e.g. sending an email to someone) should not
be exposed in this way, but should instead operate using normal invite/join semantics.
Therefore, the ID conventions discussed below are only valid for public rooms which
Therefore, the ID conventions discussed below are only valid for public rooms which
expose room aliases.
Matrix users may wish to join XMPP rooms (e.g. using XEP-0045) or IRC rooms. In both
cases, these rooms can be expressed as URIs. For consistency, these "room" URIs
cases, these rooms can be expressed as URIs. For consistency, these "room" URIs
SHOULD be mapped in the same way as "user" URIs.
::
GET /_matrix/app/%CLIENT_MAJOR_VERSION%/alias?uri=$url_encoded_uri
Returns 200 OK:
{
alias: <complete room alias on local HS>
}
Event fields
++++++++++++
We recommend that any events that originated from a remote network should
@ -320,4 +327,3 @@ include an ``external_url`` field in their content to provide a way for Matrix
clients to link into the 'native' client from which the event originated.
For instance, this could contain the message-ID for emails/nntp posts, or a link
to a blog comment when bridging blog comment traffic in & out of Matrix.

7
specification/identity_service_api.rst
View file

@ -12,6 +12,13 @@ practice has only been applied specifically to email addresses.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
General principles
------------------

34
specification/push_gateway.rst
View file

@ -3,9 +3,23 @@ Push Gateway API
Clients may want to receive push notifications when events are received at
the homeserver. This is managed by a distinct entity called the Push Gateway.
A client's homeserver forwards information about the event to the push gateway
and the gateway submits a push notification to the push notification provider
(e.g. APNS, GCM).
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
Overview
--------
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).
::
@ -23,13 +37,13 @@ and the gateway submits a push notification to the push notification provider
Matrix | | | | | |
Client/Server API + | | | | |
| | +--------------------+ +-------------------+
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
| +--+-+ |
| | <-------------------------------------------+
+---+ |
| | Provider Push Protocol
+----+
Mobile Device or Client
Homeserver behaviour

16
specification/server_server_api.rst
View file

@ -44,6 +44,13 @@ request.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
Server Discovery
----------------
@ -188,9 +195,9 @@ servers. Either way the response is a list of JSON objects containing the
JSON published by the server under ``_matrix/key/v2/server/`` signed by
both the originating server and by this server.
The ``minimum_valid_until_ts`` is a millisecond POSIX timestamp indicating
when the returned certificate will need to be valid until to be useful to the
requesting server. This can be set using the maximum ``origin_server_ts`` of
The ``minimum_valid_until_ts`` is a millisecond POSIX timestamp indicating
when the returned certificate will need to be valid until to be useful to the
requesting server. This can be set using the maximum ``origin_server_ts`` of
an batch of events that a requesting server is trying to validate. This allows
an intermediate notary server to give a prompt cached response even if the
originating server is offline.
@ -832,7 +839,7 @@ State Conflict Resolution
-------------------------
.. NOTE::
This section is a work in progress.
.. TODO-doc
- How do conflicts arise (diagrams?)
- How are they resolved (incl tie breaks)
@ -953,4 +960,3 @@ The list of join candidates is a list of server names that are likely to hold
the given room; these are servers that the requesting server may wish to use as
resident servers as part of the remote join handshake. This list may or may not
include the server answering the query.