From cc0d665e64825b23eaa8527c3837f10c0a001565 Mon Sep 17 00:00:00 2001 From: Timo Date: Wed, 19 Jun 2024 16:30:52 +0200 Subject: [PATCH 01/10] initial draft --- proposals/4157-future-widget-api.md | 50 +++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/4157-future-widget-api.md diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md new file mode 100644 index 00000000000..051d1aaf2bb --- /dev/null +++ b/proposals/4157-future-widget-api.md @@ -0,0 +1,50 @@ +# Futures for the widget api + +With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Future events is introduced. Futures are events that are send **now** but will +be inserted into the dag (and distributed to all clients and federating servers) a time after **now** (based on timeout or delegation conditions). + +This is an extension to the client server api to expose Futures to widgets. +This can be useful for numerous widgets. It 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 + +We extend the send +`"send_event"` request: + +``` +{ + state_key?: string; + type: string; + content: unknown; + room_id?: string; + + timeout?: number; + group_id?: string; +} +``` + +and the `"send_event"` response: + +``` +{ + room_id: string; + event_id: string; + + group_id: string; + send_token: string; + cancel_token: string; + refresh_token: string; +} +``` + +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 field `timeout` or `group_id` of the widget action and send a `/send` or `/send_future` http request +if one of them is present. + +Additionally the response is extended with the tokens and the group_id. + +All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention +any of the details about futures. From 62a370da62a35bd4451461e41f0e61912f69b88d Mon Sep 17 00:00:00 2001 From: Timo Date: Wed, 3 Jul 2024 15:38:22 +0200 Subject: [PATCH 02/10] make response fields optional --- proposals/4157-future-widget-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 051d1aaf2bb..0304d27b085 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -31,12 +31,12 @@ and the `"send_event"` response: ``` { room_id: string; - event_id: string; + event_id?: string; - group_id: string; - send_token: string; - cancel_token: string; - refresh_token: string; + group_id?: string; + send_token?: string; + cancel_token?: string; + refresh_token?: string; } ``` From 9e21a304de9c969d859259f997cd2ddacd28483e Mon Sep 17 00:00:00 2001 From: Timo Date: Thu, 4 Jul 2024 16:57:07 +0200 Subject: [PATCH 03/10] rename to make it compatible with the http endpoints --- proposals/4157-future-widget-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 0304d27b085..210856ac74f 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -21,8 +21,8 @@ We extend the send content: unknown; room_id?: string; - timeout?: number; - group_id?: string; + future_timeout?: number; + future_group_id?: string; } ``` @@ -33,7 +33,7 @@ and the `"send_event"` response: room_id: string; event_id?: string; - group_id?: string; + future_group_id?: string; send_token?: string; cancel_token?: string; refresh_token?: string; @@ -41,10 +41,10 @@ and the `"send_event"` response: ``` 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 field `timeout` or `group_id` of the widget action and send a `/send` or `/send_future` http request +for the field `future_timeout` or `future_group_id` of the widget action and send a `/send` or `/send_future` http request if one of them is present. -Additionally the response is extended with the tokens and the group_id. +Additionally the response is extended with the tokens and the `future_group_id`. All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention any of the details about futures. From 4b83b1bec5b3a1baf8606887612190a6c32e4164 Mon Sep 17 00:00:00 2001 From: Andrew Ferrazzutti Date: Wed, 17 Jul 2024 14:12:38 -0400 Subject: [PATCH 04/10] Replace future_group_id with parent_future_id to match the latest version of MSC4140 --- proposals/4157-future-widget-api.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 210856ac74f..922e369730c 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -22,7 +22,7 @@ We extend the send room_id?: string; future_timeout?: number; - future_group_id?: string; + parent_future_id?: string; } ``` @@ -33,18 +33,15 @@ and the `"send_event"` response: room_id: string; event_id?: string; - future_group_id?: string; - send_token?: string; - cancel_token?: string; - refresh_token?: string; + parent_future_id?: string; } ``` 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 field `future_timeout` or `future_group_id` of the widget action and send a `/send` or `/send_future` http request +for the field `future_timeout` or `parent_future_id` of the widget action and send a `/send` or `/send_future` http request if one of them is present. -Additionally the response is extended with the tokens and the `future_group_id`. +Additionally the response is extended with the tokens and the `parent_future_id`. All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention any of the details about futures. From c1e4cdf739af2ec222d63a512d91dec037729457 Mon Sep 17 00:00:00 2001 From: Andrew Ferrazzutti Date: Wed, 17 Jul 2024 14:13:15 -0400 Subject: [PATCH 05/10] Mention new/edited fields from original spec --- proposals/4157-future-widget-api.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 922e369730c..08d33ae9a27 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -20,9 +20,8 @@ We extend the send type: string; content: unknown; room_id?: string; - - future_timeout?: number; - parent_future_id?: string; + future_timeout?: number; // new field + parent_future_id?: string; // new field } ``` @@ -31,9 +30,8 @@ and the `"send_event"` response: ``` { room_id: string; - event_id?: string; - - parent_future_id?: string; + event_id?: string; // now optional + parent_future_id?: string; // new field } ``` From eed0875eb1002ad4b792999ced5aec76a14c6165 Mon Sep 17 00:00:00 2001 From: Andrew Ferrazzutti Date: Wed, 17 Jul 2024 14:40:24 -0400 Subject: [PATCH 06/10] Link to MSC2762, which this MSC builds upon --- proposals/4157-future-widget-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 08d33ae9a27..8b33a69b7e2 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -11,8 +11,7 @@ Since ElementCall (EC) is a widget and based on MatrixRTC this widget api propos ## Proposal -We extend the send -`"send_event"` request: +We extend the `"send_event"` request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) as follows: ``` { From 5d2501664cd0d07dfb50c5e2498dd460830fbef8 Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 23 Jul 2024 11:59:03 +0200 Subject: [PATCH 07/10] add update future widget action --- proposals/4157-future-widget-api.md | 42 +++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 8b33a69b7e2..7c4d31b45d2 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -1,7 +1,8 @@ # Futures for the widget api -With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Future events is introduced. Futures are events that are send **now** but will -be inserted into the dag (and distributed to all clients and federating servers) a time after **now** (based on timeout or delegation conditions). +With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Future events is introduced. +Futures are events that are send **now** but will be inserted into the dag (and distributed to all clients and federating +servers) a time after **now** (based on timeout or delegation conditions). This is an extension to the client server api to expose Futures to widgets. This can be useful for numerous widgets. It is required for widgets implementing MatrixRTC. @@ -11,9 +12,12 @@ Since ElementCall (EC) is a widget and based on MatrixRTC this widget api propos ## Proposal -We extend the `"send_event"` request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) as follows: +### 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; @@ -26,7 +30,7 @@ We extend the `"send_event"` request defined by [MSC2762](https://github.com/mat and the `"send_event"` response: -``` +```jsonc { room_id: string; event_id?: string; // now optional @@ -34,11 +38,33 @@ and the `"send_event"` response: } ``` -to provide the same properties needed for [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140). The client is responsible to check +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 field `future_timeout` or `parent_future_id` of the widget action and send a `/send` or `/send_future` http request if one of them is present. Additionally the response is extended with the tokens and the `parent_future_id`. -All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention -any of the details about futures. +All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) +so here we intentionally don't mention any of the details about futures. + +### Sending `update_future` actions + +```jsonc +{ + "direction": "fromWidget", + "action":"update_future", + "data":{ + "future_id":, + "action":"cancel"|"send"|"refresh" + } +} +``` + +response + +```jsonc +{} +``` + +or an error response if an error occurred. \ No newline at end of file From 5bf978ee16331f6b0a9e7d88e7b5d5702b9b98f3 Mon Sep 17 00:00:00 2001 From: Timo Date: Wed, 24 Jul 2024 19:12:21 +0200 Subject: [PATCH 08/10] update to naming decisions --- proposals/4157-future-widget-api.md | 36 +++++++++++++++++------------ 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 7c4d31b45d2..4f1cb36c264 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -23,8 +23,7 @@ as follows: type: string; content: unknown; room_id?: string; - future_timeout?: number; // new field - parent_future_id?: string; // new field + delay?: number; // new field } ``` @@ -34,37 +33,44 @@ and the `"send_event"` response: { room_id: string; event_id?: string; // now optional - parent_future_id?: string; // new field + 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 field `future_timeout` or `parent_future_id` of the widget action and send a `/send` or `/send_future` http request -if one of them is present. - -Additionally the response is extended with the tokens and the `parent_future_id`. +for the field `delay` of the widget action and send the correct http request +if one of it is present. All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) so here we intentionally don't mention any of the details about futures. -### Sending `update_future` actions +### Sending `update_delayed_event` actions ```jsonc { "direction": "fromWidget", - "action":"update_future", + "action":"update_delayed_event", "data":{ - "future_id":, + "delay_id": string, "action":"cancel"|"send"|"refresh" } } ``` -response +The response is empty on success or otherwise a widget error response. -```jsonc -{} -``` +### 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. + +## Unstable prefix -or an error response if an error occurred. \ No newline at end of file +- `update_delayed_event` -> `org.matrix.msc4157.update_delayed_event` +- `m.send.delayed_event` -> `org.matrix.msc4157.send.delayed_event` +- `m.update_delayed_event` -> `org.matrix.msc4157.update.delayed_event` From 3f46cb5292a9b0f7ce29dfb3e6cd85cd99b89abb Mon Sep 17 00:00:00 2001 From: Timo Date: Wed, 31 Jul 2024 12:27:03 +0200 Subject: [PATCH 09/10] add alternative and more details --- proposals/4157-future-widget-api.md | 51 ++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 15 deletions(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index 4f1cb36c264..ada18650407 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -1,11 +1,17 @@ # Futures for the widget api -With [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) a way to send Future events is introduced. -Futures are events that are send **now** but will be inserted into the dag (and distributed to all clients and federating -servers) a time after **now** (based on timeout or delegation conditions). +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). -This is an extension to the client server api to expose Futures to widgets. -This can be useful for numerous widgets. It is required for widgets implementing MatrixRTC. +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. @@ -37,13 +43,9 @@ and the `"send_event"` response: } ``` -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 field `delay` of the widget action and send the correct http request -if one of it is present. - -All other details about the future concept can be found in [MSC4140](https://github.com/matrix-org/matrix-spec-proposals/pull/4140) -so here we intentionally don't mention any of the details about futures. +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 @@ -69,8 +71,27 @@ Two new capabilities will be introduces: - `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 -- `update_delayed_event` -> `org.matrix.msc4157.update_delayed_event` -- `m.send.delayed_event` -> `org.matrix.msc4157.send.delayed_event` -- `m.update_delayed_event` -> `org.matrix.msc4157.update.delayed_event` +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` From c3aa205a9ba43dc1ab1d7406e9b0490ceaf6e842 Mon Sep 17 00:00:00 2001 From: Timo Date: Thu, 1 Aug 2024 18:35:29 +0200 Subject: [PATCH 10/10] typo fix --- proposals/4157-future-widget-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4157-future-widget-api.md b/proposals/4157-future-widget-api.md index ada18650407..77d79238881 100644 --- a/proposals/4157-future-widget-api.md +++ b/proposals/4157-future-widget-api.md @@ -94,4 +94,4 @@ The following strings will have unstable prefixes: - 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` + `m.update_delayed_event` -> `org.matrix.msc4157.update_delayed_event`