From 6125ffc663c251b37fd4fc1daab389e6d6a0aed8 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 14 Dec 2021 11:41:24 -0500 Subject: [PATCH 1/4] Initial cut of MSC to standardize from being optiona on /messages requests. --- proposals/3567-optional-from-on-messages.md | 57 +++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 proposals/3567-optional-from-on-messages.md diff --git a/proposals/3567-optional-from-on-messages.md b/proposals/3567-optional-from-on-messages.md new file mode 100644 index 00000000000..fe798e6cde0 --- /dev/null +++ b/proposals/3567-optional-from-on-messages.md @@ -0,0 +1,57 @@ +# MSC3567: Allow requesting events from the start/end of the room history + +It can be useful to request the latest events in a room directly without calling +`/_matrix/client/v3/sync` first to fetch the room state. Some use-casse include: + +* Requesting events using a different filter after receiving a `/sync` response. +* A client which does not need to fully sync an account, but wishes to inspect a + specific room's history (perhaps for exporting or auditing). + + +## Proposal + +The `from` field on the [`/_matrix/client/v3/rooms/{roomId}/messages`](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages) +becomes optional. If it is not provided, the homeserver shall return a list of +messages from the start or end (per the value of the `dir` parameter) of the +room history. + +Note that Synapse already implements this, but it is not spec-compliant. It is +known to be used by Element Android [^1], and there are other cases involving +threads [^2], which shows real-world usage that this would be valuable. + + +## Potential issues + +None. + + +## Alternatives + +The alternative is today's status quo: a client must first make a request to +`/_matrix/client/v3/sync` and then follow-up that request with queries to +`/_matrix/client/v3/rooms/{roomId}/messages`. This is clunky if the client is +going to throw away most of the information received from the `/sync` request. + +The behavior also seems undefined if a different `filter` parameter is provided +for the call to `/sync` compared to the one used for `/messages`. + + +## Security considerations + +None. + + +## Unstable prefix + +Since this is modifying the endpoint to support not including a field, no unstable +prefix is necessary. + + +## Dependencies + +N/A + +[^1]: https://github.com/matrix-org/synapse/issues/5538 + +[^2]: In order to list all threads in a room without pulling the history locally +it uses `/messages` to push the filtering onto the homeserver. See https://github.com/matrix-org/matrix-js-sdk/pull/2065 From 074773bbef91c1499b45b286333a39641f450508 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 14 Dec 2021 12:00:50 -0500 Subject: [PATCH 2/4] Fix typo. Co-authored-by: Travis Ralston --- proposals/3567-optional-from-on-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3567-optional-from-on-messages.md b/proposals/3567-optional-from-on-messages.md index fe798e6cde0..d0508163811 100644 --- a/proposals/3567-optional-from-on-messages.md +++ b/proposals/3567-optional-from-on-messages.md @@ -1,7 +1,7 @@ # MSC3567: Allow requesting events from the start/end of the room history It can be useful to request the latest events in a room directly without calling -`/_matrix/client/v3/sync` first to fetch the room state. Some use-casse include: +`/_matrix/client/v3/sync` first to fetch the room state. Some use-cases include: * Requesting events using a different filter after receiving a `/sync` response. * A client which does not need to fully sync an account, but wishes to inspect a From af730c0e4566aa671b66d41d70d1c40d1fef4a3c Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 14 Dec 2021 12:45:42 -0500 Subject: [PATCH 3/4] Clarifications of start/end. --- proposals/3567-optional-from-on-messages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3567-optional-from-on-messages.md b/proposals/3567-optional-from-on-messages.md index d0508163811..60fd358751e 100644 --- a/proposals/3567-optional-from-on-messages.md +++ b/proposals/3567-optional-from-on-messages.md @@ -12,8 +12,8 @@ It can be useful to request the latest events in a room directly without calling The `from` field on the [`/_matrix/client/v3/rooms/{roomId}/messages`](https://spec.matrix.org/v1.1/client-server-api/#get_matrixclientv3roomsroomidmessages) becomes optional. If it is not provided, the homeserver shall return a list of -messages from the start or end (per the value of the `dir` parameter) of the -room history. +messages from the first or last (per the value of the `dir` parameter) visible +event in the room history for the requesting user. Note that Synapse already implements this, but it is not spec-compliant. It is known to be used by Element Android [^1], and there are other cases involving From c63cd31f44f2d2eb6043c59a0b5d6daaee2b04d6 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Fri, 17 Dec 2021 12:51:16 -0500 Subject: [PATCH 4/4] Add information about back-paginating excluded events. --- proposals/3567-optional-from-on-messages.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/proposals/3567-optional-from-on-messages.md b/proposals/3567-optional-from-on-messages.md index 60fd358751e..31b2d247502 100644 --- a/proposals/3567-optional-from-on-messages.md +++ b/proposals/3567-optional-from-on-messages.md @@ -16,8 +16,18 @@ messages from the first or last (per the value of the `dir` parameter) visible event in the room history for the requesting user. Note that Synapse already implements this, but it is not spec-compliant. It is -known to be used by Element Android [^1], and there are other cases involving -threads [^2], which shows real-world usage that this would be valuable. +known to be used by Element Android [^1] and Element Web, and there are other +use-cases involving threads [^2], which shows real-world usage that this would +be valuable. + +Ideally this would not be necessary and the `prev_batch` token received from +calling `/sync` could be provided as the pagination token to `/messages`, but this +will not work if you `/sync` with a filter that excludes a given class of event +(such as threaded replies), and all the events taking place in a room are of that +class. This will result in your `/sync` not returning an update for that room, +which means that your most recent `prev_batch` token precedes all the excluded +events. Trying to back-paginate from `prev_batch` using `/messages` will not +result in seeing the excluded events. ## Potential issues