From 6f4f01b21529da5198314dc95d76f9988f190b53 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Tue, 31 Jan 2023 17:12:31 +0100 Subject: [PATCH] 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 efb7b2cb7..2e95fd76c 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.