From aad3e260b82e707ad10102b4b1e0d4d1949c6df7 Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Sat, 28 Mar 2020 10:53:02 +0100 Subject: [PATCH 01/13] MSC for user-defined ephemeral events --- .../2477-user-defined-ephemeral-events.md | 337 ++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 proposals/2477-user-defined-ephemeral-events.md diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md new file mode 100644 index 00000000000..6c83410736d --- /dev/null +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -0,0 +1,337 @@ +# MSC2476: User-defined ephemeral events in rooms + +Matrix currently handles the transfer of data in the form of Persistent- as well as Ephemeral Data +Units, both of which follow the same general design in the way they're encoded and transferred over +both the Client-Server and Server-Server API. + +Currently only users are only able to provide their own event types and data in the case of +persistent data, in the form of state events as well as messages / timeline events. +The sending of ephemeral data by clients - on the other hand - is currently limited to only typing +notifications, event receipts, read markers, and presence updates. Which greatly limits the +potential usefulness of ephemeral events as a general mechanism for transferring short-lived data. + +Therefore, this proposal suggest extending both the Client-Server and Server-Server APIs to allow +users to transfer arbitrary ephemeral data types and content into rooms in which they have the right +to do so. + + +## Proposal + +The proposed change is to add support for users to provide their own data types and content, in a +similar manner to the already existing support for users to send their own types of persistent data. + +Note though that this proposal does not include any support for sending user-defined ephemeral +events which are not explicitly bound to rooms, like the global `m.presence` event. + +Examples of how this feature could be used are; as regular status updates to a user-requested +long-lived task, which a bot might has started for a received event. Or pehaps as a GPS live-location +feature, where participating client would regularly post their current location relative to a +persistent geo-URI event. Perhaps for organizing meetups, or for viewing active tracking of the +locations of vehicles in an autonomous fleet - along with peristent messages posted at a lesser +rate for a timeline generation. + +The example that will be used througout this proposal is an ephemeral data object that's tracking +the current status of a user-requested 3D print, with some basic printer- and print-status +information being sent every few seconds to a control room, including a reference to the event that +the status is referring to - which the client could use to render a progress bar or other graphic +with. + +### Addition of an ephemeral event sending endpoint to the Client-Server API + +The suggested addition to the CS API is the endpoint +`PUT /_matrix/client/r0/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost +identical manner to the event sending endpoint that is already present. +An example of how an update might be posted using the new endpoint; + +``` +PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/ephemeral/com.example.3dprint/19914 HTTP/1.1 +Content-Type: application/json + +{ + "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", + "printer_id": 10, + "status": { + "hotend_c": 181.4, + "bed_c": 62.5, + "position": [54, 275, 87.2] + }, + "time": { + "elapsed": 4324, + "estimated": 7439 + } +} +``` + +Example of a response; + +Status code 200: + +```json +{} +``` + + +**NB**; +To reduce the risk of abuse, this endpoint is suggested to never allow sending any ephemeral data of +any type matching the wildcard `m.*`, instead keeping the sending of those well-defined event types +under their already existing endpoints. + +An error that could be returned for a user attempting to send such a blocked type is suggested as; + +Status code 403 + +```json +{ + "errcode": "M_FORBIDDEN", + "error": "Cannot send this ephemeral type" +} +``` + +### Extension of power levels to handle user-defined ephemeral events + +As it would be possible for the user-defined events to be used to flood a room with invisible +traffic by malicious users - increasing the bandwidth usage for all connected servers, this proposal +also suggests extending the power levels to handle ephemeral types as well. + +The suggested keys to add to the `m.room.power_levels` events are as follows; + +- `ephemeral`, of type `{string: integer}` +- `ephemeral_default`, of type `integer` + +These new keys are suggested to function in an identical manner to the already existing `events` and +`events_default` keys, with the suggested default - and fallback - value for `ephemeral_default` +being 50, while the suggested default - and fallback - values for `ephemeral` would be; + +```json +{ + "m.fully_read": 0, + "m.receipt": 0, + "m.typing": 0 +} +``` + +**NB**; +To reduce the complexity of the change, this proposal suggests to - for the time being - only limit +the user-defined types by these power levels changes. The default values for `m.*` specified here in +`ephemeral_defaults` would then only be expected to be informational in purpose. + +### Extension of the ephemeral data received in /sync responses + +Because the user-defined ephemeral events can't be aggregated and massaged by Synapse in a simple +manner, this then suggests instead adding a few more (**optional** but suggested for `m.*`, +**required** otherwise) fields to the ephemeral events as they are encoded in a sync response. The +suggested additions are; + +- `sender`, of type `string` +- `origin_server_ts`, of type `integer` + +To reduce the risk of breaking existing clients, as well as reducing the scope of change required by +this proposal, the suggestion is to leave the original `m.*` events unaltered for now - therefore +the use of fields that can be both optional *as well as* required depending on the ephemeral type. + +```json +{ + "next_batch": "...", + // ... + "rooms": { + "join": { + "!636q39766251:example.com": { + // ... + "timeline": { + "events": [ + { + "content": { + "gcode": "mxc://example.com/GEnfasiifADESSAF", + "printer": 10, + }, + "type": "com.example.3dprint_request", + "event_id": "$4CvDieFIFAzSYaykmBObZ2iUhSa5XNEUnC-GQfLl2yc", + "room_id": "!636q39766251:example.com", + "sender": "@alice:matrix.org", + "origin_server_ts": 1432735824653, + "unsigned": { + "age": 5558 + } + }, + { + "content": { + "body": "Print of fan_shroud_v5.gcode started on printer 10, ETA is 2h. Stream is available at https://example.com/printers/10.m3u8", + "print": { + "gcode": "mxc://example.com/GEnfasiifADESSAF", + "printer": 10, + "video": "https://example.com/printers/10.m3u", + "eta": 7253 + }, + "m.relates_to": { + "m.in_reply_to": { + "event_id": "$4CvDieFIFAzSYaykmBObZ2iUhSa5XNEUnC-GQfLl2yc" + } + }, + "msgtype": "m.text" + }, + "origin_server_ts": 1432735825887, + "sender": "@printbot:example.com", + "type": "m.room.message", + "unsigned": { + "age": 4324 + }, + "event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", + "room_id": "" + } + ] + }, + "ephemeral": { + "events": [ + { + "content": { + "user_ids": [ + "@alice:matrix.org", + "@bob:example.com" + ] + }, + "type": "m.typing", + "room_id": "!636q39766251:example.com" + }, + { + "content": { + "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", + "printer_id": 10, + "status": { + "hotend_c": 181.4, + "bed_c": 62.5, + "position": [54, 275, 87.2] + }, + "time": { + "elapsed": 4324, + "estimated": 7440 + } + }, + "type": "com.example.3dprint", + "room_id": "!636q39766251:example.com", + "sender": "@printbot:example.com", + "origin_server_ts": 1432735830211 + } + ] + } + } + } + } +} +``` + +### Extension of the Server-Server spec + +As the server-server protocol is currently only designed for transferring the well-defined EDUs that +exist as part of the Matrix communication protocol, this proposal suggests adding additional fields +to the EDU schema in order to let them transmit the user-specified data untouched - while still +adding source information that is important for the receiving clients. + +The suggested (**optional** but suggested for `m.*`, **required** otherwise) fields to add to the +EDU schema are; + +- `room_id`, of type `string` +- `sender`, of type `string` +- `origin`, of type `string` +- `origin_server_ts`, of type `integer` + +A user-defined ephemeral event could then look like this when federated; + +```json +{ + "content": { + "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo" + "printer_id": "10", + "status": { + "hotend_c": 181.4, + "bed_c": 62.5, + "position": [54, 275, 87.2] + }, + "time": { + "elapsed": 4324, + "estimated": 7440 + } + }, + "room_id": "!636q39766251:example.com", + "sender": "@printbot:example.com", + "origin": "example.com", + "origin_server_ts": 1432735830211, + "edu_type": "com.example.3dprint" +} +``` + + +## Potential issues + +Because this change completely redefines how ephemeral events are used, it is likely to be expected +that some servers and clients could struggle to handle the new types of data that this proposal +would create. But as the protocol is defined with an extensible transport - JSON, it should not be +difficult - if even necessary - for clients or servers to be modified to support the changes. + +Additionally, as ephemeral data is never encoded into room state there's not as many tools for +admins to handle abuse that occur through the use of the feature. +The proposals suggested changes to power levels - and limitation of what event types can be sent - +should mitigate the potential of abuse from the feature though, as long as admins don't allow any +user-defined ephemeral types to be sent by regular users. + +This change could impact the - currently in review - [MSC2409], necessitating some kind of filter for +what event types would be transferred to appservices. + + +## Alternatives + +The ephemeral state that this change would allow to transfer could as easily be sent using +self-destructing messages with the help of [MSC1763] or [MSC2228], which would result in a similar +experience to the end user. +Unfortunately using persistent events in such a manner would add a lot of unnecessary data to the +room DAG, while also increasing both the computational work and the database pressure through the +repeated and rapid insertions and redactions that it would result in. + +### Client-Server protocol changes + +The additions to ephemeral objects could be expanded to also apply to the normal `m.*` types as well, +which would reduce the complexity of the spec as there would be no distinction between the built-in +Matrix types as well as the user-defined types. +This could cause some clients to break though, if they expect the well-defined objects to keep to +their specced forms. + +### Server-Server protocol changes + +Instead of adding potentially optional keys to the EDU schema, the entire object could instead be +embedded into the content key, using an EDU type key that denotes it as an user-defined type. +This would mean a smaller change to the server-server communication, while still allowing a server +module to filter or track events based on their types or origins. + +```json +{ + "content": { + "room_id": "!636q39766251:example.com", + "sender": "@printbot:example.com", + "origin": "example.com", + "origin_server_ts": 1432735830211, + "type": "com.example.3dprint", + "content": { + "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", + "printer_id": "10", + "status": { + "hotend_c": 181.4, + "bed_c": 62.5, + "position": [54, 275, 87.2] + }, + "time": { + "elapsed": 4324, + "estimated": 7440 + } + } + }, + "edu_type": "m.user_defined" +} +``` + +Possibly, the additional requirements for user-defined types could instead also be expanded to cover +the regular Matrix types as well, which would remove the need for optional fields - but could in +return impact the federation between servers, if they're built to only handle the exact requirements +of the spec. + +[MSC1763]: https://github.com/matrix-org/matrix-doc/blob/matthew/msc1763/proposals/1763-configurable-retention-periods.md +[MSC2228]: https://github.com/matrix-org/matrix-doc/tree/matthew/msc2228/proposals/2228-self-destructing-events.md +[MSC2409]: https://github.com/Sorunome/matrix-doc/blob/soru%2Bhs/appservice-edus/proposals/2409-appservice-edus.md From 4aa82b82cbb39e0d96ba3dc833813a4b8926f162 Mon Sep 17 00:00:00 2001 From: "Alexander \"Ananace\" Olofsson" Date: Mon, 30 Mar 2020 09:38:31 +0200 Subject: [PATCH 02/13] Fix a missing comma in example JSON Co-Authored-By: Sorunome --- proposals/2477-user-defined-ephemeral-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index 6c83410736d..b2b9beded26 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -239,7 +239,7 @@ A user-defined ephemeral event could then look like this when federated; ```json { "content": { - "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo" + "print_event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", "printer_id": "10", "status": { "hotend_c": 181.4, From d4930c075600ce081cc96269786bcfa5540bef15 Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Mon, 30 Mar 2020 20:19:05 +0200 Subject: [PATCH 03/13] Remove the requirement to forbid sending m.* types As there's no similar requirement for PDUs, adding one for EDUs might be a bit overkill. --- proposals/2477-user-defined-ephemeral-events.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index b2b9beded26..eae599bfc54 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -70,23 +70,6 @@ Status code 200: {} ``` - -**NB**; -To reduce the risk of abuse, this endpoint is suggested to never allow sending any ephemeral data of -any type matching the wildcard `m.*`, instead keeping the sending of those well-defined event types -under their already existing endpoints. - -An error that could be returned for a user attempting to send such a blocked type is suggested as; - -Status code 403 - -```json -{ - "errcode": "M_FORBIDDEN", - "error": "Cannot send this ephemeral type" -} -``` - ### Extension of power levels to handle user-defined ephemeral events As it would be possible for the user-defined events to be used to flood a room with invisible From ba0b6570b4651d4f6e6b490130296309db679f68 Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Sat, 4 Apr 2020 13:28:37 +0200 Subject: [PATCH 04/13] Relink MSCs to point to their respective PR --- proposals/2477-user-defined-ephemeral-events.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index eae599bfc54..eb9dc427713 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -315,6 +315,6 @@ the regular Matrix types as well, which would remove the need for optional field return impact the federation between servers, if they're built to only handle the exact requirements of the spec. -[MSC1763]: https://github.com/matrix-org/matrix-doc/blob/matthew/msc1763/proposals/1763-configurable-retention-periods.md -[MSC2228]: https://github.com/matrix-org/matrix-doc/tree/matthew/msc2228/proposals/2228-self-destructing-events.md -[MSC2409]: https://github.com/Sorunome/matrix-doc/blob/soru%2Bhs/appservice-edus/proposals/2409-appservice-edus.md +[MSC1763]: https://github.com/matrix-org/matrix-doc/pull/1763 +[MSC2228]: https://github.com/matrix-org/matrix-doc/pull/2228 +[MSC2409]: https://github.com/matrix-org/matrix-doc/pull/2409 From 0b27339d9f6834a43c44ed6de9f9dc60cc1dd67d Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Sat, 4 Apr 2020 13:30:12 +0200 Subject: [PATCH 05/13] Add reference to MSC2487 for appservice filtering --- proposals/2477-user-defined-ephemeral-events.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index eb9dc427713..4f3ae4e67ee 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -257,7 +257,8 @@ should mitigate the potential of abuse from the feature though, as long as admin user-defined ephemeral types to be sent by regular users. This change could impact the - currently in review - [MSC2409], necessitating some kind of filter for -what event types would be transferred to appservices. +what event types would be transferred to appservices. [MSC2487] suggests a possible solution for this +potential problem. ## Alternatives @@ -318,3 +319,4 @@ of the spec. [MSC1763]: https://github.com/matrix-org/matrix-doc/pull/1763 [MSC2228]: https://github.com/matrix-org/matrix-doc/pull/2228 [MSC2409]: https://github.com/matrix-org/matrix-doc/pull/2409 +[MSC2487]: https://github.com/matrix-org/matrix-doc/pull/2487 From 5dc9372fe665e98d3a2b9f6285446b9b711db667 Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Sat, 4 Apr 2020 15:14:21 +0200 Subject: [PATCH 06/13] Namespace the extra key in the room sync example --- proposals/2477-user-defined-ephemeral-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index 4f3ae4e67ee..c4c80fecdc5 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -139,7 +139,7 @@ the use of fields that can be both optional *as well as* required depending on t { "content": { "body": "Print of fan_shroud_v5.gcode started on printer 10, ETA is 2h. Stream is available at https://example.com/printers/10.m3u8", - "print": { + "com.example.3dprint": { "gcode": "mxc://example.com/GEnfasiifADESSAF", "printer": 10, "video": "https://example.com/printers/10.m3u", From dd488d3eaf245955d736b4cc60377176c443368e Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Wed, 9 Sep 2020 13:25:44 +0200 Subject: [PATCH 07/13] Update from some comments --- .../2477-user-defined-ephemeral-events.md | 103 +++++++++++++----- 1 file changed, 78 insertions(+), 25 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index c4c80fecdc5..270203e7d0d 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -7,8 +7,8 @@ both the Client-Server and Server-Server API. Currently only users are only able to provide their own event types and data in the case of persistent data, in the form of state events as well as messages / timeline events. The sending of ephemeral data by clients - on the other hand - is currently limited to only typing -notifications, event receipts, read markers, and presence updates. Which greatly limits the -potential usefulness of ephemeral events as a general mechanism for transferring short-lived data. +notifications, event receipts, and presence updates. Which greatly limits the potential usefulness +of ephemeral events as a general mechanism for transferring short-lived data. Therefore, this proposal suggest extending both the Client-Server and Server-Server APIs to allow users to transfer arbitrary ephemeral data types and content into rooms in which they have the right @@ -66,51 +66,99 @@ Example of a response; Status code 200: +As EDUs do not have event IDs, this is an empty JSON object + ```json {} ``` +Status code 400: + +The user tried to send a `m.*` EDU, instead of using the type-specific endpoint + +```json +{ + "errcode": "M_UNKNOWN", + "error": "Cannot send built-in ephemeral types with this endpoint" +} +``` + +Status code 403: + +Power levels forbid the user from sending the attempted EDU + +```json +{ + "errcode": "M_FORBIDDEN", + "error": "You do not have permission to send the EDU" +} +``` + +User is not in the room + +```json +{ + "errcode": "M_FORBIDDEN", + "error": "You are not a member of the room" +} +``` + +Status code 429: + +The request was rate-limited + +```json +{ + "errcode": "M_LIMIT_EXCEEDED", + "error": "Too many requests", + "retry_after_ms": 2000 +} +``` + ### Extension of power levels to handle user-defined ephemeral events As it would be possible for the user-defined events to be used to flood a room with invisible traffic by malicious users - increasing the bandwidth usage for all connected servers, this proposal also suggests extending the power levels to handle ephemeral types as well. -The suggested keys to add to the `m.room.power_levels` events are as follows; +In any room version implementing this MSC, the auth rules to include in `m.room.power_levels` are; -- `ephemeral`, of type `{string: integer}` -- `ephemeral_default`, of type `integer` +- `ephemeral` (`{string: integer}`) - A mapping of EDU types to the power-level required to send them +- `ephemeral_default` (`integer`) - The default power-level required to send any EDU not listed in +the above mapping -These new keys are suggested to function in an identical manner to the already existing `events` and +These new keys are to function in an identical manner to the already existing `events` and `events_default` keys, with the suggested default - and fallback - value for `ephemeral_default` being 50, while the suggested default - and fallback - values for `ephemeral` would be; ```json { - "m.fully_read": 0, + "m.read": 0, "m.receipt": 0, "m.typing": 0 } ``` +These defaults are to ensure that all current Matrix EDUs continue to work as intended. + **NB**; To reduce the complexity of the change, this proposal suggests to - for the time being - only limit the user-defined types by these power levels changes. The default values for `m.*` specified here in -`ephemeral_defaults` would then only be expected to be informational in purpose. +`ephemeral` would then only be expected to be informational in purpose. -### Extension of the ephemeral data received in /sync responses +### Extension of the room-specific ephemeral data received in /sync responses Because the user-defined ephemeral events can't be aggregated and massaged by Synapse in a simple -manner, this then suggests instead adding a few more (**optional** but suggested for `m.*`, -**required** otherwise) fields to the ephemeral events as they are encoded in a sync response. The -suggested additions are; +manner, this then suggests instead adding a few more fields to the room-specific ephemeral events as +they are encoded in a sync response. The suggested additions are; -- `sender`, of type `string` -- `origin_server_ts`, of type `integer` +- `sender` (`string`) - The fully qualified ID of the user that sent the EDU +- `origin_server_ts` (`integer`) - Timestamp in milliseconds on the originating homeserver when this +event was sent To reduce the risk of breaking existing clients, as well as reducing the scope of change required by -this proposal, the suggestion is to leave the original `m.*` events unaltered for now - therefore -the use of fields that can be both optional *as well as* required depending on the ephemeral type. +this proposal, the suggestion is to allow the original `m.*` events to skip these keys where no value +could be easily assigned to them. E.g. typing notices, read receipts. ```json { @@ -125,7 +173,7 @@ the use of fields that can be both optional *as well as* required depending on t { "content": { "gcode": "mxc://example.com/GEnfasiifADESSAF", - "printer": 10, + "printer": 10 }, "type": "com.example.3dprint_request", "event_id": "$4CvDieFIFAzSYaykmBObZ2iUhSa5XNEUnC-GQfLl2yc", @@ -209,15 +257,15 @@ exist as part of the Matrix communication protocol, this proposal suggests addin to the EDU schema in order to let them transmit the user-specified data untouched - while still adding source information that is important for the receiving clients. -The suggested (**optional** but suggested for `m.*`, **required** otherwise) fields to add to the -EDU schema are; +The suggested fields to add to the EDU schema are; -- `room_id`, of type `string` -- `sender`, of type `string` -- `origin`, of type `string` -- `origin_server_ts`, of type `integer` +- `room_id` (`string`) - The fully qualified ID of the room the event was sent in +- `sender` (`string`) - The fully qualified ID of the user that sent the event +- `origin` (`string`) - The `server_name` of the homeserver that created this event +- `origin_server_ts` (`integer`) - Timestamp in milliseconds on origin homeserver when this event +was created -A user-defined ephemeral event could then look like this when federated; +A user-defined ephemeral event might then look like this when federated; ```json { @@ -242,6 +290,9 @@ A user-defined ephemeral event could then look like this when federated; } ``` +To reduce the scope of change required by this proposal, the suggestion is to allow the original +`m.*` events to skip these keys where no value can be easily assigned to them. E.g. aggregated typing +notices, receipt lists. ## Potential issues @@ -276,7 +327,9 @@ The additions to ephemeral objects could be expanded to also apply to the normal which would reduce the complexity of the spec as there would be no distinction between the built-in Matrix types as well as the user-defined types. This could cause some clients to break though, if they expect the well-defined objects to keep to -their specced forms. +their specced forms. Additionally, it might be hard for the server to assign a correct sender and +timestamp to events if they are aggregated from multiple sources - e.g. typing notices and read +receipt lists. ### Server-Server protocol changes From 9d736978a8277b85cb3016e49da0afe9810125b3 Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Wed, 9 Sep 2020 13:33:05 +0200 Subject: [PATCH 08/13] Remove non-existing EDU from fallback list --- proposals/2477-user-defined-ephemeral-events.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index 270203e7d0d..a0ca07eac85 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -133,7 +133,6 @@ being 50, while the suggested default - and fallback - values for `ephemeral` wo ```json { - "m.read": 0, "m.receipt": 0, "m.typing": 0 } From 2f4dd474f3cd314f8637e925b357d7d51ed3e634 Mon Sep 17 00:00:00 2001 From: "Alexander \"Ananace\" Olofsson" Date: Sun, 1 Aug 2021 11:36:39 +0200 Subject: [PATCH 09/13] Update proposals/2477-user-defined-ephemeral-events.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Šimon Brandner --- proposals/2477-user-defined-ephemeral-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index a0ca07eac85..13f7c620c3a 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -4,7 +4,7 @@ Matrix currently handles the transfer of data in the form of Persistent- as well Units, both of which follow the same general design in the way they're encoded and transferred over both the Client-Server and Server-Server API. -Currently only users are only able to provide their own event types and data in the case of +Currently, users are only able to provide their own event types and data in the case of persistent data, in the form of state events as well as messages / timeline events. The sending of ephemeral data by clients - on the other hand - is currently limited to only typing notifications, event receipts, and presence updates. Which greatly limits the potential usefulness From 047d63bd1a1d4a3da4a549e138294714d9fa2fdb Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Tue, 30 Nov 2021 21:12:43 +0100 Subject: [PATCH 10/13] Update according to review comments --- .../2477-user-defined-ephemeral-events.md | 70 ++++++++++++------- 1 file changed, 44 insertions(+), 26 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index a0ca07eac85..c3e064f2238 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -23,28 +23,29 @@ similar manner to the already existing support for users to send their own types Note though that this proposal does not include any support for sending user-defined ephemeral events which are not explicitly bound to rooms, like the global `m.presence` event. + Examples of how this feature could be used are; as regular status updates to a user-requested long-lived task, which a bot might has started for a received event. Or pehaps as a GPS live-location feature, where participating client would regularly post their current location relative to a persistent geo-URI event. Perhaps for organizing meetups, or for viewing active tracking of the -locations of vehicles in an autonomous fleet - along with peristent messages posted at a lesser +locations of vehicles in an autonomous fleet - maybe along with peristent messages posted at a lesser rate for a timeline generation. The example that will be used througout this proposal is an ephemeral data object that's tracking the current status of a user-requested 3D print, with some basic printer- and print-status information being sent every few seconds to a control room, including a reference to the event that -the status is referring to - which the client could use to render a progress bar or other graphic +the status is referring to - which the client could use to render a progress bar or some other graphic with. ### Addition of an ephemeral event sending endpoint to the Client-Server API -The suggested addition to the CS API is the endpoint -`PUT /_matrix/client/r0/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost +The addition to the CS API is the endpoint +`PUT /_matrix/client/v3/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost identical manner to the event sending endpoint that is already present. An example of how an update might be posted using the new endpoint; ``` -PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/ephemeral/com.example.3dprint/19914 HTTP/1.1 +PUT /_matrix/client/v3/rooms/%21636q39766251%3Aexample.com/ephemeral/com.example.3dprint/19914 HTTP/1.1 Content-Type: application/json { @@ -121,15 +122,23 @@ As it would be possible for the user-defined events to be used to flood a room w traffic by malicious users - increasing the bandwidth usage for all connected servers, this proposal also suggests extending the power levels to handle ephemeral types as well. -In any room version implementing this MSC, the auth rules to include in `m.room.power_levels` are; +In any room version implementing this MSC, the auth rules concerning ephemeral events in the +`m.room.power_levels` event are; - `ephemeral` (`{string: integer}`) - A mapping of EDU types to the power-level required to send them - `ephemeral_default` (`integer`) - The default power-level required to send any EDU not listed in the above mapping These new keys are to function in an identical manner to the already existing `events` and -`events_default` keys, with the suggested default - and fallback - value for `ephemeral_default` -being 50, while the suggested default - and fallback - values for `ephemeral` would be; +`events_default` keys, with the assumed default value for `ephemeral_default` - if there is no +`ephemeral_default` in the `m.room.power_levels` event - being 50, while the default values for +`ephemeral` - if there is no `ephemeral` in the `m.room.power_levels` event - would consider all types +to be `ephemeral_default`, or 0 if there is no `m.room.power_levels` event - which would then not allow +any ephemeral events to be sent. + +It is therefore recommended for servers to include at least the following `ephemeral` configuration +for all newly created rooms of any room version implementing this MSC, to allow for the sending of +the default ephemeral events in Matrix; ```json { @@ -138,26 +147,19 @@ being 50, while the suggested default - and fallback - values for `ephemeral` wo } ``` -These defaults are to ensure that all current Matrix EDUs continue to work as intended. - -**NB**; -To reduce the complexity of the change, this proposal suggests to - for the time being - only limit -the user-defined types by these power levels changes. The default values for `m.*` specified here in -`ephemeral` would then only be expected to be informational in purpose. - ### Extension of the room-specific ephemeral data received in /sync responses Because the user-defined ephemeral events can't be aggregated and massaged by Synapse in a simple -manner, this then suggests instead adding a few more fields to the room-specific ephemeral events as -they are encoded in a sync response. The suggested additions are; +manner, this MSC instead requires adding a few more fields to the room-specific ephemeral events as +they are encoded in a sync response. The additions in question are; - `sender` (`string`) - The fully qualified ID of the user that sent the EDU -- `origin_server_ts` (`integer`) - Timestamp in milliseconds on the originating homeserver when this -event was sent +- `origin_server_ts` (`integer`) - The timestamp in milliseconds on the originating homeserver when +- this event was sent -To reduce the risk of breaking existing clients, as well as reducing the scope of change required by -this proposal, the suggestion is to allow the original `m.*` events to skip these keys where no value -could be easily assigned to them. E.g. typing notices, read receipts. +To reduce the scope of changes required by this proposal, the suggestion is to allow the original +`m.*` events to skip these keys where no value could be easily assigned to them. E.g. typing notices, +read receipts. ```json { @@ -249,14 +251,29 @@ could be easily assigned to them. E.g. typing notices, read receipts. } ``` +### Delivery guarantees + +The current ephemeral event system in Matrix is built on a sort-of guaranteed delivery - albeit with +mutation/consolidation - of the events. This might not be desirable with custom ephemeral events, as +they could contain volumes of data that's not as easy to keep around for a guaranteed delivery. + +Therefore I suggest that servers are only required to provide best-effort delivery, with the exact +method in how they propagate EDUs - and store them - left up to implementation. +(Perhaps keeping a max-size ring buffer per room - that will thus remove old data when necessary. +Or maybe only storing per active sync token, per user, per device.) + +As the messages in question are ephemeral, I think the only guarantee that should be required is that +all users that are online when the message is sent will receive it. Anything above that should be +commended, but not required. + ### Extension of the Server-Server spec As the server-server protocol is currently only designed for transferring the well-defined EDUs that -exist as part of the Matrix communication protocol, this proposal suggests adding additional fields -to the EDU schema in order to let them transmit the user-specified data untouched - while still +exist as part of the Matrix communication protocol, this proposal requires some additional fields to +be added the EDU schema in order to let them transmit the user-specified data untouched - while still adding source information that is important for the receiving clients. -The suggested fields to add to the EDU schema are; +The fields to add to the EDU schema are; - `room_id` (`string`) - The fully qualified ID of the room the event was sent in - `sender` (`string`) - The fully qualified ID of the user that sent the event @@ -289,10 +306,11 @@ A user-defined ephemeral event might then look like this when federated; } ``` -To reduce the scope of change required by this proposal, the suggestion is to allow the original +To reduce the scope of the changes required by this proposal, the suggestion is to allow the original `m.*` events to skip these keys where no value can be easily assigned to them. E.g. aggregated typing notices, receipt lists. + ## Potential issues Because this change completely redefines how ephemeral events are used, it is likely to be expected From ff2ddbe182a3ba0d453129c48b4ae7df4140da3a Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Mon, 10 Jan 2022 06:09:43 +0100 Subject: [PATCH 11/13] Merge some review suggestions --- proposals/2477-user-defined-ephemeral-events.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index 5d1fcb9dcea..a193632b4df 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -23,7 +23,6 @@ similar manner to the already existing support for users to send their own types Note though that this proposal does not include any support for sending user-defined ephemeral events which are not explicitly bound to rooms, like the global `m.presence` event. - Examples of how this feature could be used are; as regular status updates to a user-requested long-lived task, which a bot might has started for a received event. Or pehaps as a GPS live-location feature, where participating client would regularly post their current location relative to a @@ -161,7 +160,7 @@ To reduce the scope of changes required by this proposal, the suggestion is to a `m.*` events to skip these keys where no value could be easily assigned to them. E.g. typing notices, read receipts. -```json +```jsonc { "next_batch": "...", // ... From 64e9460c09fb32a133fe9305c0a6215b5cb46edf Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Wed, 9 Feb 2022 22:17:30 +0100 Subject: [PATCH 12/13] Some more review comment changes --- .../2477-user-defined-ephemeral-events.md | 103 ++++++++++++------ 1 file changed, 72 insertions(+), 31 deletions(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index a193632b4df..620444b4079 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -24,11 +24,11 @@ Note though that this proposal does not include any support for sending user-def events which are not explicitly bound to rooms, like the global `m.presence` event. Examples of how this feature could be used are; as regular status updates to a user-requested -long-lived task, which a bot might has started for a received event. Or pehaps as a GPS live-location -feature, where participating client would regularly post their current location relative to a +long-lived task, which a bot might have started for a received event. Or perhaps as a GPS live-location +feature, where participating clients would regularly post their current location relative to a persistent geo-URI event. Perhaps for organizing meetups, or for viewing active tracking of the locations of vehicles in an autonomous fleet - maybe along with peristent messages posted at a lesser -rate for a timeline generation. +rate for timeline generation. The example that will be used througout this proposal is an ephemeral data object that's tracking the current status of a user-requested 3D print, with some basic printer- and print-status @@ -39,12 +39,13 @@ with. ### Addition of an ephemeral event sending endpoint to the Client-Server API The addition to the CS API is the endpoint -`PUT /_matrix/client/v3/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost -identical manner to the event sending endpoint that is already present. -An example of how an update might be posted using the new endpoint; +`PUT /_matrix/client/v1/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost +identical manner to the [`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`][PUT Room Event] +endpoint that is already present. +An example of how an update might be posted using the new endpoint is provided as; ``` -PUT /_matrix/client/v3/rooms/%21636q39766251%3Aexample.com/ephemeral/com.example.3dprint/19914 HTTP/1.1 +PUT /_matrix/client/v1/rooms/%21636q39766251%3Aexample.com/ephemeral/com.example.3dprint/19914 HTTP/1.1 Content-Type: application/json { @@ -122,22 +123,21 @@ traffic by malicious users - increasing the bandwidth usage for all connected se also suggests extending the power levels to handle ephemeral types as well. In any room version implementing this MSC, the auth rules concerning ephemeral events in the -`m.room.power_levels` event are; +`m.room.power_levels` state event are; - `ephemeral` (`{string: integer}`) - A mapping of EDU types to the power-level required to send them - `ephemeral_default` (`integer`) - The default power-level required to send any EDU not listed in the above mapping -These new keys are to function in an identical manner to the already existing `events` and -`events_default` keys, with the assumed default value for `ephemeral_default` - if there is no -`ephemeral_default` in the `m.room.power_levels` event - being 50, while the default values for -`ephemeral` - if there is no `ephemeral` in the `m.room.power_levels` event - would consider all types -to be `ephemeral_default`, or 0 if there is no `m.room.power_levels` event - which would then not allow -any ephemeral events to be sent. +These new keys are expected to function in an identical manner to the already existing `events` and +`events_default` keys in the `m.room.power_levels` state event. +The fallback value for `ephemeral_default` - if missing - should be 50, while the fallback value for +the `ephemeral` dictionary should be `{}` - or an empty mapping. Which would imply that _any_ ephemeral +event type should require a power level of at least `ephemeral_default` (or 50) to send. -It is therefore recommended for servers to include at least the following `ephemeral` configuration -for all newly created rooms of any room version implementing this MSC, to allow for the sending of -the default ephemeral events in Matrix; +With this change it is therefore recommended for servers to include at least the following `ephemeral` +configuration for all newly created rooms - of any room version implementing this MSC, to allow for +clients continued sending of the default ephemeral events in Matrix; ```json { @@ -146,19 +146,63 @@ the default ephemeral events in Matrix; } ``` +An example of what a full `m.room.power_levels` object could look like with this MSC; + +```json +{ + "type": "m.room.power_levels", + "sender": "@alice:example.com", + "content": { + "users": { + "@alice:example.com": 100 + }, + "users_default": 0, + "events": { + "m.room.name": 50, + "m.room.power_levels": 100, + "m.room.history_visibility": 100, + "m.room.canonical_alias": 50, + "m.room.avatar": 50, + "m.room.tombstone": 100, + "m.room.server_acl": 100, + "m.room.encryption": 100 + }, + "events_default": 0, + "ephemeral": { + "m.receipt": 0, + "m.typing": 0 + }, + "ephemeral_default": 50, + "state_default": 50, + "ban": 50, + "kick": 50, + "redact": 50, + "invite": 0 + }, + "state_key": "", + "origin_server_ts": 1627993163991, + "unsigned": { + "age": 10418356643 + }, + "event_id": "$za6Ba5Rosa6pahn8the7phairei3eiM3aithoh4aev0moh4siephec6laeraiyaF", + "room_id": "!lioc7Ree1eekea4u:example.com" +} + +``` + ### Extension of the room-specific ephemeral data received in /sync responses -Because the user-defined ephemeral events can't be aggregated and massaged by Synapse in a simple +Because the user-defined ephemeral events can't be aggregated and massaged by the homeserver in a simple manner, this MSC instead requires adding a few more fields to the room-specific ephemeral events as they are encoded in a sync response. The additions in question are; - `sender` (`string`) - The fully qualified ID of the user that sent the EDU - `origin_server_ts` (`integer`) - The timestamp in milliseconds on the originating homeserver when -- this event was sent +this event was sent -To reduce the scope of changes required by this proposal, the suggestion is to allow the original -`m.*` events to skip these keys where no value could be easily assigned to them. E.g. typing notices, -read receipts. +To reduce the scope of changes required by this proposal, it is suggested to allow the original `m.*` +events to skip these keys where no value could be easily assigned to them. E.g. typing notices, read +receipts. ```jsonc { @@ -177,7 +221,6 @@ read receipts. }, "type": "com.example.3dprint_request", "event_id": "$4CvDieFIFAzSYaykmBObZ2iUhSa5XNEUnC-GQfLl2yc", - "room_id": "!636q39766251:example.com", "sender": "@alice:matrix.org", "origin_server_ts": 1432735824653, "unsigned": { @@ -206,8 +249,7 @@ read receipts. "unsigned": { "age": 4324 }, - "event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo", - "room_id": "" + "event_id": "$E2RPcyuMUiXyDkQ02ASEbFxcJ4wFNrt5JVgov0wrqWo" } ] }, @@ -220,8 +262,7 @@ read receipts. "@bob:example.com" ] }, - "type": "m.typing", - "room_id": "!636q39766251:example.com" + "type": "m.typing" }, { "content": { @@ -238,7 +279,6 @@ read receipts. } }, "type": "com.example.3dprint", - "room_id": "!636q39766251:example.com", "sender": "@printbot:example.com", "origin_server_ts": 1432735830211 } @@ -269,8 +309,8 @@ commended, but not required. As the server-server protocol is currently only designed for transferring the well-defined EDUs that exist as part of the Matrix communication protocol, this proposal requires some additional fields to -be added the EDU schema in order to let them transmit the user-specified data untouched - while still -adding source information that is important for the receiving clients. +be added to the EDU schema in order to let them transmit the user-specified data untouched - while +still adding source information that is important for the receiving clients. The fields to add to the EDU schema are; @@ -319,7 +359,7 @@ difficult - if even necessary - for clients or servers to be modified to support Additionally, as ephemeral data is never encoded into room state there's not as many tools for admins to handle abuse that occur through the use of the feature. -The proposals suggested changes to power levels - and limitation of what event types can be sent - +The proposal's suggested changes to power levels - and limitation of what event types can be sent - should mitigate the potential of abuse from the feature though, as long as admins don't allow any user-defined ephemeral types to be sent by regular users. @@ -385,6 +425,7 @@ the regular Matrix types as well, which would remove the need for optional field return impact the federation between servers, if they're built to only handle the exact requirements of the spec. +[PUT Room Event]: https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid [MSC1763]: https://github.com/matrix-org/matrix-doc/pull/1763 [MSC2228]: https://github.com/matrix-org/matrix-doc/pull/2228 [MSC2409]: https://github.com/matrix-org/matrix-doc/pull/2409 From d01e95d9551fde256036de51f9cace526f3a5eeb Mon Sep 17 00:00:00 2001 From: Alexander Olofsson Date: Fri, 3 Jun 2022 14:33:31 +0200 Subject: [PATCH 13/13] Add note on unstable prefix for implementation --- proposals/2477-user-defined-ephemeral-events.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/proposals/2477-user-defined-ephemeral-events.md b/proposals/2477-user-defined-ephemeral-events.md index 620444b4079..bbe4c6d9e45 100644 --- a/proposals/2477-user-defined-ephemeral-events.md +++ b/proposals/2477-user-defined-ephemeral-events.md @@ -204,7 +204,7 @@ To reduce the scope of changes required by this proposal, it is suggested to all events to skip these keys where no value could be easily assigned to them. E.g. typing notices, read receipts. -```jsonc +```json5 { "next_batch": "...", // ... @@ -425,6 +425,17 @@ the regular Matrix types as well, which would remove the need for optional field return impact the federation between servers, if they're built to only handle the exact requirements of the spec. + +## Unstable Prefix + +During implementation, the URL for submitting user-defined EDUs should be +`PUT /_matrix/client/unstable/org.matrix.msc2477/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, and +should only be allowed for rooms versioned as `org.matrix.msc2477`. (Using room version 9 as the base) + +Similarly, the keys `ephemeral` and `ephemeral_default` in `m.room.power_levels` should be prefixed +with `org.matrix.msc2477.` until this MSC is incorporated into a stable room version. + + [PUT Room Event]: https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid [MSC1763]: https://github.com/matrix-org/matrix-doc/pull/1763 [MSC2228]: https://github.com/matrix-org/matrix-doc/pull/2228