diff --git a/proposals/4140-delayed-events-futures.md b/proposals/4140-delayed-events-futures.md index 0d7d59580dd..62dfb925b39 100644 --- a/proposals/4140-delayed-events-futures.md +++ b/proposals/4140-delayed-events-futures.md @@ -14,6 +14,8 @@ time and then distributing it as normal via federation. - [Scheduling a delayed event](#scheduling-a-delayed-event) - [Managing delayed events](#managing-delayed-events) - [Getting delayed events](#getting-delayed-events) + - [On demand](#on-demand) + - [On push](#on-push) - [Homeserver implementation details](#homeserver-implementation-details) - [Power levels are evaluated at the point of sending](#power-levels-are-evaluated-at-the-point-of-sending) - [Delayed state events are cancelled by a more recent state event](#delayed-state-events-are-cancelled-by-a-more-recent-state-event) @@ -185,6 +187,8 @@ Where the `action` is `send`, the homeserver **should** apply rate limiting to p ### Getting delayed events +#### On demand + New authenticated client-server API endpoints `GET /_matrix/client/v1/delayed_events/scheduled` and `GET /_matrix/client/v1/delayed_events/finalised` allows clients to get a list of all the delayed events owned by the requesting user that have been scheduled to send, have been sent, or failed to be sent. @@ -276,6 +280,26 @@ This can be used by clients to display events that have been scheduled to be sen For use cases where the existence of a delayed event is also of interest for other room members (e.g. self-destructing messages), it is recommended to include this information in the original/affected event itself. +#### On push + +A new optional key, `finalised_events`, is added to the response body of `/sync`. The shape of its +value is equivalent to that of the response body of `GET /_matrix/client/v1/delayed_events/finalised`. +It is an array of the syncing user's delayed events that were sent or failed to be sent after the +`since` timestamp parameter of the associated `/sync` request, or all of them for full `/sync`s. +When no such delayed events exist, the `finalised_events` key is absent from the `/sync` response. + +A new key, `finalised_events`, is defined for `POST /_matrix/client/v3/user/{userId}/filter`. +Its value is a boolean which, if set to `false`, causes an associated `/sync` response to exclude +any `finalised_events` key it may have otherwise included. + +The only delayed events included in `finalised_events` are ones that have been retained by the homeserver, +as per the same retention policies as for the `GET /_matrix/client/v1/delayed_events/finalised` endpoint. +Additionally, a homeserver may discard finalised delayed events that have been returned by a `/sync` response. + +The `finalised_events` key is added to the request bodies of the appservice API `/transactions` endpoint. +It has the same content as the key for `/sync`, and contains all of the target appservice's delayed events +that were sent or failed to be sent since the previous transaction. + ### Homeserver implementation details #### Power levels are evaluated at the point of sending @@ -726,6 +750,8 @@ Whilst the MSC is in the proposal stage, the following should be used: the `POST /_matrix/client/v1/delayed_events/{delay_id}` endpoint. - `GET /_matrix/client/unstable/org.matrix.msc4140/delayed_events` should be used instead of the `GET /_matrix/client/v1/delayed_events` endpoint. +- `org.matrix.msc4140.finalised_events` should be used as keys of `/sync`, `/transactions`, and + `/filter` instead of `finalised_events`. - The `M_UNKNOWN` `errcode` should be used instead of `M_MAX_DELAY_EXCEEDED` as follows: ```json