From 1e12b45f97c05b35b6067254816bee5f212d0d79 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Wed, 1 Dec 2021 23:28:31 +0000 Subject: [PATCH] Clarifications to /sync description (#3534) * Clarify that E0 and E1 are not returned * Clarify that ASCII art diagram 2 refers to diagram 1 * Correct third ASCII art diagram To match the spacing in. Borked in the move to new docs format. https://github.com/matrix-org/matrix-doc/blob/55aed1d296bc9c2e9db558c23f6dd1ffade1abb3/specification/client_server_api.rst#L1610-L1615 * Make ASCII art 3 follow from ASCII art 2 * Explain how to fill the gap * Create 3543.clarification * Update content/client-server-api/_index.md Co-authored-by: Travis Ralston --- .../newsfragments/3543.clarification | 1 + content/client-server-api/_index.md | 34 ++++++++++++++----- 2 files changed, 27 insertions(+), 8 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3543.clarification diff --git a/changelogs/client_server/newsfragments/3543.clarification b/changelogs/client_server/newsfragments/3543.clarification new file mode 100644 index 00000000..ebe185dd --- /dev/null +++ b/changelogs/client_server/newsfragments/3543.clarification @@ -0,0 +1 @@ +Clarify the description of the `/sync` API, including a fix to an ASCII art diagram. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4ef14de6..c0456571 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1424,7 +1424,9 @@ for each room, a `prev_batch` field, which can be passed as a `start` parameter to the [`/rooms//messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API to retrieve earlier messages. -You can visualise the range of events being returned as: +For example, a `/sync` request might return a range of four events +`E2`, `E3`, `E4` and `E5` within a given room, omitting two prior events +`E0` and `E1`. This can be visualised as follows: ``` [E0]->[E1]->[E2]->[E3]->[E4]->[E5] @@ -1441,7 +1443,8 @@ the HTTP connection for a short period of time waiting for new events, returning early if an event occurs. Only the `/sync` API (and the deprecated `/events` API) support long-polling in this way. -The response for such an incremental sync can be visualised as: +Continuing the example above, an incremental sync might report +a single new event `E6`. The response can be visualised as: ``` [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6] @@ -1458,17 +1461,32 @@ containing only the most recent message events. A state "delta" is also returned, summarising any state changes in the omitted part of the timeline. The client may therefore end up with "gaps" in its knowledge of the message timeline. The client can fill these gaps using the -[`/rooms//messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API. This situation looks like this: +[`/rooms//messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) API. + +Continuing our example, suppose we make a third `/sync` request asking for +events since the last sync, by passing the `next_batch` token `x-y-z` as +the `since` parameter. The server knows about four new events, `E7`, `E8`, +`E9` and `E10`, but decides this is too many to report at once. Instead, +the server sends a `limited` response containing `E8`, `E9` and `E10`but +omitting `E7`. This forms a gap, which we can see in the visualisation: ``` - | gap | - | <-> | + | gap | + | <-> | [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10] - ^ ^ - | | - prev_batch: 'd-e-f' next_batch: 'u-v-w' + ^ ^ ^ + | | | + since: 'x-y-z' | | + prev_batch: 'd-e-f' next_batch: 'u-v-w' ``` +The limited response includes a state delta which describes how the state +of the room changes over the gap. This delta explains how to build the state +prior to returned timeline (i.e. at `E7`) from the state the client knows +(i.e. at `E6`). To close the gap, the client should make a request to +[`/rooms//messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) +with the query parameters `from=x-y-z` and `to=d-e-f`. + {{% boxes/warning %}} Events are ordered in this API according to the arrival time of the event on the homeserver. This can conflict with other APIs which order