From b94d379921696731c0ca2ac17257cd94ea3dd2a7 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 1 Jun 2021 13:59:21 -0400 Subject: [PATCH] Add federation and reword a bit. --- .../3173-expose-stripped-state-events.md | 73 +++++++++++++++---- 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/proposals/3173-expose-stripped-state-events.md b/proposals/3173-expose-stripped-state-events.md index 3dccaf330..565dad7bd 100644 --- a/proposals/3173-expose-stripped-state-events.md +++ b/proposals/3173-expose-stripped-state-events.md @@ -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[0](#f0)) 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[0](#f0)) that +homeserver implementations include the following events as part of the stripped +state of a room: * Create event (`m.room.create`)[1](#f1) * 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