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

Add spec for MSC2659: application service ping endpoint (#1516)

Browse source
This commit is contained in:
Tulir Asokan 2023-05-23 20:36:37 +03:00 • committed by GitHub
parent f564c07e60
commit 9dd9639dd7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 272 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

57
content/application-service-api.md
View file

@ -207,6 +207,54 @@ processed the events.
{{% http-api spec="application-service" api="transactions" %}}
#### Pinging
{{% added-in v="1.7" %}}
The application service API includes a ping mechanism to allow
appservices to ensure that the homeserver can reach the appservice.
Appservices may use this mechanism to detect misconfigurations and
report them appropriately.
Implementations using this mechanism should take care to not fail
entirely in the event of temporary issues, e.g. gracefully handling
cases where the appservice is started before the homeserver.
The mechanism works as follows (note: the human-readable `error` fields
have been omitted for brevity):
**Typical**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
HS <--- AS : 200 OK {}
AS <--- HS : 200 OK {"duration_ms": 123}
```
**Incorrect `hs_token`**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body": "{\"errcode\": \"M_FORBIDDEN\"}"}
```
**Can't connect to appservice**
```
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
```
The `/_matrix/app/v1/ping` endpoint is described here. The
[`/_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping)
endpoint is under the Client-Server API extensions section below.
{{% http-api spec="application-service" api="ping" %}}
#### Querying
The application service API includes two querying APIs: for room aliases
@ -388,6 +436,15 @@ an application service-defined namespace will receive the same
`M_EXCLUSIVE` error code, but only if the application service has
defined the namespace as `exclusive`.
#### Pinging
{{% added-in v="1.7" %}}
This is the client-server API companion endpoint for the
[pinging](#pinging) mechanism described above.
{{% http-api spec="client-server" api="appservice_ping" %}}
#### Using `/sync` and `/events`
Application services wishing to use `/sync` or `/events` from the