From 805c0b2e34ff9e54153295845610e14a32b5183b Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 22 Jul 2022 09:48:19 -0400 Subject: [PATCH 01/14] Initial MSC3856 draft. --- proposals/3856-threads-list-api.md | 153 +++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 proposals/3856-threads-list-api.md diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md new file mode 100644 index 0000000000..659b15b60a --- /dev/null +++ b/proposals/3856-threads-list-api.md @@ -0,0 +1,153 @@ +# MSC3856: Threads List API + +An endpoint specific to listing the threads in a room is proposed to solve two +issues: + +1. Clients wish to display threads by the most recently active. +2. Clients wish to display a list of threads the user is interested in. + +It is currently difficult for clients to sort threads by the most recently +responded to. Clients use the `/messages` API with a filter of +`"related_by_rel_types": ["m.thread"]` to fetch the list of threads in a room. This +returns the root thread events in topological order of those events (either +forwards or backwards depending on the `dir` parameter). + +Each event also includes bundled aggregation, which will include the latest +event in each thread. + +In order to sort threads by the latest event in that thread clients must +paginate through all of the threads in the room, inspect the latest event from +the bundled aggregations and attempt to sort them. This can require many round +trips to the server and is wasteful for both the client and server. + +Additionally, even with all of the threads a client is not able to accurately +sort the threads since they lack the proper topological ordering of events. (The +closest they can get is by using `age` or `origin_server_ts`, but this is not +correct.) + +For the second problem, it is currently not possible for a client to query for +threads that the user has participated in (as defined in +[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format)). +A client could add the user's MXID to the filter, e.g. `"related_by_senders":["@alice:example.com"]`, +but this misses threads where the user sent the root message and has not yet replied. + +## Proposal + +### Client-Server endpoint + +A new endpoint is proposed to query for threads in a room. This endpoint requires +authentication and is subject to rate-limiting. This endpoint includes +[bundled aggregations](https://spec.matrix.org/v1.3/client-server-api/#aggregations) +in the response. + +The returned threads are ordered by the most recently updated thread. + +#### Request format + +``` +GET /_matrix/client/v1/rooms/{roomId}/threads +``` + +Query Parameters: + +* **`filter`**: `enum` + + Whether to include all threads in the room or only threads which the user has + participated in, meaning that the user has created the root event of the thread + or have created an event with a `m.thread` relation targeting the root. + + One of `[all participated]`. Defaults to `all`. + + XXX Rename this to something besides `filter`. +* **`from`**: `string` + + The token to start returning events from. This token can be obtained from a + `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from + an `end` token returned by a previous request to this endpoint. + + If it is not provided, the homeserver shall return a list of threads from the + last visible event in the room history for the requesting user. +* **`limit`**: Optional: a client-defined limit to the maximum + number of rooms to return per page. Must an integer greater than zero. + + Server implementations should impose a maximum value to avoid resource + exhaustion. +* **`to`**: `string` + + The token to stop returning events at. This token can be obtained from a + `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from + an `end` token returned by a previous request to this endpoint. + +#### Response format + +* **`chunk`**: [`[ClientEvent]`](https://spec.matrix.org/v1.3/client-server-api/#room-event-format) **Required** + + A list of room of events which are the root event of threads. Each event includes + bundled aggregations. The order is chronological by the latest event in that thread. +* **`end`**: `string` + + A token corresponding to the end of `chunk`. This token can be passed back to + this endpoint to request further events. + + If no further events are available (either because we have reached the start + of the timeline, or because the user does not have permission to see any more + events), this property is omitted from the response. +* **`start`**: `string` **Required** + + A token corresponding to the start of `chunk`. This will be the same as the + value given in `from`. + +XXX Define how ignored users are handled, which has two cases: + +1. If the ignored user sent the root thread event. +2. If the ignored user sent the latest thread event. + +#### Example request: + +``` +GET /_matrix/client/v1/rooms/%21ol19s%3Ableecker.street/threads? + limit=25& + filter=participated +``` + +#### Example response: + +```json +{ + "chunk": [ClientEvent], + "end": "...", + "start": "..." +} +``` + +### MSC3440 Filtering + +This MSC deprecates the [event filters added in MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room) +(`related_by_rel_types` and `related_by_senders`) as the only known use-case is +more efficiently solved by this MSC. + +## Potential issues + +None forseen. + +## Alternatives + +Additional parameters could be added to the `/messages` API to control the ordering +of the returned results. This would likely not be compatible with all the other +options available on that endpoint. + +Keeping this a separate API also gives the possibility of additional threads-specific +filtering in the future. + +## Security considerations + +As with other endpoints that accept a `limit`, homeservers should apply a hard +server-side maximum. + +## Unstable prefix + +The client-server API will be: `/_matrix/client/unstable/org.matrix.msc3856/rooms/{roomId}/threads` + +## Dependencies + +N/A From be44a1f6bb909becb8d07b4d174489bc246c64d8 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 27 Jul 2022 12:40:36 -0400 Subject: [PATCH 02/14] s/filter/include/g --- proposals/3856-threads-list-api.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 659b15b60a..b45d4cbbf7 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -50,15 +50,13 @@ GET /_matrix/client/v1/rooms/{roomId}/threads Query Parameters: -* **`filter`**: `enum` +* **`include`**: `enum` Whether to include all threads in the room or only threads which the user has participated in, meaning that the user has created the root event of the thread or have created an event with a `m.thread` relation targeting the root. One of `[all participated]`. Defaults to `all`. - - XXX Rename this to something besides `filter`. * **`from`**: `string` The token to start returning events from. This token can be obtained from a @@ -68,7 +66,7 @@ Query Parameters: If it is not provided, the homeserver shall return a list of threads from the last visible event in the room history for the requesting user. * **`limit`**: Optional: a client-defined limit to the maximum - number of rooms to return per page. Must an integer greater than zero. + number of rooms to return per page. Must be an integer greater than zero. Server implementations should impose a maximum value to avoid resource exhaustion. @@ -107,7 +105,7 @@ XXX Define how ignored users are handled, which has two cases: ``` GET /_matrix/client/v1/rooms/%21ol19s%3Ableecker.street/threads? limit=25& - filter=participated + include=participated ``` #### Example response: From 5af798d806cbbbe595632e5178dae7e25869a470 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 9 Aug 2022 15:37:37 -0400 Subject: [PATCH 03/14] Fix typo. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3856-threads-list-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index b45d4cbbf7..03fc933782 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -66,7 +66,7 @@ Query Parameters: If it is not provided, the homeserver shall return a list of threads from the last visible event in the room history for the requesting user. * **`limit`**: Optional: a client-defined limit to the maximum - number of rooms to return per page. Must be an integer greater than zero. + number of threads to return per page. Must be an integer greater than zero. Server implementations should impose a maximum value to avoid resource exhaustion. From 89a6146358a1ac0d563bbfb62b8af99227e4d7fa Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 08:41:19 -0400 Subject: [PATCH 04/14] Add link to the current spec. Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3856-threads-list-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 03fc933782..3f69136d85 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -7,7 +7,7 @@ issues: 2. Clients wish to display a list of threads the user is interested in. It is currently difficult for clients to sort threads by the most recently -responded to. Clients use the `/messages` API with a filter of +responded to. Clients can use the [`/messages`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3roomsroomidmessages) API with a filter of `"related_by_rel_types": ["m.thread"]` to fetch the list of threads in a room. This returns the root thread events in topological order of those events (either forwards or backwards depending on the `dir` parameter). From d51209a608757418168ad4b040547db3d2e6be11 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 08:43:26 -0400 Subject: [PATCH 05/14] Link to MSC3440 for related_by_rel_types. --- proposals/3856-threads-list-api.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 3f69136d85..be299573cd 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -7,10 +7,12 @@ issues: 2. Clients wish to display a list of threads the user is interested in. It is currently difficult for clients to sort threads by the most recently -responded to. Clients can use the [`/messages`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3roomsroomidmessages) API with a filter of -`"related_by_rel_types": ["m.thread"]` to fetch the list of threads in a room. This -returns the root thread events in topological order of those events (either -forwards or backwards depending on the `dir` parameter). +responded to. Clients can use the [`/messages`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3roomsroomidmessages) +API with a filter of `"related_by_rel_types": ["m.thread"]` (as defined in +[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room)) +to fetch the list of threads in a room. This returns the root thread events in +topological order of those events (either forwards or backwards depending on the +`dir` parameter). Each event also includes bundled aggregation, which will include the latest event in each thread. From 8ef8232fc4c07ab03e38b9e98c2ab07a0b368159 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 08:55:13 -0400 Subject: [PATCH 06/14] Rework and clarify intro. --- proposals/3856-threads-list-api.md | 35 +++++++++++++++++++----------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index be299573cd..abb53167ab 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -1,10 +1,10 @@ # MSC3856: Threads List API An endpoint specific to listing the threads in a room is proposed to solve two -issues: +client problems: -1. Clients wish to display threads by the most recently active. -2. Clients wish to display a list of threads the user is interested in. +1. Clients wish to display threads ordered by the most recently active. +2. Clients wish to display a list of threads the user has participated in. It is currently difficult for clients to sort threads by the most recently responded to. Clients can use the [`/messages`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3roomsroomidmessages) @@ -22,16 +22,25 @@ paginate through all of the threads in the room, inspect the latest event from the bundled aggregations and attempt to sort them. This can require many round trips to the server and is wasteful for both the client and server. -Additionally, even with all of the threads a client is not able to accurately -sort the threads since they lack the proper topological ordering of events. (The -closest they can get is by using `age` or `origin_server_ts`, but this is not -correct.) - -For the second problem, it is currently not possible for a client to query for -threads that the user has participated in (as defined in -[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format)). -A client could add the user's MXID to the filter, e.g. `"related_by_senders":["@alice:example.com"]`, -but this misses threads where the user sent the root message and has not yet replied. +Unfortunately even when a client has all the threads in a room is not able to accurately +sort the threads since the client lacks the proper topological ordering of events. (The +closest available information is the `age` or `origin_server_ts` of the events, but this +is not always correct.) + +Additionally, it is currently not possible for a client to query for threads that +the user has participated in, as defined in +[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format): + +> The user has participated if: +> +> * They created the current event. +> * They created an event with a m.thread relation targeting the current event. + +Currently, clients add the requesting user's MXID to the `related_by_senders` filter +(as defined in +[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room)), +e.g. `"related_by_senders":["@alice:example.com"]`, but this results in missing +threads where the user sent the root message and has not yet replied. ## Proposal From 75afe347d23c2358187a1966103516d29d5afa20 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 08:55:59 -0400 Subject: [PATCH 07/14] Clarify what is returned by the API. --- proposals/3856-threads-list-api.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index abb53167ab..e174c695c1 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -47,11 +47,15 @@ threads where the user sent the root message and has not yet replied. ### Client-Server endpoint A new endpoint is proposed to query for threads in a room. This endpoint requires -authentication and is subject to rate-limiting. This endpoint includes +authentication and is subject to rate-limiting. + +The endpoint returns events, which represent thread roots and includes [bundled aggregations](https://spec.matrix.org/v1.3/client-server-api/#aggregations) -in the response. +in the response (which includes the "latest event" of each thread, see +[MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#event-format) +for the format of bundled aggregations of threads). -The returned threads are ordered by the most recently updated thread. +The returned events are ordered by the latest event of each thread. #### Request format @@ -63,9 +67,10 @@ Query Parameters: * **`include`**: `enum` - Whether to include all threads in the room or only threads which the user has - participated in, meaning that the user has created the root event of the thread - or have created an event with a `m.thread` relation targeting the root. + Whether to include all thread roots in the room or only thread roots which the + user has participated in, meaning that the user has created the root event of + the thread or replied to the thread (they have created an event with a `m.thread` + relation targeting the root event). One of `[all participated]`. Defaults to `all`. * **`from`**: `string` @@ -74,8 +79,8 @@ Query Parameters: `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from an `end` token returned by a previous request to this endpoint. - If it is not provided, the homeserver shall return a list of threads from the - last visible event in the room history for the requesting user. + If it is not provided, the homeserver shall return a list of thread roots starting + from the last visible event in the room history for the requesting user. * **`limit`**: Optional: a client-defined limit to the maximum number of threads to return per page. Must be an integer greater than zero. From f23162df25af546da7c420e8b3d7448e4cf83306 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 08:59:33 -0400 Subject: [PATCH 08/14] Add a note on dir. --- proposals/3856-threads-list-api.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index e174c695c1..b8e43eefcb 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -158,6 +158,13 @@ filtering in the future. As with other endpoints that accept a `limit`, homeservers should apply a hard server-side maximum. +## Future extensions + +It does not seem useful to be able to paginate in reverse order, i.e. starting with +the thread which was least recently updated. If there becomes a future need of this +a `dir` parameter could be added which takes an enum value of `[f b]` defaulting to +`b` to maintain backwards compatibility with this proposal. + ## Unstable prefix The client-server API will be: `/_matrix/client/unstable/org.matrix.msc3856/rooms/{roomId}/threads` From dd11005295a82acf80ca69081e8e61142c5062ff Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Thu, 18 Aug 2022 09:14:43 -0400 Subject: [PATCH 09/14] Add info on ignored users. --- proposals/3856-threads-list-api.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index b8e43eefcb..fb9d3a6d7b 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -111,10 +111,18 @@ Query Parameters: A token corresponding to the start of `chunk`. This will be the same as the value given in `from`. -XXX Define how ignored users are handled, which has two cases: - -1. If the ignored user sent the root thread event. -2. If the ignored user sent the latest thread event. +If the sender of an event is ignored by the current user the results are modified +slightly. This has two situations: + +1. If the ignored user sent the root thread event: the server should return the + redacted form of the root event, but otherwise act as normal. This matches the + information that a client would have if the threads list was aggregated locally + (and generally matches the behavior if a thread root is unavailable, e.g. due + to room history visibility). +2. If the ignored user send the latest thread event: the server should treat the + latest event as not existing and replace it with the latest event from a + non-ignored user; with the caveat that the ordering of the threads is not + re-arranged due to this replacement. #### Example request: @@ -163,7 +171,7 @@ server-side maximum. It does not seem useful to be able to paginate in reverse order, i.e. starting with the thread which was least recently updated. If there becomes a future need of this a `dir` parameter could be added which takes an enum value of `[f b]` defaulting to -`b` to maintain backwards compatibility with this proposal. +`b` to maintain backwards compatibility with this proposal. ## Unstable prefix From a153ac0cf6a4164b51406b2ebad7012fc45878e9 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 6 Sep 2022 15:29:49 -0400 Subject: [PATCH 10/14] Clarifications from review. Co-authored-by: Travis Ralston --- proposals/3856-threads-list-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index fb9d3a6d7b..8d8a9fa273 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -80,7 +80,7 @@ Query Parameters: an `end` token returned by a previous request to this endpoint. If it is not provided, the homeserver shall return a list of thread roots starting - from the last visible event in the room history for the requesting user. + from the most recent visible event in the room history for the requesting user. * **`limit`**: Optional: a client-defined limit to the maximum number of threads to return per page. Must be an integer greater than zero. @@ -119,7 +119,7 @@ slightly. This has two situations: information that a client would have if the threads list was aggregated locally (and generally matches the behavior if a thread root is unavailable, e.g. due to room history visibility). -2. If the ignored user send the latest thread event: the server should treat the +2. If the ignored user sent the latest thread event: the server should treat the latest event as not existing and replace it with the latest event from a non-ignored user; with the caveat that the ordering of the threads is not re-arranged due to this replacement. @@ -144,7 +144,7 @@ GET /_matrix/client/v1/rooms/%21ol19s%3Ableecker.street/threads? ### MSC3440 Filtering -This MSC deprecates the [event filters added in MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room) +This MSC replaces the [event filters added in MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md#fetch-all-threads-in-a-room) (`related_by_rel_types` and `related_by_senders`) as the only known use-case is more efficiently solved by this MSC. From 6002d81ce86922f8f219ff8f7bba19d8cd14de6d Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 12 Sep 2022 13:54:21 -0400 Subject: [PATCH 11/14] Add notes about MSC2836. --- proposals/3856-threads-list-api.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 8d8a9fa273..05bfe8f985 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -154,12 +154,29 @@ None forseen. ## Alternatives -Additional parameters could be added to the `/messages` API to control the ordering -of the returned results. This would likely not be compatible with all the other -options available on that endpoint. +### Reusing the `/messages` endpoint -Keeping this a separate API also gives the possibility of additional threads-specific -filtering in the future. +Additional parameters could be added to the `/messages` endpoint to control the +ordering of the returned results. This would likely not be compatible with all +the other options available on that endpoint. + +Keeping this a separate endpoint also gives the possibility of additional +threads-specific filtering in the future. + +### MSC2836 Threading + +[MSC2836](https://github.com/matrix-org/matrix-spec-proposals/pull/2836) includes +a generic `/event_relationships` endpoint, but it is overly complex for +[MSC3440](https://github.com/matrix-org/matrix-doc/pull/3440)-style threads. + +MSC2836 attempts to solve a larger problem, including allowing for arbitrary +branching of threads (and many levels of event relations). MSC3440 forbids creating +threads off a threaded message, allowing for a simpler design. Additionally, the +MSC2836 design is more computensively intensive for both clients and servers to +implement due to the tree-like nature of the query. + +A benefit to the MSC2836 design is that it supports querying over federation for +additional events related to the event in question. ## Security considerations From baa6705241bad717ebf2aa538076bac1f1b69b38 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 16 Sep 2022 09:04:07 -0400 Subject: [PATCH 12/14] Add a comma to enum values. Co-authored-by: Erik Johnston --- proposals/3856-threads-list-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 05bfe8f985..2e5286eb49 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -72,7 +72,7 @@ Query Parameters: the thread or replied to the thread (they have created an event with a `m.thread` relation targeting the root event). - One of `[all participated]`. Defaults to `all`. + One of `[all, participated]`. Defaults to `all`. * **`from`**: `string` The token to start returning events from. This token can be obtained from a From 78ee0e0d297d1ed6d30568aa5ae90a036dcc8628 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 16 Sep 2022 09:10:09 -0400 Subject: [PATCH 13/14] Simplify pagination. --- proposals/3856-threads-list-api.md | 26 +++++++------------------- 1 file changed, 7 insertions(+), 19 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 2e5286eb49..4ef76a8434 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -75,9 +75,8 @@ Query Parameters: One of `[all, participated]`. Defaults to `all`. * **`from`**: `string` - The token to start returning events from. This token can be obtained from a - `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from - an `end` token returned by a previous request to this endpoint. + The token to start returning events from. This token can be obtained from an + `next_batch` token returned by a previous request to this endpoint. If it is not provided, the homeserver shall return a list of thread roots starting from the most recent visible event in the room history for the requesting user. @@ -86,11 +85,6 @@ Query Parameters: Server implementations should impose a maximum value to avoid resource exhaustion. -* **`to`**: `string` - - The token to stop returning events at. This token can be obtained from a - `prev_batch` or `next_batch` token returned by the `/sync` endpoint, or from - an `end` token returned by a previous request to this endpoint. #### Response format @@ -98,18 +92,13 @@ Query Parameters: A list of room of events which are the root event of threads. Each event includes bundled aggregations. The order is chronological by the latest event in that thread. -* **`end`**: `string` +* **`next_batch`**: `string` - A token corresponding to the end of `chunk`. This token can be passed back to - this endpoint to request further events. + A token which can be passed back to this endpoint to request additional events. If no further events are available (either because we have reached the start of the timeline, or because the user does not have permission to see any more events), this property is omitted from the response. -* **`start`**: `string` **Required** - - A token corresponding to the start of `chunk`. This will be the same as the - value given in `from`. If the sender of an event is ignored by the current user the results are modified slightly. This has two situations: @@ -137,8 +126,7 @@ GET /_matrix/client/v1/rooms/%21ol19s%3Ableecker.street/threads? ```json { "chunk": [ClientEvent], - "end": "...", - "start": "..." + "next_batch": "..." } ``` @@ -150,7 +138,7 @@ more efficiently solved by this MSC. ## Potential issues -None forseen. +None foreseen. ## Alternatives @@ -187,7 +175,7 @@ server-side maximum. It does not seem useful to be able to paginate in reverse order, i.e. starting with the thread which was least recently updated. If there becomes a future need of this -a `dir` parameter could be added which takes an enum value of `[f b]` defaulting to +a `dir` parameter could be added which takes an enum value of `[f, b]` defaulting to `b` to maintain backwards compatibility with this proposal. ## Unstable prefix From 9f67a7c01f71cf613851c8de8cbded2cbe112f29 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Mon, 19 Sep 2022 12:41:31 -0400 Subject: [PATCH 14/14] Fix typos. Co-authored-by: Alexey Rusakov --- proposals/3856-threads-list-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3856-threads-list-api.md b/proposals/3856-threads-list-api.md index 4ef76a8434..5f96aaa41b 100644 --- a/proposals/3856-threads-list-api.md +++ b/proposals/3856-threads-list-api.md @@ -22,7 +22,7 @@ paginate through all of the threads in the room, inspect the latest event from the bundled aggregations and attempt to sort them. This can require many round trips to the server and is wasteful for both the client and server. -Unfortunately even when a client has all the threads in a room is not able to accurately +Unfortunately even when a client has all the threads in a room it is not able to accurately sort the threads since the client lacks the proper topological ordering of events. (The closest available information is the `age` or `origin_server_ts` of the events, but this is not always correct.) @@ -160,7 +160,7 @@ a generic `/event_relationships` endpoint, but it is overly complex for MSC2836 attempts to solve a larger problem, including allowing for arbitrary branching of threads (and many levels of event relations). MSC3440 forbids creating threads off a threaded message, allowing for a simpler design. Additionally, the -MSC2836 design is more computensively intensive for both clients and servers to +MSC2836 design is more computationally intensive for both clients and servers to implement due to the tree-like nature of the query. A benefit to the MSC2836 design is that it supports querying over federation for