From 5e2c1a8a500d08b4900d09bcdd5d0be22408e74e Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Mon, 29 Jun 2020 14:41:37 +0300 Subject: [PATCH 01/17] Proposal for an application service ping endpoint Signed-off-by: Tulir Asokan --- proposals/2659-appservice-ping.md | 46 +++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 proposals/2659-appservice-ping.md diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md new file mode 100644 index 00000000000..3602c0d2362 --- /dev/null +++ b/proposals/2659-appservice-ping.md @@ -0,0 +1,46 @@ +# Application service ping endpoint + +## 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. + +## 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. + +### `POST /_matrix/client/r0/appservice/ping` +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. + +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. + +#### Response +If the transaction request returned successfully, the endpoint should return +HTTP 200 with an empty JSON object as the body. + +If the transaction request fails, the endpoint should return a standard error +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. From a01003574f5ecc6a31284142eacbd30236e4280b Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Wed, 1 Jul 2020 12:04:41 +0300 Subject: [PATCH 02/17] Apply suggestions from code review Co-authored-by: Travis Ralston --- proposals/2659-appservice-ping.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 3602c0d2362..f82042e9c18 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -27,13 +27,13 @@ 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. +token must result in a `M_FORBIDDEN` error. #### Response -If the transaction request returned successfully, the endpoint should return +If the transaction request returned successfully, the endpoint returns HTTP 200 with an empty JSON object as the body. -If the transaction request fails, the endpoint should return a standard error +If the transaction request fails, the endpoint returns a standard error response with `errcode`s and HTTP status codes as specified below: * For non-2xx responses, `M_BAD_STATUS` and HTTP 502. From d902c7ac615ee53a488a1b2b93a44f4d3fee4e9a Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Wed, 1 Jul 2020 12:11:06 +0300 Subject: [PATCH 03/17] Change unstable prefix and add appserviceId parameter to path Signed-off-by: Tulir Asokan --- proposals/2659-appservice-ping.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index f82042e9c18..ff00d647e9a 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -17,7 +17,7 @@ empty transaction to the appservice and reply with the result of that transactio 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. -### `POST /_matrix/client/r0/appservice/ping` +### `POST /_matrix/client/r0/appservice/{appserviceId}/ping` 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. @@ -25,9 +25,9 @@ up to the homeserver. 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 must result in a `M_FORBIDDEN` error. +The endpoint is only allowed when using a valid appservice token and it can +only ping the appservice ID associated with the token. Trying to use a +non-appservice token must result in a `M_FORBIDDEN` error. #### Response If the transaction request returned successfully, the endpoint returns @@ -43,4 +43,4 @@ response with `errcode`s and HTTP status codes as specified below: * 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. +The endpoint can implemented as `/_matrix/client/unstable/net.maunium.msc2659/appservice/ping` until it lands in the spec. From 4d9aa174d9904c6f133b0c67189a3232d16c3221 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 11 Mar 2023 16:00:16 +0200 Subject: [PATCH 04/17] Redo MSC to use dedicated endpoint Signed-off-by: Tulir Asokan --- proposals/2659-appservice-ping.md | 46 ++++++++++++++++++------------- 1 file changed, 27 insertions(+), 19 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index ff00d647e9a..ed3a67c6f53 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -11,36 +11,44 @@ homeserver isn't sending events to it. ## 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. +to trigger a ping. A new endpoint is also added to the appservice side for the +homeserver to call without any side-effects. 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. -### `POST /_matrix/client/r0/appservice/{appserviceId}/ping` -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. +### `POST /_matrix/app/v1/ping` +This endpoint is on the appservice side. Like all other appservice-side +endpoints, it is authenticated using the `hs_token`. When the token is correct, +this returns HTTP 200 and an empty JSON object as the body. -The transactions sent via this endpoint should only be attempted once and -excluded from any automatic retry that normal transactions have. +### `POST /_matrix/client/v1/appservice/ping` +When the endpoint is called, the homeserver makes a `/_matrix/app/v1/ping` +request to the appservice. -The endpoint is only allowed when using a valid appservice token and it can -only ping the appservice ID associated with the token. Trying to use a -non-appservice token must result in a `M_FORBIDDEN` error. +This endpoint is only allowed when using a valid appservice token and it can +only ping the appservice associated with the token. A potential future +extension would be allowing pinging different appservices using a body field or +query parameter, but that is not included here as there aren't any clear use +cases. #### Response -If the transaction request returned successfully, the endpoint returns -HTTP 200 with an empty JSON object as the body. +If the ping request returned successfully, the endpoint returns HTTP 200. The +response body has a `duration` field containing the ping request roundtrip time +as milliseconds. -If the transaction request fails, the endpoint returns a standard error -response with `errcode`s and HTTP status codes as specified below: +If the request fails, the endpoint returns a standard error 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. +* If the appservice doesn't have a URL configured, `M_URL_NOT_SET` and HTTP 400. +* For non-2xx responses, `M_BAD_STATUS` and HTTP 502. Additionally, the response + may include `status` (integer) and `body` (string) fields containing the HTTP + status code and response body text respectively to aid with debugging. * For connection timeouts, `M_CONNECTION_TIMEOUT` and HTTP 504. * For other connection errors, `M_CONNECTION_FAILED` and HTTP 502. + It is recommended to put a more detailed explanation in the `error` field. ## Unstable prefix -The endpoint can implemented as `/_matrix/client/unstable/net.maunium.msc2659/appservice/ping` until it lands in the spec. +The endpoints can be implemented as `/_matrix/app/unstable/fi.mau.msc2659/ping` +and `/_matrix/client/unstable/fi.mau.msc2659/appservice/ping` until they land +in the spec. Error codes can use `FI.MAU.MSC2659_` instead of `M_` as the prefix. From 015fe1e55397e03c996c540b30c887da138df15f Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 11 Mar 2023 16:49:55 +0200 Subject: [PATCH 05/17] Re-add appservice ID path parameter and txn ID body field --- proposals/2659-appservice-ping.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index ed3a67c6f53..04c18dac9c6 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -22,15 +22,18 @@ This endpoint is on the appservice side. Like all other appservice-side endpoints, it is authenticated using the `hs_token`. When the token is correct, this returns HTTP 200 and an empty JSON object as the body. -### `POST /_matrix/client/v1/appservice/ping` +### `POST /_matrix/client/v1/appservice/{appserviceId}/ping` When the endpoint is called, the homeserver makes a `/_matrix/app/v1/ping` request to the appservice. -This endpoint is only allowed when using a valid appservice token and it can -only ping the appservice associated with the token. A potential future -extension would be allowing pinging different appservices using a body field or -query parameter, but that is not included here as there aren't any clear use -cases. +The request body may contain a `transaction_id` field, which, if present, must +be passed through to the appservice `/ping` request body as-is. + +This endpoint is only allowed when using a valid appservice token, and it can +only ping the appservice associated with the token. If the token or appservice +ID in the path is wrong, the server may return `M_FORBIDDEN`. However, +implementations and future spec proposals may extend what kinds of pings are +allowed. #### Response If the ping request returned successfully, the endpoint returns HTTP 200. The From 8f8efecae7ca4633354d5c10967b4fa8336ac293 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 11 Mar 2023 17:02:44 +0200 Subject: [PATCH 06/17] Add some alternatives --- proposals/2659-appservice-ping.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 04c18dac9c6..3a5889cc857 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -51,6 +51,16 @@ If the request fails, the endpoint returns a standard error response with * For other connection errors, `M_CONNECTION_FAILED` and HTTP 502. It is recommended to put a more detailed explanation in the `error` field. +## Alternatives + +* The ping could make an empty `/transactions` request instead of adding a new + ping endpoint. A new endpoint was found to be cleaner while implementing, and + there didn't seem to be any significant benefits to reusing transactions. +* Appservices could be switched to using websockets instead of the server + pushing events. This option is already used by some bridges, but implementing + websocket support on the homeserver side is much more complicated than a + simple ping endpoint. + ## Unstable prefix The endpoints can be implemented as `/_matrix/app/unstable/fi.mau.msc2659/ping` and `/_matrix/client/unstable/fi.mau.msc2659/appservice/ping` until they land From b70620a35b764c385718b34b08565cd95e30756d Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Sat, 11 Mar 2023 17:05:32 +0200 Subject: [PATCH 07/17] Fix path in unstable prefix --- proposals/2659-appservice-ping.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 3a5889cc857..33095c7b743 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -63,5 +63,5 @@ If the request fails, the endpoint returns a standard error response with ## Unstable prefix The endpoints can be implemented as `/_matrix/app/unstable/fi.mau.msc2659/ping` -and `/_matrix/client/unstable/fi.mau.msc2659/appservice/ping` until they land -in the spec. Error codes can use `FI.MAU.MSC2659_` instead of `M_` as the prefix. +and `/_matrix/client/unstable/fi.mau.msc2659/appservice/{appserviceId}/ping`. +Error codes can use `FI.MAU.MSC2659_` instead of `M_` as the prefix. From 2f8707396e7d54a244ff0c66822bdaa5163440ff Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Mon, 13 Mar 2023 18:35:36 +0200 Subject: [PATCH 08/17] Add some optional extra behavior to endpoints --- proposals/2659-appservice-ping.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 33095c7b743..013479c7ee8 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -22,6 +22,10 @@ This endpoint is on the appservice side. Like all other appservice-side endpoints, it is authenticated using the `hs_token`. When the token is correct, this returns HTTP 200 and an empty JSON object as the body. +Appservices don't need to have any special behavior on this endpoint, but they +may use the incoming request to verify that an outgoing ping actually pinged +the appservice rather than going somewhere else. + ### `POST /_matrix/client/v1/appservice/{appserviceId}/ping` When the endpoint is called, the homeserver makes a `/_matrix/app/v1/ping` request to the appservice. @@ -35,6 +39,10 @@ ID in the path is wrong, the server may return `M_FORBIDDEN`. However, implementations and future spec proposals may extend what kinds of pings are allowed. +In case the homeserver had backed off on sending transactions, it may treat a +successful ping as a sign that the appservice is up again and transactions +should be retried. + #### Response If the ping request returned successfully, the endpoint returns HTTP 200. The response body has a `duration` field containing the ping request roundtrip time From 40416ad1abb0697c836129df68cf5e7417ff03bf Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 18 Apr 2023 21:21:21 +0300 Subject: [PATCH 09/17] Specify transaction_id type and mention it in both endpoints --- proposals/2659-appservice-ping.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 013479c7ee8..64e3e03cd58 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -22,6 +22,9 @@ This endpoint is on the appservice side. Like all other appservice-side endpoints, it is authenticated using the `hs_token`. When the token is correct, this returns HTTP 200 and an empty JSON object as the body. +The request body contains an optional `transaction_id` string field, which +comes from the client ping request defined below. + Appservices don't need to have any special behavior on this endpoint, but they may use the incoming request to verify that an outgoing ping actually pinged the appservice rather than going somewhere else. @@ -30,8 +33,8 @@ the appservice rather than going somewhere else. When the endpoint is called, the homeserver makes a `/_matrix/app/v1/ping` request to the appservice. -The request body may contain a `transaction_id` field, which, if present, must -be passed through to the appservice `/ping` request body as-is. +The request body may contain a `transaction_id` string field, which, if present, +must be passed through to the appservice `/ping` request body as-is. This endpoint is only allowed when using a valid appservice token, and it can only ping the appservice associated with the token. If the token or appservice From aa6370bc0fe531bf392894e23b28c570f7971afa Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 18 Apr 2023 21:31:14 +0300 Subject: [PATCH 10/17] Add note about homeservers not calling ping randomly --- proposals/2659-appservice-ping.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 64e3e03cd58..89f37020c3b 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -29,6 +29,11 @@ Appservices don't need to have any special behavior on this endpoint, but they may use the incoming request to verify that an outgoing ping actually pinged the appservice rather than going somewhere else. +This proposal doesn't define any cases where a homeserver would call the ping +endpoint unless explicitly requested by the appservice (using the client +endpoint below). Therefore, appservices don't necessarily have to implement +this endpoint if they never call the client ping endpoint. + ### `POST /_matrix/client/v1/appservice/{appserviceId}/ping` When the endpoint is called, the homeserver makes a `/_matrix/app/v1/ping` request to the appservice. From e6c51744e6dff2721e767e47788dbb42350e64ba Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 18 Apr 2023 21:31:59 +0300 Subject: [PATCH 11/17] Make it more explicit which request duration is being measured --- proposals/2659-appservice-ping.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 89f37020c3b..dc0335af764 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -53,8 +53,8 @@ should be retried. #### Response If the ping request returned successfully, the endpoint returns HTTP 200. The -response body has a `duration` field containing the ping request roundtrip time -as milliseconds. +response body has a `duration` field containing the `/_matrix/app/v1/ping` +request roundtrip time as milliseconds. If the request fails, the endpoint returns a standard error response with `errcode`s and HTTP status codes as specified below: From 3a85761e3cbf5f8f45e4ca81864e5c8dc09d78fd Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 18 Apr 2023 21:33:46 +0300 Subject: [PATCH 12/17] Add example of full ping flow --- proposals/2659-appservice-ping.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index dc0335af764..71e4a775b21 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -67,6 +67,18 @@ If the request fails, the endpoint returns a standard error response with * For other connection errors, `M_CONNECTION_FAILED` and HTTP 502. It is recommended to put a more detailed explanation in the `error` field. +### Example flow + +1. bridge -> homeserver (request #1): `POST http://synapse:8008/_matrix/client/v1/appservice/whatsapp/ping` + * Header `Authorization: Bearer as_token` + * Body: `{"transaction_id": "meow"}` +2. homeserver -> bridge (request #2): `POST http://bridge:29318/_matrix/app/v1/ping` + * Header `Authorization: Bearer hs_token` + * Body: `{"transaction_id": "meow"}` +3. bridge -> homeserver (response to #2): 200 OK with body `{}` +4. homeserver -> bridge (response to #1): 200 OK with body `{"duration": 123}` + (123 milliseconds being the time it took for request #2 to complete). + ## Alternatives * The ping could make an empty `/transactions` request instead of adding a new From 5e33baabc6cdf884a5ab00b0e5109bc0f26f74dc Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 18 Apr 2023 21:34:47 +0300 Subject: [PATCH 13/17] Fix markdown list --- proposals/2659-appservice-ping.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 71e4a775b21..e711fb9b93c 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -70,11 +70,11 @@ If the request fails, the endpoint returns a standard error response with ### Example flow 1. bridge -> homeserver (request #1): `POST http://synapse:8008/_matrix/client/v1/appservice/whatsapp/ping` - * Header `Authorization: Bearer as_token` - * Body: `{"transaction_id": "meow"}` + * Header `Authorization: Bearer as_token` + * Body: `{"transaction_id": "meow"}` 2. homeserver -> bridge (request #2): `POST http://bridge:29318/_matrix/app/v1/ping` - * Header `Authorization: Bearer hs_token` - * Body: `{"transaction_id": "meow"}` + * Header `Authorization: Bearer hs_token` + * Body: `{"transaction_id": "meow"}` 3. bridge -> homeserver (response to #2): 200 OK with body `{}` 4. homeserver -> bridge (response to #1): 200 OK with body `{"duration": 123}` (123 milliseconds being the time it took for request #2 to complete). From c08f89bb157833406911ddaf218f2cd774287d6b Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Thu, 20 Apr 2023 00:14:46 +0300 Subject: [PATCH 14/17] Add /versions endpoint under alternatives --- proposals/2659-appservice-ping.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index e711fb9b93c..782ff8a1df3 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -84,6 +84,11 @@ If the request fails, the endpoint returns a standard error response with * The ping could make an empty `/transactions` request instead of adding a new ping endpoint. A new endpoint was found to be cleaner while implementing, and there didn't seem to be any significant benefits to reusing transactions. +* A `/versions` endpoint could be introduced to work for both pinging and + checking what spec versions an appservice supports. However, it's not clear + that a new endpoint is the best way to detect version support (a simple flag + in the registration file may be preferable), so this MSC proposes a `/ping` + endpoint that doesn't have other behavior. * Appservices could be switched to using websockets instead of the server pushing events. This option is already used by some bridges, but implementing websocket support on the homeserver side is much more complicated than a From 2f2a43ad67b8eb0856c4228c6588aa12b49a2071 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Thu, 20 Apr 2023 00:43:55 +0300 Subject: [PATCH 15/17] Add MSC number to title Co-authored-by: Travis Ralston --- proposals/2659-appservice-ping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 782ff8a1df3..38131735f99 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -1,4 +1,4 @@ -# Application service ping endpoint +# MSC2659: Application service ping endpoint ## Problem A relatively common problem when setting up appservices is the connection From 8a72354259b8dae9e6051fc9488192a5f35d1d29 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Mon, 1 May 2023 10:50:07 +0300 Subject: [PATCH 16/17] Rename duration field --- proposals/2659-appservice-ping.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index 38131735f99..b0b11af79db 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -53,7 +53,7 @@ should be retried. #### Response If the ping request returned successfully, the endpoint returns HTTP 200. The -response body has a `duration` field containing the `/_matrix/app/v1/ping` +response body has a `duration_ms` field containing the `/_matrix/app/v1/ping` request roundtrip time as milliseconds. If the request fails, the endpoint returns a standard error response with @@ -76,7 +76,7 @@ If the request fails, the endpoint returns a standard error response with * Header `Authorization: Bearer hs_token` * Body: `{"transaction_id": "meow"}` 3. bridge -> homeserver (response to #2): 200 OK with body `{}` -4. homeserver -> bridge (response to #1): 200 OK with body `{"duration": 123}` +4. homeserver -> bridge (response to #1): 200 OK with body `{"duration_ms": 123}` (123 milliseconds being the time it took for request #2 to complete). ## Alternatives From f9d54985a38b5e764b7caacd51dcb802635959d2 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 2 May 2023 14:44:05 +0300 Subject: [PATCH 17/17] Document unstable_features flags --- proposals/2659-appservice-ping.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2659-appservice-ping.md b/proposals/2659-appservice-ping.md index b0b11af79db..90deda5cec3 100644 --- a/proposals/2659-appservice-ping.md +++ b/proposals/2659-appservice-ping.md @@ -98,3 +98,8 @@ If the request fails, the endpoint returns a standard error response with The endpoints can be implemented as `/_matrix/app/unstable/fi.mau.msc2659/ping` and `/_matrix/client/unstable/fi.mau.msc2659/appservice/{appserviceId}/ping`. Error codes can use `FI.MAU.MSC2659_` instead of `M_` as the prefix. + +`fi.mau.msc2659` can be used as an `unstable_features` flag in `/versions` to +indicate support for the unstable prefixed endpoint. Once the MSC is approved, +`fi.mau.msc2659.stable` can be used to indicate support for the stable endpoint +until the spec release containing the endpoint is supported.