From c61790eb79903bc10662f7ef3092b3aa5b4d075f Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 13:30:52 +0100 Subject: [PATCH 01/28] MSC 2664: Get rooms in common with another user --- proposals/2664-get-rooms-in-common.md | 71 +++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 proposals/2664-get-rooms-in-common.md diff --git a/proposals/2664-get-rooms-in-common.md b/proposals/2664-get-rooms-in-common.md new file mode 100644 index 00000000000..0f2f20f6774 --- /dev/null +++ b/proposals/2664-get-rooms-in-common.md @@ -0,0 +1,71 @@ +# MSC 2664: Get rooms in common with another user + +It is useful to be able to fetch rooms you have in common with another user. Popular messaging services +such as Telegram offer users the ability to show "groups in common", which allows users to determine +what they have in common before participating in converstion. + +There are a variety of applications for this information. Some users may want to block invites from +users they do not share a room with at the client level, and need a way to poll the homeserver for +this information. Another use case would be trying to determine how a user came across your mxid, as +invites on their own do not present much context. With this endpoint, a client could tell you what +rooms you have in common before you accept an invite. + +While this information can be determined if the user has full access to member state for all rooms, +modern clients tend to implement "lazy-loaded" design patterns, so they often only have state for the +rooms the user has interacted with, or at least a subset of all rooms they are in. Therefore, the homeserver +should have a means to provide this information. + +This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. + +## Proposal + +Homeservers should implement a new endpoint `/users/{user_id}/shared_rooms/{other_user_id}` which will take +the current users mxid and the other users mxid, which the user is trying to search for. + +The response format will be an array containing all rooms where both the `user_id` and `other_user_id` have +a membership of type `join`. + +``` +GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.com +``` + +```json +[ + "!OGEhHVWSdvArJzumhm:matrix.org", + "!HYlSnuBHTxUPgyZPKC:half-shot.uk", + "!DueayyFpVTeVOQiYjR:example.com" +] +``` + +## Potential issues + +Homeserver performance OR storage may be impacted by this endpoint. While a homeserver already stores +membership information for each of it's users, the information may not be stored in a way that is quickly +accessible. Homeservers that have implemented [POST /user-directory/search](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-user-directory-search) +may have started some of this work, if they are limiting users to searching for users for which they +share rooms. While this is not a given by any means, it may mean that implementations of this API +and /search may be complimentary. + + +## Alternatives + +A client can already read all membership for all rooms, and thus determine which of those rooms contains +a "join" membership for the given user_id. However, this method is computationally expensive on the homeserver +and the client. Furthermore, it would increase total network traffic (which is important for low bandwith / mobile clients) +as well as include lots of extranious information. + + +## Security considerations + +The information provided in this endpoint is also accessible to day, if the client is in posession of all +state that the user can see. This endpoint only makes it possible to view this information without having +to request all state ahead of time. + + +## Unstable prefix + +The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. +The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2664`. +Once the MSC has been merged, clients should use `/_matrix/client/r0/users/{user_id}/shared_rooms/{other_user_id}` +and will no longer need to check for the `unstable_features` flag. + From 4264f32fe344174c8140348d4ffc999c76cafa31 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 13:32:48 +0100 Subject: [PATCH 02/28] correct MSC number --- ...{2664-get-rooms-in-common.md => 2666-get-rooms-in-common.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{2664-get-rooms-in-common.md => 2666-get-rooms-in-common.md} (98%) diff --git a/proposals/2664-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md similarity index 98% rename from proposals/2664-get-rooms-in-common.md rename to proposals/2666-get-rooms-in-common.md index 0f2f20f6774..9f973b132a2 100644 --- a/proposals/2664-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -1,4 +1,4 @@ -# MSC 2664: Get rooms in common with another user +# MSC 2666: Get rooms in common with another user It is useful to be able to fetch rooms you have in common with another user. Popular messaging services such as Telegram offer users the ability to show "groups in common", which allows users to determine From 008951f222665258e80560d93e6a40bf13ae017a Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 13:45:24 +0100 Subject: [PATCH 03/28] Try to clarify Proposal, update response format --- proposals/2666-get-rooms-in-common.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 9f973b132a2..b02573468f1 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -19,10 +19,10 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal -Homeservers should implement a new endpoint `/users/{user_id}/shared_rooms/{other_user_id}` which will take -the current users mxid and the other users mxid, which the user is trying to search for. +Homeservers should implement a new endpoint `/users/{current_user}/shared_rooms/{other_user_id}` which will take +the authenticated users MxID and the user that is being searched for. -The response format will be an array containing all rooms where both the `user_id` and `other_user_id` have +The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have a membership of type `join`. ``` @@ -30,11 +30,13 @@ GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.c ``` ```json -[ - "!OGEhHVWSdvArJzumhm:matrix.org", - "!HYlSnuBHTxUPgyZPKC:half-shot.uk", - "!DueayyFpVTeVOQiYjR:example.com" -] +{ + "rooms": [ + "!OGEhHVWSdvArJzumhm:matrix.org", + "!HYlSnuBHTxUPgyZPKC:half-shot.uk", + "!DueayyFpVTeVOQiYjR:example.com" + ] +} ``` ## Potential issues From 29f02edb2c8254f3e1d0ceb306ce79367de032d2 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 14:07:41 +0100 Subject: [PATCH 04/28] Update MSC number in prefix --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index b02573468f1..17f2d7a8df2 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -67,7 +67,7 @@ to request all state ahead of time. ## Unstable prefix The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. -The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2664`. +The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. Once the MSC has been merged, clients should use `/_matrix/client/r0/users/{user_id}/shared_rooms/{other_user_id}` and will no longer need to check for the `unstable_features` flag. From 2b75da81ee4ecd7716f0077a8c6258163b07bba1 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 15:57:56 +0100 Subject: [PATCH 05/28] Wording tidyup --- proposals/2666-get-rooms-in-common.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 17f2d7a8df2..040bdaebdcb 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -11,9 +11,8 @@ invites on their own do not present much context. With this endpoint, a client c rooms you have in common before you accept an invite. While this information can be determined if the user has full access to member state for all rooms, -modern clients tend to implement "lazy-loaded" design patterns, so they often only have state for the -rooms the user has interacted with, or at least a subset of all rooms they are in. Therefore, the homeserver -should have a means to provide this information. +modern clients often implement "lazy-loadeding", so they often only have state for a subset of all rooms +the user is in. Therefore, the homeserver should have a means to provide this information. This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. @@ -31,7 +30,7 @@ GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.c ```json { - "rooms": [ + "rooms": [ "!OGEhHVWSdvArJzumhm:matrix.org", "!HYlSnuBHTxUPgyZPKC:half-shot.uk", "!DueayyFpVTeVOQiYjR:example.com" @@ -41,8 +40,8 @@ GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.c ## Potential issues -Homeserver performance OR storage may be impacted by this endpoint. While a homeserver already stores -membership information for each of it's users, the information may not be stored in a way that is quickly +Homeserver performance and storage may be impacted by this endpoint. While a homeserver already stores +membership information for each of its users, the information may not be stored in a way that is readily accessible. Homeservers that have implemented [POST /user-directory/search](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-user-directory-search) may have started some of this work, if they are limiting users to searching for users for which they share rooms. While this is not a given by any means, it may mean that implementations of this API @@ -59,15 +58,14 @@ as well as include lots of extranious information. ## Security considerations -The information provided in this endpoint is also accessible to day, if the client is in posession of all -state that the user can see. This endpoint only makes it possible to view this information without having +The information provided in this endpoint is already accessible to the client, if the client has a copy of all +state that the user can see. This endpoint only makes it possible to get this information without having to request all state ahead of time. ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. -The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. +The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. +The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. Once the MSC has been merged, clients should use `/_matrix/client/r0/users/{user_id}/shared_rooms/{other_user_id}` and will no longer need to check for the `unstable_features` flag. - From 630af1c396be007d6312ef4f2fa5ed27c3f1bf51 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 15:58:32 +0100 Subject: [PATCH 06/28] more tidyup --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 040bdaebdcb..f4a2f0c60f2 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -58,7 +58,7 @@ as well as include lots of extranious information. ## Security considerations -The information provided in this endpoint is already accessible to the client, if the client has a copy of all +The information provided in this endpoint is already accessible to the client if it has a copy of all state that the user can see. This endpoint only makes it possible to get this information without having to request all state ahead of time. From d885bcf27b0e923ac89f6cac45d5d1079eda172e Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 16:00:28 +0100 Subject: [PATCH 07/28] Clarify empty responses --- proposals/2666-get-rooms-in-common.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index f4a2f0c60f2..f1e014d5ea5 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -22,7 +22,8 @@ Homeservers should implement a new endpoint `/users/{current_user}/shared_rooms/ the authenticated users MxID and the user that is being searched for. The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have -a membership of type `join`. +a membership of type `join`. If either user is not joined to any rooms, or the `other_user_id` does not exist, an +empty array should be returned. ``` GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.com From 52540768faf9ebd60ab108fbb3e769c4cd891722 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Sun, 5 Jul 2020 16:19:13 +0100 Subject: [PATCH 08/28] uhoreg fixes my spelling Co-authored-by: Hubert Chathi --- proposals/2666-get-rooms-in-common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index f1e014d5ea5..f8c209029a3 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -11,7 +11,7 @@ invites on their own do not present much context. With this endpoint, a client c rooms you have in common before you accept an invite. While this information can be determined if the user has full access to member state for all rooms, -modern clients often implement "lazy-loadeding", so they often only have state for a subset of all rooms +modern clients often implement "lazy-loading", so they often only have a subset of state for the rooms the user is in. Therefore, the homeserver should have a means to provide this information. This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. @@ -19,7 +19,7 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal Homeservers should implement a new endpoint `/users/{current_user}/shared_rooms/{other_user_id}` which will take -the authenticated users MxID and the user that is being searched for. +the authenticated user's MxID and the user that is being searched for. The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have a membership of type `join`. If either user is not joined to any rooms, or the `other_user_id` does not exist, an From 3f2faeffc74889b6fa985d288c101783dfe7a8da Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 6 Jul 2020 16:51:05 +0100 Subject: [PATCH 09/28] add same user case --- proposals/2666-get-rooms-in-common.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index f8c209029a3..2d032096bf5 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -23,7 +23,8 @@ the authenticated user's MxID and the user that is being searched for. The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have a membership of type `join`. If either user is not joined to any rooms, or the `other_user_id` does not exist, an -empty array should be returned. +empty array should be returned. If the `current_user` and `other_user_id` are the same, then the endpoint SHOULD +reject with HTTP 400. ``` GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.com From db99583ce577582f6bfe4b28d6ecfa7b1bf54590 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 10 Jul 2020 12:02:21 +0100 Subject: [PATCH 10/28] Update to use /uk.half-shot.msc2666/ --- proposals/2666-get-rooms-in-common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 2d032096bf5..00266beec9f 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -27,7 +27,7 @@ empty array should be returned. If the `current_user` and `other_user_id` are th reject with HTTP 400. ``` -GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.com +GET _matrix/client/unstable/uk.half-shot.msc2666/users/@alice:example.com/shared_rooms/@bob:example.com ``` ```json @@ -67,7 +67,7 @@ to request all state ahead of time. ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. +The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/users/{user_id}/shared_rooms/{other_user_id}`. The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. Once the MSC has been merged, clients should use `/_matrix/client/r0/users/{user_id}/shared_rooms/{other_user_id}` and will no longer need to check for the `unstable_features` flag. From 10a2df2069accb9c5d2f60595dbfed3b6f0dc8a1 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Jul 2020 23:30:42 +0100 Subject: [PATCH 11/28] Fixes --- proposals/2666-get-rooms-in-common.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index f1e014d5ea5..53140af28e5 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -18,7 +18,7 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal -Homeservers should implement a new endpoint `/users/{current_user}/shared_rooms/{other_user_id}` which will take +Homeservers should implement a new endpoint `/user/shared_rooms/{other_user_id}` which will take the authenticated users MxID and the user that is being searched for. The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have @@ -26,12 +26,12 @@ a membership of type `join`. If either user is not joined to any rooms, or the ` empty array should be returned. ``` -GET _matrix/client/unstable/users/@alice:example.com/shared_rooms/@bob:example.com +GET _matrix/client/r0/user/shared_rooms/@bob:example.com ``` ```json { - "rooms": [ + "joined": [ "!OGEhHVWSdvArJzumhm:matrix.org", "!HYlSnuBHTxUPgyZPKC:half-shot.uk", "!DueayyFpVTeVOQiYjR:example.com" @@ -66,7 +66,7 @@ to request all state ahead of time. ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/users/{user_id}/shared_rooms/{other_user_id}`. +The implementation MUST use `/_matrix/client/unstable/user/shared_rooms/{other_user_id}`. The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. -Once the MSC has been merged, clients should use `/_matrix/client/r0/users/{user_id}/shared_rooms/{other_user_id}` +Once the MSC has been merged, clients should use `/_matrix/client/r0/user/shared_rooms/{other_user_id}` and will no longer need to check for the `unstable_features` flag. From 4ac7ce85f30554fb27e49daad2f8fecd76d55ca7 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Jul 2020 23:41:05 +0100 Subject: [PATCH 12/28] remove referneces to user_id --- proposals/2666-get-rooms-in-common.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 3bca423a3b3..09c958fc8ec 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -18,13 +18,12 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal -Homeservers should implement a new endpoint `/user/shared_rooms/{other_user_id}` which will take +Homeservers should implement a new endpoint `/user/shared_rooms/{user_id}` which will take the authenticated user's MxID and the user that is being searched for. -The response format will be an array containing all rooms where both the `current_user` and `other_user_id` have -a membership of type `join`. If either user is not joined to any rooms, or the `other_user_id` does not exist, an -empty array should be returned. If the `current_user` and `other_user_id` are the same, then the endpoint SHOULD -reject with HTTP 400. +The response format will be an array containing all rooms where both the authenticated user and `user_id` have +a membership of type `join`. If the `user_id` does not exist, or does not share any rooms with the authenticated user, +an empty array should be returned. ``` GET _matrix/client/r0/user/shared_rooms/@bob:example.com @@ -68,7 +67,7 @@ to request all state ahead of time. ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/{other_user_id}`. +The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/{user_id}`. The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. -Once the MSC has been merged, clients should use `/_matrix/client/r0/user/shared_rooms/{other_user_id}` +Once the MSC has been merged, clients should use `/_matrix/client/r0/user/shared_rooms/{user_id}` and will no longer need to check for the `unstable_features` flag. From a4f5bae7149ffa171edfd6165dceaf1dd0600309 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Jul 2020 23:43:00 +0100 Subject: [PATCH 13/28] another reference to the auth user id --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 09c958fc8ec..80b8c20e4a0 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -19,7 +19,7 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal Homeservers should implement a new endpoint `/user/shared_rooms/{user_id}` which will take -the authenticated user's MxID and the user that is being searched for. +the MxID of the user who is being searched for. The response format will be an array containing all rooms where both the authenticated user and `user_id` have a membership of type `join`. If the `user_id` does not exist, or does not share any rooms with the authenticated user, From c45370474cf4b8428c3f9c3d1da9dc3f210f3593 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Mon, 20 Jul 2020 23:43:49 +0100 Subject: [PATCH 14/28] consistent newlines --- proposals/2666-get-rooms-in-common.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 80b8c20e4a0..681283f74f9 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -16,6 +16,7 @@ the user is in. Therefore, the homeserver should have a means to provide this in This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. + ## Proposal Homeservers should implement a new endpoint `/user/shared_rooms/{user_id}` which will take @@ -39,6 +40,7 @@ GET _matrix/client/r0/user/shared_rooms/@bob:example.com } ``` + ## Potential issues Homeserver performance and storage may be impacted by this endpoint. While a homeserver already stores @@ -58,6 +60,7 @@ all rooms. While a client *could* pull all membership for all rooms at the point it's computationally expensive for both the homeserver and the client, as well as a bandwidth waste for contrained clients. + ## Security considerations The information provided in this endpoint is already accessible to the client if it has a copy of all From cd173d5f3a441d075aacc9852b1b44b999f3ccba Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 18 Aug 2020 18:31:26 +0100 Subject: [PATCH 15/28] Add errcode --- proposals/2666-get-rooms-in-common.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 681283f74f9..e6ee6c2f318 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -40,6 +40,7 @@ GET _matrix/client/r0/user/shared_rooms/@bob:example.com } ``` +The response error for trying to get shared rooms with yourself will be an HTTP code 400, with `M_FORBIDDEN` as the `errcode`. ## Potential issues @@ -71,6 +72,7 @@ to request all state ahead of time. ## Unstable prefix The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/{user_id}`. -The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. +The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. +If the value is false or the key is not present, clients MUST assume the feature is not available. Once the MSC has been merged, clients should use `/_matrix/client/r0/user/shared_rooms/{user_id}` and will no longer need to check for the `unstable_features` flag. From 1a389f9644fac35f53ab15d063ae1324852fda9f Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 18 Aug 2020 18:31:33 +0100 Subject: [PATCH 16/28] Update proposals/2666-get-rooms-in-common.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index e6ee6c2f318..9fe14b30f87 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -27,7 +27,7 @@ a membership of type `join`. If the `user_id` does not exist, or does not share an empty array should be returned. ``` -GET _matrix/client/r0/user/shared_rooms/@bob:example.com +GET /_matrix/client/r0/user/shared_rooms/%40bob%3Aexample.com ``` ```json From fbbb2d95640457424a018d57df3b121d8a805665 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Sun, 9 Jan 2022 04:27:57 +0100 Subject: [PATCH 17/28] typo fix and shared_rooms -> mutual_rooms (#3631) --- proposals/2666-get-rooms-in-common.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 9fe14b30f87..7d21d44ef54 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -2,11 +2,11 @@ It is useful to be able to fetch rooms you have in common with another user. Popular messaging services such as Telegram offer users the ability to show "groups in common", which allows users to determine -what they have in common before participating in converstion. +what they have in common before participating in conversation. There are a variety of applications for this information. Some users may want to block invites from users they do not share a room with at the client level, and need a way to poll the homeserver for -this information. Another use case would be trying to determine how a user came across your mxid, as +this information. Another use case would be trying to determine how a user came across your MXID, as invites on their own do not present much context. With this endpoint, a client could tell you what rooms you have in common before you accept an invite. @@ -19,7 +19,7 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal -Homeservers should implement a new endpoint `/user/shared_rooms/{user_id}` which will take +Homeservers should implement a new endpoint `/user/mutual_rooms/{user_id}` which will take the MxID of the user who is being searched for. The response format will be an array containing all rooms where both the authenticated user and `user_id` have @@ -27,7 +27,7 @@ a membership of type `join`. If the `user_id` does not exist, or does not share an empty array should be returned. ``` -GET /_matrix/client/r0/user/shared_rooms/%40bob%3Aexample.com +GET /_matrix/client/r0/user/mutual_rooms/%40bob%3Aexample.com ``` ```json @@ -58,7 +58,7 @@ A client which holds full and current state can already see all membership for a determine which of those rooms contains a "join" membership for the given user_id. Clients which "lazy-load" however do not have this information, as they will have only synced a subset of the full membership for all rooms. While a client *could* pull all membership for all rooms at the point of needing this information, -it's computationally expensive for both the homeserver and the client, as well as a bandwidth waste for contrained +it's computationally expensive for both the homeserver and the client, as well as a bandwidth waste for constrained clients. @@ -71,8 +71,8 @@ to request all state ahead of time. ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/shared_rooms/{user_id}`. +The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms/{user_id}`. The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. If the value is false or the key is not present, clients MUST assume the feature is not available. -Once the MSC has been merged, clients should use `/_matrix/client/r0/user/shared_rooms/{user_id}` +Once the MSC has been merged, clients should use `/_matrix/client/r0/user/mutual_rooms/{user_id}` and will no longer need to check for the `unstable_features` flag. From 591d3e55c97c9d4d92144e62cbcd8f868a96578b Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Tue, 12 Apr 2022 10:42:33 +0100 Subject: [PATCH 18/28] Apply suggestions from code review Co-authored-by: Jonathan de Jong --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 7d21d44ef54..c66b35d9490 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -72,7 +72,7 @@ to request all state ahead of time. ## Unstable prefix The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms/{user_id}`. -The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666`. +The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666.mutual_rooms`. If the value is false or the key is not present, clients MUST assume the feature is not available. Once the MSC has been merged, clients should use `/_matrix/client/r0/user/mutual_rooms/{user_id}` and will no longer need to check for the `unstable_features` flag. From a1de65f178f9bffa17e28ba20fa2e32f565fb276 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Wed, 13 Apr 2022 11:14:56 +0200 Subject: [PATCH 19/28] @MSC2666: Add "may return 400" qualifier (#3770) Resolves [this comment](https://github.com/matrix-org/matrix-spec-proposals/pull/2666#discussion_r830500133) Rationale for `M_UNKNOWN`: There's not a "semantically more close" variant of that error, and i'm hesitant to add a new error. cc @Half-Shot --- proposals/2666-get-rooms-in-common.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index c66b35d9490..1ecc063238c 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -26,6 +26,9 @@ The response format will be an array containing all rooms where both the authent a membership of type `join`. If the `user_id` does not exist, or does not share any rooms with the authenticated user, an empty array should be returned. +Additionally, a server may respond with a `400` `M_UNKNOWN` to this endpoint for any reason, +signalling its unwillingess (or inability) to satisfy the request. + ``` GET /_matrix/client/r0/user/mutual_rooms/%40bob%3Aexample.com ``` From d59d05187aa24a55db40997e142020456b46bbb5 Mon Sep 17 00:00:00 2001 From: Will Hunt Date: Fri, 15 Apr 2022 20:45:25 +0100 Subject: [PATCH 20/28] Reject r0, embrace v1 Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/2666-get-rooms-in-common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 1ecc063238c..a00434b73dd 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -30,7 +30,7 @@ Additionally, a server may respond with a `400` `M_UNKNOWN` to this endpoint for signalling its unwillingess (or inability) to satisfy the request. ``` -GET /_matrix/client/r0/user/mutual_rooms/%40bob%3Aexample.com +GET /_matrix/client/v1/user/mutual_rooms/%40bob%3Aexample.com ``` ```json @@ -77,5 +77,5 @@ to request all state ahead of time. The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms/{user_id}`. The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666.mutual_rooms`. If the value is false or the key is not present, clients MUST assume the feature is not available. -Once the MSC has been merged, clients should use `/_matrix/client/r0/user/mutual_rooms/{user_id}` +Once the MSC has been merged, clients should use `/_matrix/client/v1/user/mutual_rooms/{user_id}` and will no longer need to check for the `unstable_features` flag. From 6a4e5238e394e185df04b4961451afb69362e793 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Tue, 31 May 2022 03:32:28 +0200 Subject: [PATCH 21/28] Remove M_UNKNOWN response (#3822) --- proposals/2666-get-rooms-in-common.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index a00434b73dd..20c8c1fcb8d 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -26,9 +26,6 @@ The response format will be an array containing all rooms where both the authent a membership of type `join`. If the `user_id` does not exist, or does not share any rooms with the authenticated user, an empty array should be returned. -Additionally, a server may respond with a `400` `M_UNKNOWN` to this endpoint for any reason, -signalling its unwillingess (or inability) to satisfy the request. - ``` GET /_matrix/client/v1/user/mutual_rooms/%40bob%3Aexample.com ``` From b946cc36523eadae54e80848b3c7d5fa438ca465 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 2 Aug 2022 16:40:08 +0100 Subject: [PATCH 22/28] Update an old link to the spec; fix endpoint text --- proposals/2666-get-rooms-in-common.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 20c8c1fcb8d..0adf88d1658 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -19,7 +19,7 @@ This proposal aims to implement a simple mechanism to fetch rooms you have in co ## Proposal -Homeservers should implement a new endpoint `/user/mutual_rooms/{user_id}` which will take +Homeservers should implement a new endpoint `/_matrix/client/v1/user/mutual_rooms/{user_id}` which will take the MxID of the user who is being searched for. The response format will be an array containing all rooms where both the authenticated user and `user_id` have @@ -46,7 +46,7 @@ The response error for trying to get shared rooms with yourself will be an HTTP Homeserver performance and storage may be impacted by this endpoint. While a homeserver already stores membership information for each of its users, the information may not be stored in a way that is readily -accessible. Homeservers that have implemented [POST /user-directory/search](https://matrix.org/docs/spec/client_server/r0.6.0#post-matrix-client-r0-user-directory-search) +accessible. Homeservers that have implemented [POST /user_directory/search](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3user_directorysearch) may have started some of this work, if they are limiting users to searching for users for which they share rooms. While this is not a given by any means, it may mean that implementations of this API and /search may be complimentary. From ea49670496b969e2c5bc9fcf1a037ebaa9dd1f7a Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Tue, 2 Aug 2022 16:42:09 +0100 Subject: [PATCH 23/28] provide a link to lazy-loading of room members spec --- proposals/2666-get-rooms-in-common.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 0adf88d1658..efb7b2cb7e9 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -11,8 +11,9 @@ invites on their own do not present much context. With this endpoint, a client c rooms you have in common before you accept an invite. While this information can be determined if the user has full access to member state for all rooms, -modern clients often implement "lazy-loading", so they often only have a subset of state for the rooms -the user is in. Therefore, the homeserver should have a means to provide this information. +modern clients often implement [lazy-loading of room members](https://spec.matrix.org/v1.3/client-server-api/#lazy-loading-room-members), +so they often only have a subset of state for the rooms the user is in. Therefore, the homeserver +should have a means to provide this information. This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. From 6f4f01b21529da5198314dc95d76f9988f190b53 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Tue, 31 Jan 2023 17:12:31 +0100 Subject: [PATCH 24/28] Apply review feedback (#3913) - convert to using query parameters - add pagination - add rate-limit-ness - add forward-compatibility considerations - alter unstable prefix and unstable_features - misc reflow of the markdown --- proposals/2666-get-rooms-in-common.md | 82 +++++++++++++++++++-------- 1 file changed, 59 insertions(+), 23 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index efb7b2cb7e9..2e95fd76c88 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -1,8 +1,8 @@ # MSC 2666: Get rooms in common with another user -It is useful to be able to fetch rooms you have in common with another user. Popular messaging services -such as Telegram offer users the ability to show "groups in common", which allows users to determine -what they have in common before participating in conversation. +It is useful to be able to fetch rooms you have in common with another user. Popular messaging +services such as Telegram offer users the ability to show "groups in common", which allows users to +determine what they have in common before participating in conversation. There are a variety of applications for this information. Some users may want to block invites from users they do not share a room with at the client level, and need a way to poll the homeserver for @@ -11,24 +11,29 @@ invites on their own do not present much context. With this endpoint, a client c rooms you have in common before you accept an invite. While this information can be determined if the user has full access to member state for all rooms, -modern clients often implement [lazy-loading of room members](https://spec.matrix.org/v1.3/client-server-api/#lazy-loading-room-members), +modern clients often implement +[lazy-loading of room members](https://spec.matrix.org/v1.3/client-server-api/#lazy-loading-room-members), so they often only have a subset of state for the rooms the user is in. Therefore, the homeserver should have a means to provide this information. -This proposal aims to implement a simple mechanism to fetch rooms you have in common with another user. - +This proposal aims to implement a simple mechanism to fetch rooms you have in common with another +user. ## Proposal -Homeservers should implement a new endpoint `/_matrix/client/v1/user/mutual_rooms/{user_id}` which will take -the MxID of the user who is being searched for. +Homeservers will implement a new endpoint `/_matrix/client/v1/user/mutual_rooms`. -The response format will be an array containing all rooms where both the authenticated user and `user_id` have -a membership of type `join`. If the `user_id` does not exist, or does not share any rooms with the authenticated user, -an empty array should be returned. +This endpoint will take a query parameter of `user_id` which will contain the MXID of the user +matched against. -``` -GET /_matrix/client/v1/user/mutual_rooms/%40bob%3Aexample.com +This endpoint can be rate limited. + +The response format will be an array containing all rooms where both the authenticated user and +`user_id` have a membership of type `join`. If the `user_id` does not exist, or does not share any +rooms with the authenticated user, an empty array should be returned. + +```http +GET /_matrix/client/v1/user/mutual_rooms/?user_id=%40bob%3Aexample.com ``` ```json @@ -41,18 +46,33 @@ GET /_matrix/client/v1/user/mutual_rooms/%40bob%3Aexample.com } ``` -The response error for trying to get shared rooms with yourself will be an HTTP code 400, with `M_FORBIDDEN` as the `errcode`. +The server may decide that the response to this endpoint is too large, and thus an optional key +`"next_batch_token"` can be inserted, which the client has to pass to `batch_token` in the query +parameters together with the original `user_id` to fetch the next batch of responses. This will +continue until the server does no longer insert `"next_batch_token"`. + +```json5 +{ + "joined": [ + // ... + ], + "next_batch_token": "" +} +``` + +The response error for trying to get shared rooms with yourself will be an HTTP code 422, with +`M_INVALID_PARAM` as the `errcode`. ## Potential issues -Homeserver performance and storage may be impacted by this endpoint. While a homeserver already stores -membership information for each of its users, the information may not be stored in a way that is readily -accessible. Homeservers that have implemented [POST /user_directory/search](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3user_directorysearch) +Homeserver performance and storage may be impacted by this endpoint. While a homeserver already +stores membership information for each of its users, the information may not be stored in a way that +is readily accessible. Homeservers that have implemented +[POST /user_directory/search](https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3user_directorysearch) may have started some of this work, if they are limiting users to searching for users for which they share rooms. While this is not a given by any means, it may mean that implementations of this API and /search may be complimentary. - ## Alternatives A client which holds full and current state can already see all membership for all rooms, and thus @@ -62,6 +82,15 @@ all rooms. While a client *could* pull all membership for all rooms at the point it's computationally expensive for both the homeserver and the client, as well as a bandwidth waste for constrained clients. +## Forward-compatibility considerations + +There possibly comes a time where it's desirable to query mutual rooms for more-than-one other user, +where multiple people (including the self-user) are matched against for which rooms all of them +share. + +Because of that, the endpoint accepts a query parameter, however, it will only accept *one* query +parameter for the time being. In the future this restriction can be lifted to accept multiple query +parameters under `user_id` ## Security considerations @@ -69,11 +98,18 @@ The information provided in this endpoint is already accessible to the client if state that the user can see. This endpoint only makes it possible to get this information without having to request all state ahead of time. - ## Unstable prefix -The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms/{user_id}`. -The /versions endpoint MUST include a new key in `unstable_features` with the name `uk.half-shot.msc2666.mutual_rooms`. +The implementation MUST use `/_matrix/client/unstable/uk.half-shot.msc2666/user/mutual_rooms`. + +The /versions endpoint MUST include a new key in `unstable_features` with the name +`uk.half-shot.msc2666.query_mutual_rooms`. + +Previous iterations of this MSC has used the following `unstable_features` key(s): +- `uk.half-shot.msc2666.mutual_rooms` + If the value is false or the key is not present, clients MUST assume the feature is not available. -Once the MSC has been merged, clients should use `/_matrix/client/v1/user/mutual_rooms/{user_id}` -and will no longer need to check for the `unstable_features` flag. + +Once the MSC has been merged, and the homeserver has advertised support for the Matrix version that +this endpoint is included in, clients should use `/_matrix/client/v1/user/mutual_rooms` and will no +longer need to check for the `unstable_features` flag. From 60ae94fbbe3d35d487bff0fe75a9e3a963a1f483 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Thu, 18 May 2023 18:03:22 +0200 Subject: [PATCH 25/28] Add invalid batch_token error code (#4017) --- proposals/2666-get-rooms-in-common.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 2e95fd76c88..c5c3aa8bbca 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -60,6 +60,9 @@ continue until the server does no longer insert `"next_batch_token"`. } ``` +The response error for when the given `batch_token` is invalid will be a response with HTTP code 400, +with `M_INVALID_PARAM` as `errcode`. + The response error for trying to get shared rooms with yourself will be an HTTP code 422, with `M_INVALID_PARAM` as the `errcode`. From 7829c3bf4a8f7b0602be7445eaea53fa422aa541 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Fri, 19 May 2023 10:40:10 +0100 Subject: [PATCH 26/28] Update proposals/2666-get-rooms-in-common.md Co-authored-by: Jonathan de Jong --- proposals/2666-get-rooms-in-common.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index c5c3aa8bbca..5844a430b09 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -110,6 +110,7 @@ The /versions endpoint MUST include a new key in `unstable_features` with the na Previous iterations of this MSC has used the following `unstable_features` key(s): - `uk.half-shot.msc2666.mutual_rooms` +- `uk.half-shot.msc2666` If the value is false or the key is not present, clients MUST assume the feature is not available. From 92aef5b242617d62aa5ae8b59de88ba9510ba34a Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Mon, 5 Jun 2023 11:33:39 +0100 Subject: [PATCH 27/28] restrict the allowed characters for the next_batch_token Co-authored-by: Jonathan de Jong --- proposals/2666-get-rooms-in-common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 5844a430b09..08ce12aad12 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -56,7 +56,7 @@ continue until the server does no longer insert `"next_batch_token"`. "joined": [ // ... ], - "next_batch_token": "" + "next_batch_token": "" } ``` From d58d0a1da0e89a25a8e4ddcf4d2c9e439b1b9bdd Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Thu, 13 Jul 2023 22:34:52 +0200 Subject: [PATCH 28/28] apply review feedback (#4035) --- proposals/2666-get-rooms-in-common.md | 30 ++++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/proposals/2666-get-rooms-in-common.md b/proposals/2666-get-rooms-in-common.md index 08ce12aad12..f63371d5017 100644 --- a/proposals/2666-get-rooms-in-common.md +++ b/proposals/2666-get-rooms-in-common.md @@ -26,14 +26,19 @@ Homeservers will implement a new endpoint `/_matrix/client/v1/user/mutual_rooms` This endpoint will take a query parameter of `user_id` which will contain the MXID of the user matched against. -This endpoint can be rate limited. +This endpoint can be rate limited and requires authentication. The response format will be an array containing all rooms where both the authenticated user and -`user_id` have a membership of type `join`. If the `user_id` does not exist, or does not share any -rooms with the authenticated user, an empty array should be returned. +`user_id` have a membership of type `join`. + +If the `user_id` does not exist, or does not share any rooms with the authenticated user, +an empty array should be returned. + +Handling invalid user IDs should result in an error, is likely implementation-specific, +and is beyond the scope of this proposal. ```http -GET /_matrix/client/v1/user/mutual_rooms/?user_id=%40bob%3Aexample.com +GET /_matrix/client/v1/user/mutual_rooms?user_id=%40bob%3Aexample.com ``` ```json @@ -47,24 +52,29 @@ GET /_matrix/client/v1/user/mutual_rooms/?user_id=%40bob%3Aexample.com ``` The server may decide that the response to this endpoint is too large, and thus an optional key -`"next_batch_token"` can be inserted, which the client has to pass to `batch_token` in the query +`"next_batch"` can be inserted, which the client has to pass to `from` in the query parameters together with the original `user_id` to fetch the next batch of responses. This will -continue until the server does no longer insert `"next_batch_token"`. +continue until the server does no longer insert `"next_batch"`. ```json5 { "joined": [ // ... ], - "next_batch_token": "" + "next_batch": "" } ``` -The response error for when the given `batch_token` is invalid will be a response with HTTP code 400, +The batch tokens this endpoint generates are only valid for this endpoint. + +The response error for when the given `from` batch token is invalid will be a response with HTTP code 400, with `M_INVALID_PARAM` as `errcode`. -The response error for trying to get shared rooms with yourself will be an HTTP code 422, with -`M_INVALID_PARAM` as the `errcode`. +The response error for trying to get shared rooms with yourself will be an HTTP code 400, with +`M_UNKNOWN` as the `errcode`. And the error description may be "you cannot request rooms in common with yourself". + +Tokens generated by this endpoint must be valid for at least 10 minutes, after which, tokens can expire. +Expired tokens must be handled similar to invalid tokens, as described above. ## Potential issues