Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

MSC2659: Application service ping endpoint #2659

Merged
merged 18 commits into from
May 9, 2023
Merged

MSC2659: Application service ping endpoint #2659

Changes from 1 commit
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5e2c1a8
Proposal for an application service ping endpoint
tulir Jun 29, 2020
a010035
Apply suggestions from code review
tulir Jul 1, 2020
d902c7a
Change unstable prefix and add appserviceId parameter to path
tulir Jul 1, 2020
87cbde6
Merge branch 'main' into appservice-ping
tulir Mar 11, 2023
4d9aa17
Redo MSC to use dedicated endpoint
tulir Mar 11, 2023
015fe1e
Re-add appservice ID path parameter and txn ID body field
tulir Mar 11, 2023
8f8efec
Add some alternatives
tulir Mar 11, 2023
b70620a
Fix path in unstable prefix
tulir Mar 11, 2023
2f87073
Add some optional extra behavior to endpoints
tulir Mar 13, 2023
40416ad
Specify transaction_id type and mention it in both endpoints
tulir Apr 18, 2023
aa6370b
Add note about homeservers not calling ping randomly
tulir Apr 18, 2023
e6c5174
Make it more explicit which request duration is being measured
tulir Apr 18, 2023
3a85761
Add example of full ping flow
tulir Apr 18, 2023
5e33baa
Fix markdown list
tulir Apr 18, 2023
c08f89b
Add /versions endpoint under alternatives
tulir Apr 19, 2023
2f2a43a
Add MSC number to title
tulir Apr 19, 2023
8a72354
Rename duration field
tulir May 1, 2023
f9d5498
Document unstable_features flags
tulir May 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions proposals/2659-appservice-ping.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Application service ping endpoint
tulir marked this conversation as resolved.
Show resolved Hide resolved

## Problem
A relatively common problem when setting up appservices is the connection
between the appservice and homeserver not working in one or both directions.
If the appservice is unable to connect to the homeserver, it can simply show
the error message to the user. However, there's currently no easy way for the
appservice to know if the homeserver is unable to connect to it. This means
that the appservice might start up fine, but not actually work, because the
homeserver isn't sending events to it.

tulir marked this conversation as resolved.
Show resolved Hide resolved
## Proposed solution
The proposed solution is a new endpoint in homeservers that appservices can use
to trigger a "ping". When the endpoint is called, the homeserver will send an
empty transaction to the appservice and reply with the result of that transaction.

Appservices can use the endpoint at startup to ensure communication works in
both directions, and show an error to the user if it doesn't.
Comment on lines +17 to +18
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not a blocker for this MSC, but I would caution against writing applications that refuse to start if they cannot connect to some network service: it means that things will fail to restart during network outages, and means you have to be very careful about the order you bring things up during whole-system restarts.


### `POST /_matrix/client/r0/appservice/ping`
tulir marked this conversation as resolved.
Show resolved Hide resolved
The request body has an optional `txn_id` field that the homeserver must pass
through to the `PUT transactions` call. If not specified, the transaction ID is
up to the homeserver.
tulir marked this conversation as resolved.
Show resolved Hide resolved

The transactions sent via this endpoint should only be attempted once and
excluded from any automatic retry that normal transactions have.

The endpoint is only allowed when using a valid appservice token and it will
ping the appservice associated with the token. Trying to use a non-appservice
token should result in a `M_FORBIDDEN` error.
tulir marked this conversation as resolved.
Show resolved Hide resolved

#### Response
If the transaction request returned successfully, the endpoint should return
HTTP 200 with an empty JSON object as the body.
tulir marked this conversation as resolved.
Show resolved Hide resolved

If the transaction request fails, the endpoint should return a standard error
tulir marked this conversation as resolved.
Show resolved Hide resolved
response with `errcode`s and HTTP status codes as specified below:

* For non-2xx responses, `M_BAD_STATUS` and HTTP 502.
Additionally, homeservers should return the status code and response body in
the `status` and `body` fields respectively to aid with debugging.
* For connection timeouts, `M_CONNECTION_TIMEOUT` and HTTP 504.
* For other connection errors, `M_CONNECTION_FAILED` and HTTP 502.

## Unstable prefix
The endpoint can implemented as `/_matrix/client/unstable/net.maunium/appservice/ping` until it lands in the spec.
turt2live marked this conversation as resolved.
Show resolved Hide resolved