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

Misc. cleanup of the appservice spec

Browse source
This commit is contained in:
Travis Ralston 2018-08-24 16:54:53 -06:00
parent f01cfa2c7b
commit 07153c22a9
1 changed files with 11 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

22
specification/application_service_api.rst
View file

@ -48,12 +48,12 @@ https://github.com/matrix-org/matrix-doc/blob/master/changelogs/application_serv
Application Services Application Services
-------------------- --------------------
Application services are passive and can only observe events from a given Application services are passive and can only observe events from a given
homeserver (HS). They can inject events into rooms they are participating in. homeserver. They can inject events into rooms they are participating in.
They cannot prevent events from being sent, nor can they modify the content of They cannot prevent events from being sent, nor can they modify the content of
the event being sent. In order to observe events from a homeserver, the the event being sent. In order to observe events from a homeserver, the
homeserver needs to be configured to pass certain types of traffic to the homeserver needs to be configured to pass certain types of traffic to the
application service. This is achieved by manually configuring the homeserver application service. This is achieved by manually configuring the homeserver
with information about the application service (AS). with information about the application service.
Registration Registration
~~~~~~~~~~~~ ~~~~~~~~~~~~
@ -187,24 +187,24 @@ events. Each list of events includes a transaction ID, which works as follows:
Typical Typical
HS ---> AS : Homeserver sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<--- : AS sends back 200 OK. <--- : Application Service sends back 200 OK.
AS ACK Lost AS ACK Lost
HS ---> AS : Homeserver sends events with transaction ID T. HS ---> AS : Homeserver sends events with transaction ID T.
<-/- : AS 200 OK is lost. <-/- : AS 200 OK is lost.
HS ---> AS : Homeserver retries with the same transaction ID of T. HS ---> AS : Homeserver retries with the same transaction ID of T.
<--- : AS sends back 200 OK. If the AS had processed these events <--- : Application Service sends back 200 OK. If the AS had processed these
already, it can NO-OP this request (and it knows if it is the same events already, it can NO-OP this request (and it knows if it is the
events based on the transaction ID). same events based on the transaction ID).
The events sent to the application service should be linearised, as if they were 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 transactions to from the event stream. The homeserver MUST maintain a queue of transactions to
send to the AS. If the application service cannot be reached, the homeserver send to the application service. If the application service cannot be reached, the
SHOULD backoff exponentially until the application service is reachable again. homeserver SHOULD backoff exponentially until the application service is reachable again.
As application services cannot *modify* the events in any way, these requests can As application services cannot *modify* the events in any way, these requests can
be made without blocking other aspects of the homeserver. Homeservers MUST NOT be made without blocking other aspects of the homeserver. Homeservers MUST NOT
alter (e.g. add more) events they were going to send within that transaction ID alter (e.g. add more) events they were going to send within that transaction ID
on retries, as the AS may have already processed the events. on retries, as the application service may have already processed the events.
{{transactions_as_http_api}} {{transactions_as_http_api}}
@ -334,7 +334,7 @@ users needs API changes in order to:
- Have a 'passwordless' user. - Have a 'passwordless' user.
This involves bypassing the registration flows entirely. This is achieved by This involves bypassing the registration flows entirely. This is achieved by
including the AS token on a ``/register`` request, along with a login type of including the ``as_token`` on a ``/register`` request, along with a login type of
``m.login.application_service`` to set the desired user ID without a password. ``m.login.application_service`` to set the desired user ID without a password.
:: ::
@ -374,8 +374,6 @@ additional parameters on the ``/publicRooms`` client-server endpoint.
Event fields Event fields
~~~~~~~~~~~~ ~~~~~~~~~~~~
.. TODO-TravisR: Fix this section to be a general "3rd party networks" section
We recommend that any events that originated from a remote network should We recommend that any events that originated from a remote network should
include an ``external_url`` field in their content to provide a way for Matrix 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. clients to link into the 'native' client from which the event originated.