98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# Futures for the widget api
|
|
|
|
With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Delayed events is introduced.
|
|
Delayed events are events that will be inserted into the dag (and distributed to all clients and federating
|
|
servers) a time after **now** (based on a delay that can be refreshed).
|
|
|
|
Those events are useful to implement scheduled messages or a last will mechanisms. Since the delayed events are refreshable,
|
|
it is possible to send an event with a short timeout and send restarts to that timeout. This behaves like a heartbeat and
|
|
the event is sent once the heartbeat stops: As a last will.
|
|
|
|
This msc only specifies how the widget api uses this concept. [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140)
|
|
gives more details about the delayed events themselves.
|
|
|
|
Exposing delayed events to the widget is required for widgets implementing MatrixRTC.
|
|
Futures are needed for reliable MatrixRTC memberships that get cleaned up when a client looses network connection.
|
|
|
|
Since ElementCall (EC) is a widget and based on MatrixRTC this widget api proposel is required for EC to work.
|
|
|
|
## Proposal
|
|
|
|
### Sending Future events
|
|
|
|
We extend the `"send_event"` request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762)
|
|
as follows:
|
|
|
|
```jsonc
|
|
{
|
|
state_key?: string;
|
|
type: string;
|
|
content: unknown;
|
|
room_id?: string;
|
|
delay?: number; // new field
|
|
}
|
|
```
|
|
|
|
and the `"send_event"` response:
|
|
|
|
```jsonc
|
|
{
|
|
room_id: string;
|
|
event_id?: string; // now optional
|
|
delay_id?: string; // new field
|
|
}
|
|
```
|
|
|
|
To provide the same properties needed for [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140).
|
|
The client is responsible to check for the `delay` field of the widget action and send the correct http request if it
|
|
is present.
|
|
|
|
### Sending `update_delayed_event` actions
|
|
|
|
```jsonc
|
|
{
|
|
"direction": "fromWidget",
|
|
"action":"update_delayed_event",
|
|
"data":{
|
|
"delay_id": string,
|
|
"action":"cancel"|"send"|"refresh"
|
|
}
|
|
}
|
|
```
|
|
|
|
The response is empty on success or otherwise a widget error response.
|
|
|
|
### Capabilities
|
|
|
|
Two new capabilities will be introduces:
|
|
|
|
- `m.send.delay_events`\
|
|
allows to send delayed events by using the optional `delay` property in a `fromWidget send_event` widget action.
|
|
- `m.update_delayed_event`\
|
|
allows to update delayed events using the `fromWidget update_delayed_event` widget action.
|
|
|
|
Receiving events does not require a special permission since delayed events are not distinguishable from normal events
|
|
from the receiver side.
|
|
|
|
For sending a delayed event two capabilities are required. One for sending the event type itself and the `m.send.delay_events`
|
|
capability to send it as a delayed event.
|
|
|
|
## Alternatives
|
|
|
|
A more granular capability configuration for sending delayed events can be imagined. Where
|
|
each event type gets its own capability to sent this type with a delay. Since we always need the capability for the
|
|
event type itself it might be sufficient to ask for delayed event sending in general.
|
|
|
|
But it is then possible to send any of the events the widget can sent as delayed events.
|
|
|
|
## Unstable prefix
|
|
|
|
The following strings will have unstable prefixes:
|
|
|
|
- The widget action:\
|
|
`update_delayed_event` -> `org.matrix.msc4157.update_delayed_event`
|
|
- The send delayed event capability:\
|
|
`m.send.delayed_event` -> `org.matrix.msc4157.send.delayed_event`
|
|
- The update delayed event capability:\
|
|
`m.update_delayed_event` -> `org.matrix.msc4157.update_delayed_event`
|