From 3a6f23b756366412f1b49dd6ae47186a4b95762e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 11 Dec 2024 15:33:54 +0100 Subject: [PATCH] Apply suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../newsfragments/2018.feature | 2 +- content/application-service-api.md | 40 +++++++++++-------- .../definitions/registration.yaml | 2 +- .../api/application-service/transactions.yaml | 9 +++-- 4 files changed, 30 insertions(+), 23 deletions(-) diff --git a/changelogs/application_service/newsfragments/2018.feature b/changelogs/application_service/newsfragments/2018.feature index 70001142..ce1ef5bb 100644 --- a/changelogs/application_service/newsfragments/2018.feature +++ b/changelogs/application_service/newsfragments/2018.feature @@ -1 +1 @@ -Allow to send EDUs to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). +Allow to send ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). diff --git a/content/application-service-api.md b/content/application-service-api.md index 7062f7da..2882f3d9 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -207,32 +207,38 @@ processed the events. {{% http-api spec="application-service" api="transactions" %}} -##### Pushing EDUs +##### Pushing ephemeral data {{% added-in v="1.13" %}} If the `receive_ephemeral` settings is enabled in the [registration](#registration) -file, homeservers MUST send all EDUs that are relevant to the application +file, homeservers MUST send ephemeral data that is relevant to the application service via the transaction API, using the `ephemeral` property of the request's body. This property is an array that is effectively a combination of the `presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync) -API. It means that there are only three event types that can currently occur: -[`m.presence`](/client-server-api/#mpresence), [`m.typing`](/client-server-api/#mtyping), -and [`m.receipt`](/client-server-api/#mreceipt). +API. -EDUs that can be associated to a particular room (i.e. `m.typing` or `m.receipt`) -MUST also include a `room_id` property to identify the room that they were sent -in. They should be sent to the application service under the same rules as -regular events, meaning that the application service must have registered -interest in the room itself, or in a user that is in the room. -[Private read receipts](/client-server-api/#private-read-receipts) should only -be sent for users matching one of the application service's namespaces. Normal -read receipts and threaded read receipts are always sent. +There are currently three event types that can be delivered to an application +service: -EDUs which are not associated with a particular room (i.e. `m.presence`), should -be sent to the application service if the EDU would apply contextually. For -example, a presence update for a user an application service shares a room with, -or matching one of the application service's namespaces. +- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the +application service if the data would apply contextually. For example, a +presence update for a user an application service shares a room with, or +matching one of the application service's namespaces. +- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application +service under the same rules as regular events, meaning that the application +service must have registered interest in the room itself, or in a user that is +in the room. The data MUST use the same format as the client-server API, with +the addition of a `room_id` property at the top level to identify the room that +they were sent in. +- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the +application service under the same rules as regular events, meaning that the +application service must have registered interest in the room itself, or in a +user that is in the room. The data MUST use the same format as the client-server +API, with the addition of a `room_id` property at the top level to identify the +room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts) +MUST only be sent for users matching one of the application service's +namespaces. Normal read receipts and threaded read receipts are always sent. #### Pinging diff --git a/data/api/application-service/definitions/registration.yaml b/data/api/application-service/definitions/registration.yaml index ef3ef430..ce702df0 100644 --- a/data/api/application-service/definitions/registration.yaml +++ b/data/api/application-service/definitions/registration.yaml @@ -36,7 +36,7 @@ properties: type: boolean x-addedInMatrixVersion: "1.13" description: |- - Whether the application service wants to [receive EDUs](/application-service-api/#pushing-edus). + Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data). Defaults to `false` if not present. namespaces: diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index 5b8d58bd..9d897df2 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -74,12 +74,13 @@ paths: type: array x-addedInMatrixVersion: "1.13" description: |- - A list of ephemeral events (aka EDUs), if the `receive_ephemeral` setting was - enabled in the [registration](/application-service-api/#registration) file. + A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the + [registration](/application-service-api/#registration) file. There are only three event types that can currently occur: `m.presence`, - `m.typing`, and `m.receipt`. Room-scoped EDUs (`m.typing` and `m.receipt`) MUST - include a `room_id` property to identify the room that they were sent in. + `m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and + `m.receipt`) MUST include a `room_id` property to identify the room that they + were sent in. This property can be omitted if it would be empty. items: