diff --git a/specification/application_service_api.rst b/specification/application_service_api.rst index 6d983461..16e9b00a 100644 --- a/specification/application_service_api.rst +++ b/specification/application_service_api.rst @@ -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 `_ as of Git commit +`{{git_version}} `_. + 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: @@ -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: } - + 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. - diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index ca841c39..0aa34343 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -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 `_ as of Git commit +`{{git_version}} `_. + General principles ------------------ diff --git a/specification/push_gateway.rst b/specification/push_gateway.rst index d239e702..7e33f35f 100644 --- a/specification/push_gateway.rst +++ b/specification/push_gateway.rst @@ -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 `_ as of Git commit +`{{git_version}} `_. + +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 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 66e50a1f..eaf7eca7 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -44,6 +44,13 @@ request. .. contents:: Table of Contents .. sectnum:: +Specification version +--------------------- + +This version of the specification is generated from +`matrix-doc `_ as of Git commit +`{{git_version}} `_. + 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. -