Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-04 05:13:42 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Add federation and reword a bit.

Browse source
This commit is contained in:
Patrick Cloke 2021-06-01 13:59:21 -04:00 committed by Richard van der Hoff
parent 8082b2f813
commit 4933ecd176
1 changed files with 59 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
proposals/3173-expose-stripped-state-events.md
View file

@ -79,7 +79,8 @@ recommends including the `m.room.create` event as one of the stripped state even
This proposal includes a few aspects which are dealt with separately:
1. Generalizing when a user is allowed to view the stripped state of a room.
2. A consistent recommendation for which events to include in the stripped state.
2. A consistent definition of stripped state and a recommendation for which
events to include in the stripped state.
3. Providing a dedicated API for accessing the stripped state of the room.
### Accessing the stripped state of a room
@ -102,12 +103,21 @@ should consider this MSC, for example:
proposes allowing users to join a room based on their membership in a space (as defined in
[MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772)).
### Events to include in the stripped state
### Stripped state definitions and recommended events
It is also proposed to create a single definition for what stripped state events
should be provided to be potential joiners. Thus, it is recommended (although not
required<sup id="a0">[0](#f0)</sup>) that homeserver implementations include the
following as stripped state events:
It is also proposed to create a single definition of what the stripped state of
a room is and for what events should be included in the stripped state to be
potential joiners.
The stripped state of a room is a list of simplified state events to help a
potential joiner identify the room. These state events may only have the
`sender`, `type`, `state_key` and `content` keys present. These events do not
replace any state that the client already has for the room, for example if the
client has archived the room.
It is recommended (although not required<sup id="a0">[0](#f0)</sup>) that
homeserver implementations include the following events as part of the stripped
state of a room:
* Create event (`m.room.create`)<sup id="a1">[1](#f1)</sup>
* Join rules (`m.room.join_rules`)
@ -119,7 +129,9 @@ following as stripped state events:
### Stripped state API
`GET /_matrix/client/r0/rooms/{roomId}/stripped_state`
#### Client-server API
`GET /_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state`
A dedicated API is provided to query for the stripped state of a room. As
described above, any potential joiner may access the stripped state of a room
@ -128,19 +140,26 @@ may access the stripped state, as it is a strict subset of the state).
This API is rate-limited and does not require authentication.
The request format follows [the `/state`](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state)
endpoint.
The request format follows [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state),
but with the addition of handling a `server_name` query parameter (as
specified for [the `/join/{roomIdOrAlias}` endpoint](https://matrix.org/docs/spec/client_server/latest#post-matrix-client-r0-join-roomidoralias)).
The response body includes an array of `StrippedState`, as
[described in the `/sync` response](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-sync).
#### Example request:
If the homeserver does not know the state of the requested room it should use
the corresponding federation API to request the stripped state from another
homeserver.
TODO
##### Example request:
`GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/stripped_state HTTP/1.1`
#### Responses:
##### Responses:
##### Status code 200:
###### Status code 200:
The current stripped state of the room
@ -174,10 +193,33 @@ The current stripped state of the room
Note that this is the same example as [the `/state` endpoint](https://matrix.org/docs/spec/client_server/latest#get-matrix-client-r0-rooms-roomid-state),
but limited to what would be returned as stripped state.
##### Status code 403:
###### Status code 403:
You are not a member of the room, a potential joiner, and the room is not publicly viewable.
#### Server-server API
`GET /_matrix/federation/v1/stripped_state/{roomId}`
Retrieve the stripped state of a room, this is essentially identical to the
client-server API, but will not reach out over federation.
Path parameters:
* `roomId` - **Required.** The room ID to get state for.
Response format:
* `stripped_state` - `[StrippedState]` A list of simplified events to help identify the room.
The form of `StrippedState` is as defined in
[the `/invite/{roomId}/{eventId}` endpoint](https://matrix.org/docs/spec/server_server/latest#put-matrix-federation-v2-invite-roomid-eventid).
The stripped state should be returned to the requesting server if the host has
a potential joiner, e.g. if the room has `join_rules` set to `public` or any
user on the request server is in possession of an invite to the room. The
requesting server is responsible for filtering the returned data to the client.
## Potential issues
This is a generalization of current behavior and shouldn't introduce any new issues.
@ -222,7 +264,10 @@ for potential joiners due to membership in a space.
## Unstable prefix
N/A
| Stable Endpoint | Unstable Endpoint |
|---|---|
| `/_matrix/client/r0/rooms/{roomIdOrAlias}/stripped_state` | `/_matrix/client/unstable/org.matrix.msc3173/rooms/{roomIdOrAlias}/stripped_state` |
| `/_matrix/federation/v1/stripped_state/{roomId}` | `/_matrix/federation/unstable/org.matrix.msc3173/stripped_state/{roomId}` |
## Footnotes