Those behave like the normal `send`/`state` endpoints except that that they allow
Those behave like the normal `send`/`state` endpoints except that that they allow
to define a `timeout` and a `future_group_id` in their query parameters.
to define `future_timeout` and `future_group_id` in their query parameters.
The **`future_group_id`** is an identifier defined by the client.
- `future_timeout: number | "none"` is a required parameter that defines how long the homeserver will wait before sending
The purpose of this identifier is to group multiple futures in one mutually exclusive group.
the event into the room. Since the timeout can be refreshed and sending the future can be triggered via an endpoint (see: [Proposal/Delegating futures](#delegating-futures)) this value is not enough to predict the time this event will arrive in the room.
Only one of the events in such a group can ever reach the DAG/will be distributed by the homeserver.
- If set to `"none"` the future will never expire and can only be send by the [external delegation endpoint](#delegating-futures).
All other events will be discarded.
We call such a future **action future**.
One group can only contain one event with a `timeout` (timeout futures). The other events do not have a timeout (action futures) and are send
- If set to a `number` we call the future **timeout future**
as an mutually exclusive alternative to the event send with `timeout`.
- `future_group_id: string` is optional if a `future_timeout` is a `number`. The purpose of this identifier is to group
We call these timeout futures and action futures.
**multiple futures in one mutually exclusive group**.
The server will respond with a [`409`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409)
- Only one of the events in such a group can ever reach the DAG/will be distributed by the homeserver.
(`Conflict` This response is sent when a request conflicts with the current state of the server.) if
All other futures will be discarded.
the client tries to send an action future without there being a timeout future with the same `group_id`
- Every future group needs at least one timeout future to guarantee that all future expire eventually.
- If a timeout future is send without a `future_group_id` a unique identifier will be generated by the
homeserver and is part of the `send_future`response.
Possible error responses are all error responses that can occur when using the `send` and `state` endpoint accordingly and:
- The server will respond with a [`409`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409)
(`Conflict` This response is sent when a request conflicts with the current state of the server.) if
the client tries to send an action future without there being a timeout future with the same `future_group_id`
- The server can optionally configure a maximum `timeout_duration`
(In the order of one week dependent on how long they want to track futures)
The server will respond with a [`400`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400) (`Bad Request`, with a message
containing the maximum allowed `timeout_duration`) if the
client tries to send a timeout future with a larger `timeout_duration`.
The body is the same as sending a normal event.
The body is the same as sending a normal event.
@ -106,6 +119,7 @@ The response will include a `send_token` and a optional `refresh_token` but no `
// always present
// always present
"send_token": "token",
"send_token": "token",
// optional if there is a timeout
// optional if there is a timeout
"future_group_id": "group_id",
"refresh_token": "token",
"refresh_token": "token",
"cancel_token": "token"
"cancel_token": "token"
}
}
@ -125,18 +139,18 @@ This unauthenticated endpoint allows to delegate resolving the future.
An SFU for instance, that tracks the current client connection state, could get a url that it
An SFU for instance, that tracks the current client connection state, could get a url that it
needs to call every X hours while a user is connected and a url it has to call once the user disconnects.
needs to call every X hours while a user is connected and a url it has to call once the user disconnects.
This way the SFU can be used as the source of truth for the call member room state even if the client
This way the SFU can be used as the source of truth for the call member room state even if the client
gets closed or looses connection and without knowing anything about the matrix call.
gets closed or looses connection and without knowing anything about the Matrix call.
The homeserver does the following when receiving a Future:
The homeserver does the following when receiving a Future:
- It checks for the validity of the request (based on the `timeout` and the `group_id` query parameters)
- It checks for the validity of the request (based on the `future_timeout` and the `future_group_id` query parameters)
and returns a `409` if necessary.
and returns a `409`or `400`if necessary.
- It **generates** a `send_token` and optionally a `refresh_token`,`cancel_token` and stores them alongside the time
- It **generates** a `send_token` and optionally a `future_group_id`, a `refresh_token` and a`cancel_token` and stores them alongside the time
of retrieval, the `group_id` and the `timeout_duration`.
of retrieval and the `timeout_duration`.
- If `timeout` was present, it **Starts a timer** for the `refresh_token`.
- If `future_timeout` was present, it **Starts a timer** for the `refresh_token`.
- If a `PUT /_matrix/client/v3/futures/{refresh_token}` is received, it
- If a `PUT /_matrix/client/v3/futures/{refresh_token}` is received, it
**restarts the timer** with the stored timeout duration for the associated timeout future.
**restarts the timer** with the stored `timeout_duration` for the associated timeout future.
- If a `PUT /_matrix/client/v3/futures/{send_token}` is received, it **sends the associated action or timeout future**
- If a `PUT /_matrix/client/v3/futures/{send_token}` is received, it **sends the associated action or timeout future**
and deletes any stored futures with the `group_id` associated with that token.
and deletes any stored futures with the `group_id` associated with that token.
- If a `PUT /_matrix/client/v3/futures/{cancel_token}` is received, it **does NOT send any future**
- If a `PUT /_matrix/client/v3/futures/{cancel_token}` is received, it **does NOT send any future**
@ -154,14 +168,14 @@ The homeserver does the following when receiving a Future:
- After the homeservers sends a timeout future or action future, the associated
- After the homeservers sends a timeout future or action future, the associated
timer and tokens is canceled/deleted.
timer and tokens is canceled/deleted.
So for each `group_id` the client sends, the homeserver will send one event
So for each `future_group_id`, the homeserver will at most send one timeline event.
conditionally at an unknown time that can trigger logic on the client or
no event if the `/_matrix/client/v3/futures/{cancel_token}` was called.
This allows for any generic timeout logic.
- No timeline event will be send in case all of the timeout futures in a future group are cancelled via `/_matrix/client/v3/futures/{cancel_token}`.
- Otherwise one of the timeout or action future will be emitted.
Timed messages/reminders or ephemeral events could be implemented using this where
Timed messages, tea timers, reminders or ephemeral events could be implemented
clients send a redact as a future or a room event with intentional mentions.
using this where clients send room events with
intentional mentions or a redaction as a future.
In some scenarios it is important to allow to send an event with an associated
In some scenarios it is important to allow to send an event with an associated
future at the same time.
future at the same time.
@ -177,8 +191,11 @@ future at the same time.
For this usecase batch sending of multiple futures would be desired.
For this usecase batch sending of multiple futures would be desired.
We do not include batch sending in this MSC however since batch sending should
We do not include batch sending in the proposal of this MSC however since batch sending should
become a generic matrix concept as proposed with `/send_pdus`. (see: [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080))
become a generic Matrix concept as proposed with `/send_pdus`. (see: [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080))
There is a [batch sending version](#batch-sending-futures-with-custom-endpoint) in the Alternatives section
that proposes a future specific group sending endpoint in case this is required sooner then its realistic to implement [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080).
### Getting running futures
### Getting running futures
@ -189,7 +206,7 @@ of the final event content with the associated tokens.
@ -197,8 +214,9 @@ of the final event content with the associated tokens.
// always present
// always present
"send_token": "token",
"send_token": "token",
// optional if there is a timeout
// optional if there is a timeout
"future_group_id": "group_id",
"refresh_token": "token",
"refresh_token": "token",
"cancel_token": "token"
"cancel_token": "token",
}
}
},
},
]
]
@ -206,7 +224,7 @@ of the final event content with the associated tokens.
This can be used so clients can optionally display events
This can be used so clients can optionally display events
that will be send in the future.
that will be send in the future.
And to optionally cancel tokens for them.
And to acquire cancel_tokens for then.
For all usecases where the existence of a running future is also of interest for other room members,
For all usecases where the existence of a running future is also of interest for other room members,
(like self-destructing messages) it is recommended to include
(like self-destructing messages) it is recommended to include
@ -221,7 +239,7 @@ and alternative expiration systems are evaluated.
#### Background
#### Background
MatrixRTC makes it necessary to have real time information about the current matrixRTC session.
MatrixRTC makes it necessary to have real time information about the current MatrixRTC session.
To properly display room tiles and header in the room list (or compute a list of ongoing calls) need to know:
To properly display room tiles and header in the room list (or compute a list of ongoing calls) need to know:
- If there is a running session.
- If there is a running session.
@ -245,7 +263,7 @@ Example:
> A room list with 100 rooms where there has been a call before in every room (or there is an ongoing call) would require the client to send a to-device message (or a request to the SFU) to every user that has an active state event to check if they are still online. Just to display the room tile properly.
> A room list with 100 rooms where there has been a call before in every room (or there is an ongoing call) would require the client to send a to-device message (or a request to the SFU) to every user that has an active state event to check if they are still online. Just to display the room tile properly.
For displaying the room list timeout based approaches are much more reasonable because this allows computing matrixRTC metadata for a room to be synchronous.
For displaying the room list timeout based approaches are much more reasonable because this allows computing MatrixRTC metadata for a room to be synchronous.
The current solution updates the room state every X minutes. This is not elegant since we basically resend room state with the same content. In large calls this could result in huge traffic/large DAGs (100 call members implies 100 state events every X minutes.) X cannot be a long duration because it is the duration after which we can consider the event as expired. Improper disconnects would result in the user being displayed as "still in the call" for X minutes (we want this to be as short as possible!)
The current solution updates the room state every X minutes. This is not elegant since we basically resend room state with the same content. In large calls this could result in huge traffic/large DAGs (100 call members implies 100 state events every X minutes.) X cannot be a long duration because it is the duration after which we can consider the event as expired. Improper disconnects would result in the user being displayed as "still in the call" for X minutes (we want this to be as short as possible!)
@ -270,7 +288,7 @@ With this proposal we can provide an elegant solution using actions and timeouts
This MSC also allows to implement self-destructing messages:
This MSC also allows to implement self-destructing messages:
First send (or generate the pdu when [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080) is available):
First send (or generate the pdu when [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080) is available):
Timo
2 years ago