MSC2477: User-defined ephemeral events in rooms #2477
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,374 @@ | ||||||
| # 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, 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 | ||||||
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||
| feature, where participating client would regularly post their current location relative to a | ||||||
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||
| 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. | ||||||
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||
|
|
||||||
| 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 | ||||||
|
||||||
| `PUT /_matrix/client/r0/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost | |
| `PUT /_matrix/client/v1/rooms/{roomId}/ephemeral/{eventType}/{txnId}`, which would act in an almost |
Following the new per-endpoint versioning spec.
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ananace marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment.
I'm not sure if we should make this off-limits to anything m.*. In fact, I wonder if we should go the opposite way and transition all room-based ephemeral messages to this endpoint - so read receipts and typing notifications.
At the moment, typing notifications are using:
PUT /_matrix/client/v3/rooms/{roomId}/typing/{userId}
{
"timeout": 30000,
"typing": true
}
and read markers are sent with:
POST /_matrix/client/v3/rooms/{roomId}/read_markers
{
"m.fully_read": "$somewhere:example.org",
"m.read": "$elsewhere:example.org"
}
The {userId} bit of the typing endpoint is especially useless, and could be cleaned up in the same move.
Presence and to-device messages would be excluded from this, as they are not bound to a room.
There was a problem hiding this comment.
Read markers seem to be a bit of a special case, as they have an effect on the server to store something quasi-persistent, shouldn't read_markers stay out of this then? or what is the idea behind that?
There was a problem hiding this comment.
I wrote this MSC on the assumption that the custom EDUs would be a separate beast to the built-in EDUs, but I guess it could just as well be done to instead have the server handle well-defined EDUs in a certain manner. So that you - as a client dev/user - could just post m.typing or m.receipt/m.fully_read/m.read EDUs instead of calling the specific endpoints for them.
There was a problem hiding this comment.
Read markers seem to be a bit of a special case, as they have an effect on the server to store something quasi-persistent, shouldn't read_markers stay out of this then? or what is the idea behind that?
Good point. m.fully_read does not fit this model, as its purpose is to store your read-up-to position, which lives in the current user's room account data. The linked endpoint just happens to allow optionally sending an m.read receipt in the same call.
Instead, we should be thinking about whether to replicate the behaviour of POST /_matrix/client/v3/rooms/{roomId}/receipt/{receiptType}/{eventId} with this then.
With that, I'm not so sure. They do fall under the banner of EDU, but a receipt is always tied to an event ID (e.g. I read up to this event ID). We'd need to include that event ID in the body of the request for m.read or for any other type of receipt. That can work, though I suppose it comes down to how much we'd like to differentiate receipts as their own thing, versus just another type of EDU.
ananace marked this conversation as resolved.
Show resolved
Hide resolved
ananace marked this conversation as resolved.
Show resolved
Hide resolved
Outdated
There was a problem hiding this comment.
As mentioned earlier, any change to the auth rules requires a new room version. If we wanted to have these only apply to user-defined types initially, and then fully apply later, that would take two room versions.
Given rooms will need to be recreated anyways, it seems sensible to simply have homeservers pre-fill 0 for m.typing and m.fully_read entries when creating a room to preserve existing behaviour?
There was a problem hiding this comment.
I used m.receipt as the type when I was writing, as I wasn't sure about m.read (and m.fully_read). The resulting event is m.receipt, and the endpoint for sending the information is rooms/{roomId}/receipt. But the receipt type as defined in the content is m.read.
m.fully_read is in the spec handled in a separate endpoint, but includes a link to receipts as you can include m.read in the request to combine the two into a single request. Not sure how that would be combined into things.
For now I think I'm going to keep m.receipt as the general EDU type, since it's the type that - for now - is seen in an actual ephemeral event. (after all m.fully_read only ends up in the account data, and m.read are agglomerated into m.receipt events)
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
Outdated
There was a problem hiding this comment.
room_id isn't part of the spec for ephemeral event bodies down /sync.
Likewise below.
There was a problem hiding this comment.
The spec entry you linked includes an m.typing event in the example response for code 200, which does include room_id in the data;
# ...
"join": {
"!726s6s6q:example.com": {
"account_data": {
"events": [
{
"content": {
"tags": {
"u.work": {
"order": 0.9
}
}
},
"type": "m.tag"
},
{
"content": {
"custom_config_key": "custom_config_value"
},
"type": "org.example.custom.room.config"
}
]
},
"ephemeral": {
"events": [
{
"content": {
"user_ids": [
"@alice:matrix.org",
"@bob:example.com"
]
},
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"type": "m.typing"
}
]
},
# ...I think that's where that came from, since I tried to base my examples directly on the spec examples.
There was a problem hiding this comment.
I see, thanks for pointing that out! I've made a PR to fix that, as I believe that's a spec bug: #3679.
anoadragon453 marked this conversation as resolved.
Show resolved
Hide resolved
ananace marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
This feels suboptimal because it means the room admin needs to know the entire superset of features of all potential clients which may join the room. Consider:
- I create a room on a terminal client that has no knowledge of any of these custom EDUs.
- 6 people join all on clients capable of showing printer status updates.
- See how sad they become as they can't use the feature.
To resolve this requires a fair bit of social work as either:
- someone asks the admin to allow the custom type (assuming the client they are using let's them do this)
- someone asks the admin to make one of the 6 users a mod/admin/to have enough power for their client to automatically (or manually) enable the sending of that custom type.
ananace marked this conversation as resolved.
Show resolved
Hide resolved
anoadragon453 marked this conversation as resolved.
Show resolved
Hide resolved
There was a problem hiding this comment.
This could cause some clients to break though, if they expect the well-defined objects to keep to
their specced forms.
If I understand correctly, this is referring to adding the sender and origin_server_ts fields to a JSON object. In the past I believe we've considered adding keys to JSON to not break backwards compatibility, as clients should just be pulling out the keys they need anyhow - and these events are not signed or otherwise wholly checked for integrity.
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.
This would have to be a problem that we solve anyways, regardless of backwards-compatibility periods.
I'm also not clear why it would be difficult to populate these fields for typing and read receipt lists.
There was a problem hiding this comment.
As one example on the second point; m.typing events are aggregated down from the source data into a single event with a list of user_ids that are currently typing. If they are to have correct timestamps and sender data attached to match the EDU type as defined in this MSC, then they'd have to be split apart into separate objects each with their own metadata. I'm not really sure if that's desirable.
There was a problem hiding this comment.
Unstable prefixes will need to be defined in order for an implementation of the MSC to be carried out. I suggest implementation replace:
ephemeralandephemeral_defaultfields in them.room.power_levelsstate event withorg.matrix.msc2477.ephemeralandorg.matrix.msc2477.ephemeral_defaultrespectively.- the
PUT /_matrix/client/v1/rooms/{roomId}/ephemeral/{eventType}/{txnId}endpoint withPUT /_matrix/client/unstable/org.matrix.msc2477/rooms/{roomId}/ephemeral/{eventType}/{txnId}.
And an experimental room version with name org.matrix.msc2477 should be used where this feature is enabled.
There was a problem hiding this comment.
And a whole lot later than it should've been, but I've added a section on an unstable prefix.
Wasn't sure about adding blurbs on when the m.room.power_levels keys should be allowed, but I figured that it'd a bit superfluous since the only method that will act on them is limited to the experimental room version.
Uh oh!
There was an error while loading. Please reload this page.