Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Distinguish room state and timeline events in MSC2762 #4237

Open
wants to merge 2 commits into
base: travis/msc/widgets-send-receive-events
Choose a base branch
from
+61 −13
Open

Distinguish room state and timeline events in MSC2762 #4237

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
60ca531
Distinguish room state and timeline events in MSC2762
robintown Dec 6, 2024
70197cc
Change update_state to an array (to replace room_state_synced)
robintown Dec 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 61 additions & 13 deletions proposals/2762-widget-event-receiving.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ capability of `com.example.event` and an event type of the same name).

The new capabilities are:

* `m.send.event:<event type>` (eg: `m.send.event:m.room.message`) - Used for sending room messages of
* `m.send.event:<event type>` (eg: `m.send.event:m.room.message`) - Used for sending non-state events of
a given type.
* `m.send.state_event:<event type>` (eg: `m.send.state_event:m.room.topic`) - Used for sending state
events of a given type.
Expand Down Expand Up @@ -180,12 +180,12 @@ on behalf of the widget.

In addition to being able to send events into the room, some widgets have an interest in reacting
to particular events that appear in the room. Using a similar approach to the sending of events,
a new capability matching `m.receive.event:<event type>` and `m.receive.state_event:<event type>`
new capabilities matching `m.receive.event:<event type>` and `m.receive.state_event:<event type>`
are introduced, with the same formatting requirements as the `m.send.event` and `m.send.state_event`
capabilities above (ie: `m.receive.event:m.room.message#m.text`).

For each event type requested and approved, the client sends a `toWidget` request with action `event`
is sent to the widget with the `data` being the event itself. For example:
For each event type requested and approved, the client sends a `toWidget` request with action
`send_event` to the widget, with the `data` being the event itself. For example:

```json
{
Expand Down Expand Up @@ -220,6 +220,54 @@ unless they asked for it (and were approved), and they receive *decrypted* event
Note that the client should also be sending the widget any events in rooms where the widget is permitted
to receive events from. The exact details of these permissions are covered later in this document.

## Proposal (receiving room state in a widget)

When a widget is approved to receive some state events, the client begins syncing all room state
entries matching the capabilities in rooms where the widget is permitted to receive events. It
communicates the current state by sending a `toWidget` request with action `update_state`.

```json
{
"api": "toWidget",
"widgetId": "20200827_WidgetExample",
"requestid": "generated-id-1234",
"action": "update_state",
"data": {
"state": [
{
"type": "m.room.topic",
"sender": "@alice:example.org",
"event_id": "$example",
"room_id": "!room:example.org",
"state_key": "",
"origin_server_ts": 1574383781154,
"content": {
"topic": "Hello world!"
},
"unsigned": {
"age": 12345
}
}
]
}
}
```

`data.state` is an array of state events representing the current values of the room state for each
(`room_id`, `type`, `state_key`) tuple. The widget acknowledges receipt of this request with an
empty `response` object.
Comment on lines +256 to +258
Copy link

Choose a reason for hiding this comment

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

Reading through this again for some cases we might need a pagination api.
I think postmessage is only limited by system memory so it does not really need pagination. But for rooms like matrix HQ the client itself does not hold all the room members.

I am not sure if we even want the widget to be able to force the client to download all the member events with this API.
But maybe we should allow the client to inform the widget that it limited the amount of results.
If the widget receives a state update we might want include a list of keys that got capped.
This would allow the widget to know which keys it does not know entirely and where it might want to do a read_event request.

Overall since we do not have a good concept for pagination for messages (state and timeline) in general I don't see this as blocking.
It is not a breaking change that the widget message horizon can be limited by the client. this is already the current behaviour.


Whenever a widget is granted the ability to receive some room state (through a capability
negotiation or renegotiation), the widget may wait upon the next `update_state` action to know when
the requested room state has finished loading. Therefore, if all new room state entries that the
widget may receive are empty, the client must send an `update_state` action with an empty
`data.state` array.

The client continues sending `update_state` actions whenever it observes a change in the relevant
room state. Each action only has to mention the events that changed.

## Proposal (reading events in a widget)

Widgets can also read the events they were approved to receive on demand with the following `fromWidget`
API action:

Expand All @@ -239,9 +287,12 @@ API action:

When a `state_key` is present, the client will respond with state events matching that state key. If
`state_key` is instead a boolean `true`, the client will respond with state events of the given type
with any state key. For clarity, `"state_key": "@alice:example.org"` would return the state event with
the specified state key (there can only be one or zero), while `"state_key": true` would return any
state events of the type, regardless of state key.
with any state key.

For clarity, the state events returned should *not* be understood to represent the current state of
the room. Rather, they are simply events from the room's timeline that match the requested filter,
and may or may not belong to the resolved room state. Multiple events may be returned, even when
requesting a specific state key.

To support the ability to read particular msgtypes, the widget can specify a `msgtype` in place of the
`state_key` for `m.room.message` requests.
Expand All @@ -260,10 +311,7 @@ being able to send events. Web clients, for example, may be more able to send *e
about. The default assumption is that the client will send over as much as possible as an upper limit.

The client is not required to backfill (use the `/messages` endpoint) to get more events for the
widget, and is able to return less than the requested amount of events. When returning state events,
the client should always return the current state event (in the client's view) rather than the history
of an event. For example, `{"type":"m.room.topic", "state_key": "", "limit": 5}` should return zero
or one topic events, not 5, even if the topic has changed more than once.
widget, and is able to return less than the requested amount of events.

An optional `room_ids` property may also be added to the `data` object by the widget, indicating which
room(s) to listen for events in. This is either an array of room IDs, undefined, or the special string
Expand Down Expand Up @@ -327,8 +375,8 @@ because they'll always send events to the user's currently viewed room, and the
without special room timeline permissions.

There is no Widget API action exposed for listing the user's invited/joined rooms: the widget can request
permission to read/receive the `m.room.create` state event of rooms and query that way. Clients should be
aware of this trick and describe the situation appropriately to users.
permission to receive the `m.room.create` state entries of rooms and learn about them that way. Clients
should be aware of this trick and describe the situation appropriately to users.

## Alternatives

Expand Down