wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Revert "Merge branch 'travis/msc/1337-joined-rooms'"

Browse source 
This reverts commit 0961c7b0f7.
This commit is contained in:
Travis Ralston 2020-12-07 14:31:26 -07:00
parent e659572183
commit 6ccc548912
1 changed files with 0 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

155
proposals/1337-improve-membership.md
View file

@ -1,155 +0,0 @@
# Improving the way membership lists are queried
## Problem scope
A common operation for bots, bridges, scripts, and clients is to determine what rooms the user is a
member of and who the members of those rooms are. Although possible with the current specification,
the API can be improved to provide more granular and simplified access to this information.
The affected routes are:
* `GET /_matrix/client/r0/rooms/{roomId}/members`
* `GET /_matrix/client/r0/rooms/{roomId}/joined_members`
* `GET /_matrix/client/r0/joined_rooms`
This proposal aims to resolve [matrix-doc#1123](https://github.com/matrix-org/matrix-doc/issues/1123).
## Background
The `/joined_members` and `/joined_rooms` endpoints were originally added in [synapse#1680](https://github.com/matrix-org/synapse/pull/1680)
during a time when the IRC bridge on matrix.org was under extreme load. The endpoints were fully
intended to alleviate load by having the bridge do less work and have the server doing more.
## Proposal
This proposal calls for both `/joined_members` and `/joined_rooms` to be deprecated. The
deprecation is to be coupled with improving how `/members` works and introducing a new `/rooms`
endpoint, which will work in a very similar way to the updated `/members` endpoint. Both endpoints
are proposed to get some way to filter based upon membership, as outlined in the options below.
### Option 1: Query string
A new query parameter, `membership`, should be added to the `/members` endpoint. The parameter
filters the membership list of the room such that only members with a matching `membership` are
returned. The parameter can be supplied multiple times to filter on multiple membership states. For
example, the request could be `/members?membership=join&membership=invite` to get all invited and
joined members for the room. If no `membership` parameter is specified, the default is to return
all members of the room regardless of membership state.
To compliment the `/members` endpoint, a new endpoint should be added to query the rooms for the
user. This uses the same style of using a membership query parameter to filter the rooms.
Some examples of using this endpoint are below. The `rooms` field is an object where the key is a
room ID and the value is information about that room, currently storing a single `membership`
field. The value is an object to support future expansion of this API.
```json5
// GET /_matrix/client/r0/rooms?membership=join&membership=invite
{
"rooms": {
"!somewhere:domain.com": {
"membership": "join"
},
"!elsewhere:matrix.org": {
"membership": "invite"
}
}
}
```
```json5
// GET /_matrix/client/r0/rooms?membership=ban
{
"rooms": {
"!plzno:domain.com": {
"membership": "ban"
}
}
}
```
```json5
// GET /_matrix/client/r0/rooms
{
"rooms": {
"!somewhere:domain.com": {
"membership": "join"
},
"!elsewhere:matrix.org": {
"membership": "invite"
},
"!plzno:domain.com": {
"membership": "ban"
},
"!curbaf:domain.com": {
"membership": "leave"
}
}
}
```
### Option 2: Filter
As with Option 1, a new endpoint would be added to handle getting the list of rooms. However, instead of both `/members` and `/rooms` taking a query parameter for membership they would instead take a filter (re-using existing matrix concepts). Similar to how `/messages` works, this filter would be a `RoomEventFilter` instead of having all the available options. Additionally, the filter would support a `membership` field to filter based upon membership.
An example filter for getting members/rooms of membership `invite` or `join` would be:
```json5
{
"limit": 5, // The maximum number of items to return. Defaults to no limit.
// These only apply when fetching members in a room
"senders": ["*"],
"not_senders": [],
// These only apply when fetching rooms
"rooms": ["*"],
"not_rooms": [],
// NEW! Filter based upon the given membership values.
"membership": ["join", "invite"],
// These are copied from the RoomEventFilter schema, but are ignored
"types": [],
"not_types": [],
"contains_url": true,
}
```
### Option 3: Even more filters
Expanding on Option 2, we give `/state` the option of a filter (also from Option 2). This would
require the `types` to be useful, and we could potentially deprecate the `/members` endpoint
entirely with this approach.
Likewise, `/context` should take a similar filter so clients can get members at a given point in
history.
## Alternative solutions
### Using ?membership=join,invite or ?membership=join+invite instead
The arguments in favour of this approach are:
* It doesn’t rely on undefined behaviour in RFC3986
* Using multiple keys in the query string hasn’t been done before in the matrix spec
The arguments against this approach are:
* It’s not as pretty and may require hex encoding
* It adds unnecessary complexity given most query string parsers are capable of handling multiple
keys in the query string. It is additional complexity because implementations would now need to
do string splitting instead of relying on their already-in-use parsing libraries
### Encoding ?membership as a JSON value
The arguments in favour of this approach are:
* The filtering API already does this
* It doesn’t rely on undefined behaviour in RFC3986
The arguments against this approach are:
* It’s not as pretty and requires hex encoding
* Implementations would be forced to perform decoding, adding additional complexity (see the con
for comma-separated values)