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.
The **`future_group_id`** is an identifier defined by the client.
The purpose of this identifier is to group multiple futures in one mutually exclusive group.
Only one of the events in such a group can ever reach the DAG/will be distributed by the homeserver.
All other events will be discarded.
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
as an mutually exclusive alternative to the event send with `timeout`.
We call these timeout futures and action futures.
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 `group_id`
to define `future_timeout` and `future_group_id` in their query parameters.
- `future_timeout: number | "none"` is a required parameter that defines how long the homeserver will wait before sending
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.
- If set to `"none"` the future will never expire and can only be send by the [external delegation endpoint](#delegating-futures).
We call such a future **action future**.
- If set to a `number` we call the future **timeout future**
- `future_group_id: string` is optional if a `future_timeout` is a `number`. The purpose of this identifier is to group
**multiple futures in one mutually exclusive group**.
- Only one of the events in such a group can ever reach the DAG/will be distributed by the homeserver.
All other futures will be discarded.
- 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.
@ -106,6 +119,7 @@ The response will include a `send_token` and a optional `refresh_token` but no `
// always present
"send_token": "token",
// optional if there is a timeout
"future_group_id": "group_id",
"refresh_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
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
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:
- It checks for the validity of the request (based on the `timeout` and the `group_id` query parameters)
and returns a `409` if necessary.
- It **generates** a `send_token` and optionally a `refresh_token`,`cancel_token` and stores them alongside the time
of retrieval, the `group_id` and the `timeout_duration`.
- If `timeout` was present, it **Starts a timer** for the `refresh_token`.
- It checks for the validity of the request (based on the `future_timeout` and the `future_group_id` query parameters)
and returns a `409`or `400`if necessary.
- 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 and the `timeout_duration`.
- 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
**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**
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**
@ -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
timer and tokens is canceled/deleted.
So for each `group_id` the client sends, the homeserver will send one 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.
So for each `future_group_id`, the homeserver will at most send one timeline event.
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
clients send a redact as a future or a room event with intentional mentions.
Timed messages, tea timers, reminders or ephemeral events could be implemented
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
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.
We do not include batch sending in 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))
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))
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
@ -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
"send_token": "token",
// optional if there is a timeout
"future_group_id": "group_id",
"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
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,
(like self-destructing messages) it is recommended to include
@ -221,7 +239,7 @@ and alternative expiration systems are evaluated.
#### 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:
- 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.
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!)
@ -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:
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