From 97c3c039d9398217a2e01de4698c162f97041320 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 5 Sep 2019 22:06:12 -0600 Subject: [PATCH 01/29] What if we let people hide their read receipts? --- proposals/2285-hidden-read-receipts.md | 53 ++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 proposals/2285-hidden-read-receipts.md diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md new file mode 100644 index 00000000000..354361794b0 --- /dev/null +++ b/proposals/2285-hidden-read-receipts.md @@ -0,0 +1,53 @@ +# MSC2285: Hidden read receipts + +Currently users must send read receipts in order to affect their notification counts, which +alerts to other people that the user has read their message. For primarily privacy reasons, +it may be desirable to users to not advertise to others that they've read a message. + +## Proposal + +When sending a `m.read` receipt, a `m.hidden: true` flag can be included (optional) to tell +the server to not send it to anyone else. This allows the user to affect their notification +counts without advertising that they've read the message. `m.hidden` defaults to `false`. + +For example: +``` +POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read/$123 +{ + "m.hidden": true +} +``` + +The same applies to read markers (which allow you to update your read receipt): +``` +POST /_matrix/client/r0/rooms/!a:example.org/read_markers +{ + "m.fully_read": "$123", + "m.read": "$123", + "m.hidden": true +} +``` + +Note that fully read markers are not sent to other users and are local to the user sending them. +Therefore, no changes are required or implied by `m.hidden` for `m.fully_read` - just `m.read`. + +Servers processing read receipts MUST NOT send hidden receipts to any other user than the sender. +Servers MUST NOT send hidden receipts over federation to any server. + +## Tradeoffs + +Clients which support read receipts would end up rendering the user's receipt as jumping down +when they send a message. This is no different from how IRC and similarly bridged users are +perceived today. + +## Security considerations + +Servers could ignore the flag without telling the user. The user must already trust the homeserver +to a degree however, and the methods of notifying the user to the problem are difficult to +implement. Users can always run their own homeservers to ensure it behaves correctly. + +## Why not X kind of EDUs? + +In short: don't send those EDUs. Typing notifications, device messages, etc can all be mitigated +by simply not calling the endpoints. Read receipts have a side effect of causing stuck +notifications for users however, which is why they are solved here. From a4e5b45204b243b6b23226a0fcf5cf8a9b10cdc0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 25 May 2021 09:06:12 -0600 Subject: [PATCH 02/29] Add unstable prefix --- proposals/2285-hidden-read-receipts.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 354361794b0..7d1fc7de2b2 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -51,3 +51,12 @@ implement. Users can always run their own homeservers to ensure it behaves corre In short: don't send those EDUs. Typing notifications, device messages, etc can all be mitigated by simply not calling the endpoints. Read receipts have a side effect of causing stuck notifications for users however, which is why they are solved here. + +## Unstable prefix + +While this MSC is not considered stable, implementations should use `org.matrix.msc2285` as a namespace +for identifiers. `m.hidden` becomes `org.matrix.msc2885.hidden` for example. + +To detect server support, clients can either rely on the spec version (when stable) or the presence of +a `org.matrix.msc2285` flag in `unstable_features` on `/versions`. Clients are recommended to check for +server support to ensure they are not misleading the user about "hidden read receipts". From 40d2aa22b563a51c65969a9aab5b74a76623496f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 10 Aug 2021 11:29:03 -0600 Subject: [PATCH 03/29] Update proposals/2285-hidden-read-receipts.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 7d1fc7de2b2..133d396b9c4 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -55,7 +55,7 @@ notifications for users however, which is why they are solved here. ## Unstable prefix While this MSC is not considered stable, implementations should use `org.matrix.msc2285` as a namespace -for identifiers. `m.hidden` becomes `org.matrix.msc2885.hidden` for example. +for identifiers. `m.hidden` becomes `org.matrix.msc2285.hidden` for example. To detect server support, clients can either rely on the spec version (when stable) or the presence of a `org.matrix.msc2285` flag in `unstable_features` on `/versions`. Clients are recommended to check for From 4a77139249c2e830aec3c7d6bd5501a514d1cc27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Thu, 3 Mar 2022 22:54:35 +0100 Subject: [PATCH 04/29] Use a separate `receiptType` for hidden read receipts (#3750) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update the way MSC2285 works Signed-off-by: Šimon Brandner * Update proposals/2285-hidden-read-receipts.md Co-authored-by: Travis Ralston --- proposals/2285-hidden-read-receipts.md | 90 +++++++++++++++----------- 1 file changed, 54 insertions(+), 36 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 133d396b9c4..9657efb2e87 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -1,62 +1,80 @@ # MSC2285: Hidden read receipts -Currently users must send read receipts in order to affect their notification counts, which -alerts to other people that the user has read their message. For primarily privacy reasons, -it may be desirable to users to not advertise to others that they've read a message. +Currently users must send read receipts in order to affect their notification +counts, which alerts other people that the user has read their message. For +primarily privacy reasons, it may be desirable to users to not advertise to +others that they've read a message. ## Proposal -When sending a `m.read` receipt, a `m.hidden: true` flag can be included (optional) to tell -the server to not send it to anyone else. This allows the user to affect their notification -counts without advertising that they've read the message. `m.hidden` defaults to `false`. +This MSC proposes adding a new `receiptType` of `m.read.private`. This +`receiptType` is used when the user wants to affect their notification count but +doesn't want other users to see their read receipt. -For example: -``` -POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read/$123 -{ - "m.hidden": true -} -``` +To move the user's private read receipt to `$123` the client can make a POST +request such as this. -The same applies to read markers (which allow you to update your read receipt): +```HTTP +POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 +{} ``` + +To also move the user's `m.fully_read` marker and `m.read` receipt the client +can make a POST request such as this. + +```HTTP POST /_matrix/client/r0/rooms/!a:example.org/read_markers { "m.fully_read": "$123", "m.read": "$123", - "m.hidden": true + "m.read.private": "$123", } ``` -Note that fully read markers are not sent to other users and are local to the user sending them. -Therefore, no changes are required or implied by `m.hidden` for `m.fully_read` - just `m.read`. +It is assumed that if only an `m.read` receipt is received, the `m.read.private` +should also be moved. -Servers processing read receipts MUST NOT send hidden receipts to any other user than the sender. -Servers MUST NOT send hidden receipts over federation to any server. +The `m.read` is now optional as sometimes we only want to send `m.read.private`. -## Tradeoffs - -Clients which support read receipts would end up rendering the user's receipt as jumping down -when they send a message. This is no different from how IRC and similarly bridged users are -perceived today. +Servers MUST NOT send receipts of `receiptType` `m.read.private` to any other +user than the sender. Servers also MUST NOT send receipts of `receiptType` +`m.read.private` to any server over federation. ## Security considerations -Servers could ignore the flag without telling the user. The user must already trust the homeserver -to a degree however, and the methods of notifying the user to the problem are difficult to -implement. Users can always run their own homeservers to ensure it behaves correctly. +Servers could act as if `m.read.private` is the same as `m.read` so the user +must already trust the homeserver to a degree however, and the methods of +notifying the user to the problem are difficult to implement. Users can always +run their own homeservers to ensure it behaves correctly. + +## Potential issues + +Clients which support read receipts would end up rendering the user's receipt as +jumping down when they send a message. This is no different from how IRC and +similarly bridged users are perceived today. -## Why not X kind of EDUs? +## Alternatives -In short: don't send those EDUs. Typing notifications, device messages, etc can all be mitigated -by simply not calling the endpoints. Read receipts have a side effect of causing stuck -notifications for users however, which is why they are solved here. +It has been suggested to use account data to control this on a per-account +basis. While this might have some benefits, it is much less flexible and would +lead to us inventing a way to store per-account settings in account data which +should be handled in a separate MSC. + +Previous iterations of this MSC additionally suggested that having an `m.hidden` +flag on existing read receipts could work, however this feels like assigning too +much responsibility to an existing structure. ## Unstable prefix -While this MSC is not considered stable, implementations should use `org.matrix.msc2285` as a namespace -for identifiers. `m.hidden` becomes `org.matrix.msc2285.hidden` for example. +While this MSC is not considered stable, implementations should use +`org.matrix.msc2285` as a namespace. + +|Release |Development | +|----------------|---------------------------------| +|`m.read.private`|`org.matrix.msc2285.read.private`| -To detect server support, clients can either rely on the spec version (when stable) or the presence of -a `org.matrix.msc2285` flag in `unstable_features` on `/versions`. Clients are recommended to check for -server support to ensure they are not misleading the user about "hidden read receipts". +To detect server support, clients can either rely on the spec version (when +stable) or the presence of a `org.matrix.msc2285` flag in `unstable_features` +on `/versions`. Clients are recommended to check for server support to ensure +they are not misleading the user about their read receipts not being visible to +other users. From 94fdb2a5f1e5302be9cfccddde95b624dc378962 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 4 May 2022 18:13:19 +0200 Subject: [PATCH 05/29] Clarify notification behaviour and other things Co-authored-by: Patrick Cloke --- proposals/2285-hidden-read-receipts.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 9657efb2e87..c82b48c8187 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -31,8 +31,14 @@ POST /_matrix/client/r0/rooms/!a:example.org/read_markers } ``` -It is assumed that if only an `m.read` receipt is received, the `m.read.private` -should also be moved. +Both `m.read` and `m.read.private` clear notifications in the same way. If the +user sent two receipts into a room, the later one should be the one that decides +the notification count. + +If the user has `m.read` and `m.read.private` receipts at the same event, the +`m.read` receipt takes precedence - an `m.read.private` receipt sent to an event +that already has `m.read`, shouldn't move the user's receipt up in the timeline +from the perspective of other users. The `m.read` is now optional as sometimes we only want to send `m.read.private`. From 2cc2ed9335bf036e37978dfc0a64c6bfb9f9f3b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 4 May 2022 18:13:53 +0200 Subject: [PATCH 06/29] Mention adding `m.fully_read` to `/receipt` --- proposals/2285-hidden-read-receipts.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index c82b48c8187..0b317b3e88a 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -18,6 +18,7 @@ request such as this. POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 {} ``` +The MSC also proposes adding `m.fully_read` as a possible `receiptType` for `/receipt`. To also move the user's `m.fully_read` marker and `m.read` receipt the client can make a POST request such as this. From c895850e6886871e81d4d67c3345307ac2dafcf8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Thu, 5 May 2022 09:27:57 +0200 Subject: [PATCH 07/29] Rename MSC to `Private read receipts` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 0b317b3e88a..2e9157194f7 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -1,4 +1,4 @@ -# MSC2285: Hidden read receipts +# MSC2285: Private read receipts Currently users must send read receipts in order to affect their notification counts, which alerts other people that the user has read their message. For @@ -18,6 +18,7 @@ request such as this. POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 {} ``` + The MSC also proposes adding `m.fully_read` as a possible `receiptType` for `/receipt`. To also move the user's `m.fully_read` marker and `m.read` receipt the client From 84d18d0708fdf157b871db1808a1a7fa8c55135e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 15:55:10 +0200 Subject: [PATCH 08/29] Apply suggestions from review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 2e9157194f7..d242f5d7eeb 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -12,7 +12,7 @@ This MSC proposes adding a new `receiptType` of `m.read.private`. This doesn't want other users to see their read receipt. To move the user's private read receipt to `$123` the client can make a POST -request such as this. +request to the [`/receipt` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid). For example: ```HTTP POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 From 55e2060f3058b709e1f4d9b5e70d2bd45cea9baf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 15:55:39 +0200 Subject: [PATCH 09/29] Apply suggestions from review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index d242f5d7eeb..d8e25d941d4 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -21,8 +21,9 @@ POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 The MSC also proposes adding `m.fully_read` as a possible `receiptType` for `/receipt`. -To also move the user's `m.fully_read` marker and `m.read` receipt the client -can make a POST request such as this. +Alternatively, the client can move the user's `m.fully_read` marker and/or +`m.read` receipt at the same time as `m.read.private` by making a POST +request to the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers). For example: ```HTTP POST /_matrix/client/r0/rooms/!a:example.org/read_markers From de850aa10f6ed2d0c2bfbcbd458af711b2ef023c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 15:56:15 +0200 Subject: [PATCH 10/29] Remove trailing comma Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index d8e25d941d4..3a9896e5f78 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -30,7 +30,7 @@ POST /_matrix/client/r0/rooms/!a:example.org/read_markers { "m.fully_read": "$123", "m.read": "$123", - "m.read.private": "$123", + "m.read.private": "$123" } ``` From f551a775a494c15a4549368466ee863951fdedd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 15:58:53 +0200 Subject: [PATCH 11/29] Apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 3a9896e5f78..04f24d0194b 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -7,23 +7,29 @@ others that they've read a message. ## Proposal -This MSC proposes adding a new `receiptType` of `m.read.private`. This -`receiptType` is used when the user wants to affect their notification count but -doesn't want other users to see their read receipt. +This MSC proposes adding a new `receiptType` (see [the receipts +spec](https://spec.matrix.org/v1.3/client-server-api/#receipts)) of +`m.read.private`. This `receiptType` is used when the user wants to affect their +notification count but doesn't want other users to see their read receipt. To move the user's private read receipt to `$123` the client can make a POST -request to the [`/receipt` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid). For example: +request to the [`/receipt` +endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid). +For example: ```HTTP POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 {} ``` -The MSC also proposes adding `m.fully_read` as a possible `receiptType` for `/receipt`. +The MSC also proposes adding `m.fully_read` as a possible `receiptType` for +`/receipt`. -Alternatively, the client can move the user's `m.fully_read` marker and/or -`m.read` receipt at the same time as `m.read.private` by making a POST -request to the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers). For example: +Alternatively, the client can move the user's `m.fully_read` marker and/or +`m.read` receipt at the same time as `m.read.private` by making a POST request +to the [`/read_markers` +endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers). +For example: ```HTTP POST /_matrix/client/r0/rooms/!a:example.org/read_markers From 927b6222e668494d9c131dd054ba6b68d69a11ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 16:00:05 +0200 Subject: [PATCH 12/29] Apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 04f24d0194b..4f680c852a3 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -49,7 +49,9 @@ If the user has `m.read` and `m.read.private` receipts at the same event, the that already has `m.read`, shouldn't move the user's receipt up in the timeline from the perspective of other users. -The `m.read` is now optional as sometimes we only want to send `m.read.private`. +The `m.read` is now optional on the [`/read_markers` +endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers) +as sometimes we only want to send `m.read.private`. Servers MUST NOT send receipts of `receiptType` `m.read.private` to any other user than the sender. Servers also MUST NOT send receipts of `receiptType` From 18f49eb5f8f4fae0d5e3d2c5667a0d94ccaddede Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 28 Jun 2022 19:09:32 +0200 Subject: [PATCH 13/29] `r0` -> `v3` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 4f680c852a3..b3ff5b75422 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -18,7 +18,7 @@ endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roo For example: ```HTTP -POST /_matrix/client/r0/rooms/!a:example.org/receipt/m.read.private/$123 +POST /_matrix/client/v3/rooms/!a:example.org/receipt/m.read.private/$123 {} ``` From 904582f935dc4f24b3c1bd3ea2ad91417d950d96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 09:22:05 +0200 Subject: [PATCH 14/29] Describe how to determine server support while stable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index b3ff5b75422..69a46fcd063 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -86,12 +86,18 @@ much responsibility to an existing structure. While this MSC is not considered stable, implementations should use `org.matrix.msc2285` as a namespace. -|Release |Development | +|Stable |Unstable | |----------------|---------------------------------| |`m.read.private`|`org.matrix.msc2285.read.private`| -To detect server support, clients can either rely on the spec version (when -stable) or the presence of a `org.matrix.msc2285` flag in `unstable_features` -on `/versions`. Clients are recommended to check for server support to ensure -they are not misleading the user about their read receipts not being visible to -other users. +Clients are required to check for server support to ensure they are not +misleading the user about their read receipts not being visible to other users. + +While the MSC is considered unstable, to detect server support clients can rely +on the presence of the `org.matrix.msc2285` flag in `unstable_features` on +`/versions`. + +While this MSC is considered stable, to determine server support clients can +rely on the presence of the `org.matrix.msc2285.stable` flag in +`unstable_features` (while the MSC is not in a spec version) or on the presence +of a suitable spec version in `versions` on `/versions`. From 287c503b01e630fd8adb0ad19cfaadfdabc1ef4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 09:49:01 +0200 Subject: [PATCH 15/29] Be more precise about the failure mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 69a46fcd063..d0bfd419e3d 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -90,8 +90,8 @@ While this MSC is not considered stable, implementations should use |----------------|---------------------------------| |`m.read.private`|`org.matrix.msc2285.read.private`| -Clients are required to check for server support to ensure they are not -misleading the user about their read receipts not being visible to other users. +Clients are required to check for server support to ensure they are not sending +read receipts which are not clearing notifications. While the MSC is considered unstable, to detect server support clients can rely on the presence of the `org.matrix.msc2285` flag in `unstable_features` on From 37f1d5358a4808aafdef9f0b9c3d1765b7c96f66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 22:23:20 +0200 Subject: [PATCH 16/29] Improve wording Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index d0bfd419e3d..4b250114c88 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -49,7 +49,7 @@ If the user has `m.read` and `m.read.private` receipts at the same event, the that already has `m.read`, shouldn't move the user's receipt up in the timeline from the perspective of other users. -The `m.read` is now optional on the [`/read_markers` +The `m.read` property is now optional for the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers) as sometimes we only want to send `m.read.private`. From f5c2659565c5dab7c41a7ca7092833893c5740e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 22:23:43 +0200 Subject: [PATCH 17/29] Improve wording Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 4b250114c88..e5dac4909f1 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -93,8 +93,8 @@ While this MSC is not considered stable, implementations should use Clients are required to check for server support to ensure they are not sending read receipts which are not clearing notifications. -While the MSC is considered unstable, to detect server support clients can rely -on the presence of the `org.matrix.msc2285` flag in `unstable_features` on +While the MSC is considered unstable, to detect server support clients should +check for the presence of the `org.matrix.msc2285` flag in `unstable_features` on `/versions`. While this MSC is considered stable, to determine server support clients can From 887cc0a6df55bc3656f06c26658ba881d7668137 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 22:34:04 +0200 Subject: [PATCH 18/29] Improve wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index e5dac4909f1..648f91ee870 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -97,7 +97,7 @@ While the MSC is considered unstable, to detect server support clients should check for the presence of the `org.matrix.msc2285` flag in `unstable_features` on `/versions`. -While this MSC is considered stable, to determine server support clients can +Once this MSC is post-FCP, to determine server support clients should rely on the presence of the `org.matrix.msc2285.stable` flag in `unstable_features` (while the MSC is not in a spec version) or on the presence of a suitable spec version in `versions` on `/versions`. From e8ba93f879b95c112c4000c109ed08a411a69b9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Fri, 1 Jul 2022 22:35:53 +0200 Subject: [PATCH 19/29] Be more explicit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 648f91ee870..cbf20167756 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -86,9 +86,9 @@ much responsibility to an existing structure. While this MSC is not considered stable, implementations should use `org.matrix.msc2285` as a namespace. -|Stable |Unstable | -|----------------|---------------------------------| -|`m.read.private`|`org.matrix.msc2285.read.private`| +|Stable (post-FCP)|Unstable | +|-----------------|---------------------------------| +|`m.read.private` |`org.matrix.msc2285.read.private`| Clients are required to check for server support to ensure they are not sending read receipts which are not clearing notifications. From 9eedb2808b332705ab05b3009065bee506cf99dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Sat, 2 Jul 2022 10:03:26 +0200 Subject: [PATCH 20/29] Be more explicit around server support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 34 ++++++++++++++++++++------ 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index cbf20167756..60b1e8810d1 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -90,14 +90,34 @@ While this MSC is not considered stable, implementations should use |-----------------|---------------------------------| |`m.read.private` |`org.matrix.msc2285.read.private`| +## Detecting server support + Clients are required to check for server support to ensure they are not sending read receipts which are not clearing notifications. -While the MSC is considered unstable, to detect server support clients should -check for the presence of the `org.matrix.msc2285` flag in `unstable_features` on -`/versions`. +If a client has this feature enabled, it is recommended that, in the case of the +server not supporting the MSC, the client should either keep sending private +read receipts and risk notifications not clearing (if the server really does not +support the MSC) or it should warn the user and start sending public read +receipts. + +### While the MSC is unstable + +During this period, to detect server support clients should check for the +presence of the `org.matrix.msc2285` flag in `unstable_features` on `/versions`. +Clients are also required to use the unstable prefixes (see [unstable +prefix](#unstable-prefix)) during this time. + +### Once the MSC is merged but not in a spec version + +Once this MSC is merged, but is not yet part of the spec, clients should rely on +the presence of the `org.matrix.msc2285.stable` flag in `unstable_features` to +determine server support. If the flag is present, clients are required to use +stable prefixes (see [unstable prefix](#unstable-prefix)). + +### Once the MSC is in a spec version -Once this MSC is post-FCP, to determine server support clients should -rely on the presence of the `org.matrix.msc2285.stable` flag in -`unstable_features` (while the MSC is not in a spec version) or on the presence -of a suitable spec version in `versions` on `/versions`. +Once this MSC becomes a part of a spec version, clients should rely on the +presence of the spec version, that supports the MSC, in `versions` on +`/versions`, to determine support. Servers will also drop the +`org.matrix.msc2285.stable` flag once the MSC is part of a spec version. From 8b1b73a9ea17f130fd9c7f479f496e8e17526da0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Mon, 4 Jul 2022 19:14:49 +0200 Subject: [PATCH 21/29] Simplify text MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 60b1e8810d1..865fe2aac76 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -95,11 +95,10 @@ While this MSC is not considered stable, implementations should use Clients are required to check for server support to ensure they are not sending read receipts which are not clearing notifications. -If a client has this feature enabled, it is recommended that, in the case of the -server not supporting the MSC, the client should either keep sending private -read receipts and risk notifications not clearing (if the server really does not -support the MSC) or it should warn the user and start sending public read -receipts. +If a client has this feature enabled, in the case of the server not supporting +the MSC, the client should either keep sending private read receipts and risk +notifications not clearing or it should warn the user and start sending public +read receipts. ### While the MSC is unstable From 4ad1c109ebe14779e0745881452b0928fa96c8ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 12 Jul 2022 15:50:49 +0200 Subject: [PATCH 22/29] Be more explicit about detecting server support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 865fe2aac76..0dd730c70ab 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -96,9 +96,13 @@ Clients are required to check for server support to ensure they are not sending read receipts which are not clearing notifications. If a client has this feature enabled, in the case of the server not supporting -the MSC, the client should either keep sending private read receipts and risk -notifications not clearing or it should warn the user and start sending public -read receipts. +the MSC, the client should either keep sending private read receipts with the +knowledge that notifications will not be clearing or it should warn the user and +start sending public read receipts. + +**Once this MSC gets merged and once it becomes a part of a spec version, +clients should update their implementations as fast as possible to accommodate +the fact that the way of detecting server support will change.** ### While the MSC is unstable From 714695ca9b837c11e2ee2138d3347324ed096362 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Tue, 12 Jul 2022 16:38:23 +0200 Subject: [PATCH 23/29] Add note about consistency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 0dd730c70ab..770723b917b 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -23,7 +23,9 @@ POST /_matrix/client/v3/rooms/!a:example.org/receipt/m.read.private/$123 ``` The MSC also proposes adding `m.fully_read` as a possible `receiptType` for -`/receipt`. +`/receipt` to make this endpoint consistent with `/read_markers`. (we have two +endpoints that do essentially the same thing, so it would make sense for them to +be consistent) Alternatively, the client can move the user's `m.fully_read` marker and/or `m.read` receipt at the same time as `m.read.private` by making a POST request From aa41d8478ee3ce7fe008977408eefa4e25123c44 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Jul 2022 12:30:31 -0600 Subject: [PATCH 24/29] Clarify how exactly to detect support --- proposals/2285-hidden-read-receipts.md | 40 ++++++++++++++++---------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 770723b917b..4a2aa00cc92 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -92,19 +92,26 @@ While this MSC is not considered stable, implementations should use |-----------------|---------------------------------| |`m.read.private` |`org.matrix.msc2285.read.private`| -## Detecting server support - -Clients are required to check for server support to ensure they are not sending -read receipts which are not clearing notifications. - -If a client has this feature enabled, in the case of the server not supporting -the MSC, the client should either keep sending private read receipts with the -knowledge that notifications will not be clearing or it should warn the user and -start sending public read receipts. - -**Once this MSC gets merged and once it becomes a part of a spec version, -clients should update their implementations as fast as possible to accommodate -the fact that the way of detecting server support will change.** +Clients should check for server support before sending private read receipts: +if the server does not support them, then a private read receipt will not clear +any notifications for the user. + +The presence of `org.matrix.msc2285` or `org.matrix.msc2285.stable` in +`unstable_features` is a reliable indication that a server supports private read +receipts; however the converse is not true: their absence does not necessarily +mean that the server does *not* support private read receipts. In particular, +the server may have been updated to a future spec version which includes +private read receipts, and hence removed the `unstable_features` entry. + +Therefore, if a client has this feature enabled, but the server does not advertise +support for this MSC in `unstable_features`, the client should either keep sending +private read receipts with the risk that notifications will not be clearing, or it +should warn the user and start sending public read receipts instead. + +To mitigate this problem, once this MSC gets merged and once it becomes a part of a +spec version, clients should update their implementations as fast as possible to +accommodate the fact that the way of detecting server support will change: clients +will now be looking for that spec version in `/versions`. ### While the MSC is unstable @@ -124,5 +131,8 @@ stable prefixes (see [unstable prefix](#unstable-prefix)). Once this MSC becomes a part of a spec version, clients should rely on the presence of the spec version, that supports the MSC, in `versions` on -`/versions`, to determine support. Servers will also drop the -`org.matrix.msc2285.stable` flag once the MSC is part of a spec version. +`/versions`, to determine support. Servers are encouraged to keep the +`org.matrix.msc2285.stable` flag around for a reasonable amount of time +to help smooth over the transition for clients. "Reasonable" is intentionally +left as an implementation detail, however the MSC process currently recommends +*at most* 2 months from the date of spec release. From 5c891d036307f91c9fdd1d701c65e4070b14c5af Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 12 Jul 2022 12:53:41 -0600 Subject: [PATCH 25/29] Try to fix clarity around precedence --- proposals/2285-hidden-read-receipts.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 4a2aa00cc92..a7c402ce0ab 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -46,10 +46,23 @@ Both `m.read` and `m.read.private` clear notifications in the same way. If the user sent two receipts into a room, the later one should be the one that decides the notification count. -If the user has `m.read` and `m.read.private` receipts at the same event, the -`m.read` receipt takes precedence - an `m.read.private` receipt sent to an event -that already has `m.read`, shouldn't move the user's receipt up in the timeline -from the perspective of other users. +The receipt that is more "ahead" of the other takes precedence when considering +notifications and a client's rendering of read receipts. This means that given +an ordered set of events A, B, C, and D the public read receipt could be at +point C, private at point A. If the user moves the private receipt from A to B +then the user's notification count is still considered from point C as the public +receipt is further ahead, still. Other users would also see the user's public read +receipt as not having moved. The user can then move the private read receipt +to point D, hopping over the public receipt, to change their notification count. + +For clarity, if the public receipt is "fast forwarded" to be at the same position +as the private receipt then the public receipt is broadcast to other users, even +if previously considered private. + +Note that like regular read receipts today, neither receipt can cause a backwards +movement: both receipts can only move forwards, but do not have to be ahead of +each other. It's valid to, for example, update a public read receipt which lags +20 messages behind the private one. The `m.read` property is now optional for the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers) From 252474a9de985efd2ca9b1dac74879a685b46ee8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 13 Jul 2022 17:54:05 +0200 Subject: [PATCH 26/29] Be clearer about alternatives MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 770723b917b..1079888a37f 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -74,10 +74,9 @@ similarly bridged users are perceived today. ## Alternatives -It has been suggested to use account data to control this on a per-account -basis. While this might have some benefits, it is much less flexible and would -lead to us inventing a way to store per-account settings in account data which -should be handled in a separate MSC. +It has been suggested to use account data to store the setting that controls +whether read receipts should be private on a per-account/per-room basis. While +this might have some benefits, it is much less flexible. Previous iterations of this MSC additionally suggested that having an `m.hidden` flag on existing read receipts could work, however this feels like assigning too From 33ba33c20de2f2a8cc98f3ee174d4c20aad92c63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 13 Jul 2022 18:04:49 +0200 Subject: [PATCH 27/29] Add sentence about `/receipt` federation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 1079888a37f..867d8cb5e1e 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -55,9 +55,10 @@ The `m.read` property is now optional for the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers) as sometimes we only want to send `m.read.private`. -Servers MUST NOT send receipts of `receiptType` `m.read.private` to any other -user than the sender. Servers also MUST NOT send receipts of `receiptType` -`m.read.private` to any server over federation. +The MSC proposes that from now on, not all things sent over `/receipt` are +federated. Servers MUST NOT send receipts of `receiptType` `m.read.private` to +any other user than the sender. Servers also MUST NOT send receipts of +`receiptType` `m.read.private` to any server over federation. ## Security considerations From 23f4a2ab7ccd74abef289575a2f5d1ea44dc607d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Wed, 13 Jul 2022 19:59:32 +0200 Subject: [PATCH 28/29] Be more explicit about adding `m.read.private` to `/receipt` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Šimon Brandner --- proposals/2285-hidden-read-receipts.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 1423400d480..7825610e023 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -22,10 +22,10 @@ POST /_matrix/client/v3/rooms/!a:example.org/receipt/m.read.private/$123 {} ``` -The MSC also proposes adding `m.fully_read` as a possible `receiptType` for -`/receipt` to make this endpoint consistent with `/read_markers`. (we have two -endpoints that do essentially the same thing, so it would make sense for them to -be consistent) +The MSC also proposes adding `m.fully_read` and `m.read.private` as a possible +`receiptType` for `/receipt` to make this endpoint consistent with +`/read_markers`. (we have two endpoints that do essentially the same thing, so +it would make sense for them to be consistent) Alternatively, the client can move the user's `m.fully_read` marker and/or `m.read` receipt at the same time as `m.read.private` by making a POST request From 839c1982d17aafbcc6a76fb86cf7960055d5f5c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0imon=20Brandner?= Date: Sat, 16 Jul 2022 14:10:55 +0200 Subject: [PATCH 29/29] Fix wrong RR type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> --- proposals/2285-hidden-read-receipts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2285-hidden-read-receipts.md b/proposals/2285-hidden-read-receipts.md index 7825610e023..7c3ed9eeb83 100644 --- a/proposals/2285-hidden-read-receipts.md +++ b/proposals/2285-hidden-read-receipts.md @@ -64,7 +64,7 @@ movement: both receipts can only move forwards, but do not have to be ahead of each other. It's valid to, for example, update a public read receipt which lags 20 messages behind the private one. -The `m.read` property is now optional for the [`/read_markers` +The `m.fully_read` property is now optional for the [`/read_markers` endpoint](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3roomsroomidread_markers) as sometimes we only want to send `m.read.private`.