Update everything to v1

and use proper msc number in unstable prefix section.
toger5/expiring-events-keep-alive
Timo 1 year ago
parent 99b3a20c32
commit eb50a1947a

@ -72,9 +72,9 @@ We call those delayed events `Futures`.
New endpoints are introduced:
`PUT /_matrix/client/v3/rooms/{roomId}/send_future/{eventType}/{txnId}?future_timeout={timeout_duration}&future_group_id={group_id}`
`PUT /_matrix/client/v1/rooms/{roomId}/send_future/{eventType}/{txnId}?future_timeout={timeout_duration}&future_group_id={group_id}`
`PUT /_matrix/client/v3/rooms/{roomId}/state_future/{eventType}/{stateKey}?future_timeout={timeout_duration}&future_group_id={group_id}`
`PUT /_matrix/client/v1/rooms/{roomId}/state_future/{eventType}/{stateKey}?future_timeout={timeout_duration}&future_group_id={group_id}`
Those behave like the normal `send`/`state` endpoints except that that they allow
to define `future_timeout` and `future_group_id` in their query parameters.
@ -140,7 +140,7 @@ The response will include a `send_token`, `cancel_token`, the associated `future
This MSC also proposes a `futures` endpoint.
The `token` can be used to call this public `futures` endpoint:
`POST /_matrix/client/v3/future/{token}`
`POST /_matrix/client/v1/future/{token}`
The information required to call this endpoint is minimal so that
no metadata is leaked when sharing the refresh/send url with a third party.
@ -160,13 +160,13 @@ The homeserver does the following when receiving a Future:
of retrieval and the `timeout_duration`.
- If `future_timeout` was present, it **Starts a timer** for the `refresh_token`.
- If a `POST /_matrix/client/v3/future/{refresh_token}` is received, it
- If a `POST /_matrix/client/v1/future/{refresh_token}` is received, it
**restarts the timer** with the stored `timeout_duration` for the associated timeout future.
- If a `POST /_matrix/client/v3/future/{send_token}` is received, it **sends the associated action or timeout future**
- If a `POST /_matrix/client/v1/future/{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 `POST /_matrix/client/v3/future/{cancel_token}` is received, it **does NOT send any future**
- If a `POST /_matrix/client/v1/future/{cancel_token}` is received, it **does NOT send any future**
and deletes/invalidates the associated stored future. This can mean that a whole future group gets deleted (see below).
- If a `POST /_matrix/client/v3/future/{unknown_token}` is received the server responds with a `410` (Gone).
- If a `POST /_matrix/client/v1/future/{unknown_token}` is received the server responds with a `410` (Gone).
An `unknown_token` either means that the service is making something up or that the service is using a
token that is invalidated by now.
- If a timer times out, **it sends the timeout future**.
@ -184,10 +184,10 @@ The homeserver does the following when receiving a Future:
So for each `future_group_id`, the homeserver will at most send one timeline event.
- No timeline event will be send in case all of the timeout futures in a future group are cancelled via `/_matrix/client/v3/future/{cancel_token}`.
- No timeline event will be send in case all of the timeout futures in a future group are cancelled via `/_matrix/client/v1/future/{cancel_token}`.
- Otherwise one of the timeout or action futures will be send.
**Rate limiting** the `POST /_matrix/client/v3/future/{token}`endpoint:
**Rate limiting** the `POST /_matrix/client/v1/future/{token}`endpoint:
- A malicious party can try to find a correct token by randomly sending requests to this endpoint.
- Homeservers should rate limit this endpoint so that one can at
@ -222,14 +222,14 @@ that proposes a future specific group sending endpoint in case this is required
### Getting running futures
Using `GET /_matrix/client/v3/future` it is possible to get the list of all running futures issues by the authenticated user.
Using `GET /_matrix/client/v1/future` it is possible to get the list of all running futures issues by the authenticated user.
This is an authenticated endpoint. It sends back the json
of the final event content with the associated tokens.
```json
[
{
"url":"/_matrix/client/v3/rooms/{roomId}/send_future/{eventType}/{txnId}?future_timeout={timeout_duration}&future_group_id={group_id}",
"url":"/_matrix/client/v1/rooms/{roomId}/send_future/{eventType}/{txnId}?future_timeout={timeout_duration}&future_group_id={group_id}",
"body":{
...event_body
},
@ -327,7 +327,7 @@ 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):
`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{eventType}/{txnId}`
`PUT /_matrix/client/v1/rooms/{roomId}/send/{eventType}/{eventType}/{txnId}`
```json
{
@ -336,7 +336,7 @@ is available):
```
then send:
`PUT /_matrix/client/v3/rooms/{roomId}/send_future/{eventType}/{txnId}?timeout={10*60}&future_group_id={XYZ}`
`PUT /_matrix/client/v1/rooms/{roomId}/send_future/{eventType}/{txnId}?timeout={10*60}&future_group_id={XYZ}`
```json
{
@ -410,7 +410,7 @@ The widget driver would then take care of calling `send` or `send_future` based
An alternative to the proposed solution that allows this kind of batch sending would be to
introduce this endpoint:
`PUT /_matrix/client/v3/rooms/{roomId}/send/future/{txnId}`
`PUT /_matrix/client/v1/rooms/{roomId}/send/future/{txnId}`
It allows to send a list of event contents. The body looks as following:
```json
@ -474,8 +474,8 @@ We do not need a `future_group_id` since we will send one group in one request.
Working with futures is the same with this alternative.
This means,
- `GET /_matrix/client/v3/future` getting running futures
- `POST /_matrix/client/v3/future/{token}` cancel, refreshing and sending futures
- `GET /_matrix/client/v1/future` getting running futures
- `POST /_matrix/client/v1/future/{token}` cancel, refreshing and sending futures
uses the exact same endpoints.
Also the behaviour of the homeserver on when to invalidate the furures is identical except, that
@ -494,7 +494,7 @@ For this reason, template variables are introduced that are only valid in `Futur
`send_on_timeout` this template variable can be used.
The **Self-destructing messages** example be a single request:
`PUT /_matrix/client/v3/rooms/{roomId}/send/future/{txnId}`
`PUT /_matrix/client/v1/rooms/{roomId}/send/future/{txnId}`
```json
{
@ -545,7 +545,7 @@ of the Futures. (The homeserver has them but they can always send events in your
as long as we do not have [MSC4080: Cryptographic Identities](https://github.com/matrix-org/matrix-spec-proposals/pull/4080))
It is an intentional decision to not provide an endpoint like
`PUT /_matrix/client/v3/future/room/{roomId}/event/{eventId}`
`PUT /_matrix/client/v1/future/room/{roomId}/event/{eventId}`
where any client with access to the room could also `end` or `refresh`
the expiration. With the token the client creating the future has ownership
over the expiration and only intentional delegation of that ownership
@ -557,7 +557,7 @@ even tell with which room or user it is interacting or what the token does (refr
## Unstable prefix
Use `io.element.msc3140.` instead of `m.` as long as the MSC is not stable.
For the endpoints introduced in this MSC use the prefix `/io.element.msc3140/` and set the paths version string to unstable, instead of v#.
Use `org.matrix.msc4140.` instead of `m.` as long as the MSC is not stable.
For the endpoints introduced in this MSC use the prefix `/org.matrix.msc4140/` and set the paths version string to unstable, instead of v#.
## Dependencies

Loading…
Cancel
Save