From 56532dd6885200d7fc70a6ca8c26be1376ebaaf5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 5 Jan 2022 10:57:59 -0700 Subject: [PATCH] Describe and hoist stripped state to a first-class citizen (#3606) * Describe and hoist stripped state to a first-class citizen Fixes https://github.com/matrix-org/matrix-doc/issues/3413 MSC: https://github.com/matrix-org/matrix-doc/pull/3173 * Add changelog * may->can for clarity * Update text per review --- .../newsfragments/3606.clarification | 1 + content/client-server-api/_index.md | 61 +++++++++++++++++++ data/api/client-server/sync.yaml | 26 +++----- data/api/server-server/invites-v1.yaml | 7 +-- data/api/server-server/invites-v2.yaml | 7 +-- data/api/server-server/knocks.yaml | 7 +-- .../stripped_state.yaml | 2 +- data/event-schemas/schema/m.room.member.yaml | 8 +-- 8 files changed, 83 insertions(+), 36 deletions(-) create mode 100644 changelogs/client_server/newsfragments/3606.clarification rename data/event-schemas/schema/{ => core-event-schema}/stripped_state.yaml (98%) diff --git a/changelogs/client_server/newsfragments/3606.clarification b/changelogs/client_server/newsfragments/3606.clarification new file mode 100644 index 00000000..8945f893 --- /dev/null +++ b/changelogs/client_server/newsfragments/3606.clarification @@ -0,0 +1 @@ +Clarify what "Stripped State" is and what purpose it serves, as per [MSC3173](https://github.com/matrix-org/matrix-doc/pull/3173). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 5e2522af..1b38c0f8 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1516,6 +1516,67 @@ following field: |--------------|--------------|--------------------------------------------------------------------------------------------------------------| | state_key | string | **Required.** A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user. | +### Stripped state + +Stripped state events are simplified state events to help a potential +joiner identify the room. These state events can only have the `sender`, +`type`, `state_key` and `content` keys present. + +These stripped state events typically appear on invites, knocks, and in +other places where a user *could* join the room under the conditions +available (such as a [`restricted` room](#restricted-rooms)). + +Clients should only use stripped state events so long as they don't have +access to the proper state of the room. Once the state of the room is +available, all stripped state should be discarded. In cases where the +client has an archived state of the room (such as after being kicked) +and the client is receiving stripped state for the room, such as from an +invite or knock, then the stripped state should take precedence until +fresh state can be acquired from a join. + +The following state events should be represented as stripped state when +possible: + +* [`m.room.create`](#mroomcreate) +* [`m.room.name`](#mroomname) +* [`m.room.avatar`](#mroomavatar) +* [`m.room.topic`](#mroomtopic) +* [`m.room.join_rules`](#mroomjoin_rules) +* [`m.room.canonical_alias`](#mroomcanonical_alias) +* [`m.room.encryption`](#mroomencryption) + +{{% boxes/note %}} +Clients should inspect the list of stripped state events and not assume any +particular event is present. The server might include events not described +here as well. +{{% /boxes/note %}} + +{{% boxes/rationale %}} +The name, avatar, topic, and aliases are presented as aesthetic information +about the room, allowing users to make decisions about whether or not they +want to join the room. + +The join rules are given to help the client determine *why* it is able to +potentially join. For example, annotating the room decoration with iconography +consistent with the respective join rule for the room. + +The create event can help identify what kind of room is being joined, as it +may be a Space or other kind of room. The client might choose to render the +invite in a different area of the application as a result. + +Similar to join rules, the encryption information is given to help clients +decorate the room with appropriate iconography or messaging. +{{% /boxes/rationale %}} + +{{% boxes/warning %}} +Although stripped state is usually generated and provided by the server, it +is still possible to be incorrect on the receiving end. The stripped state +events are not signed and could theoretically be modified, or outdated due to +updates not being sent. +{{% /boxes/warning %}} + +{{% event-fields event_type="stripped_state" %}} + ### Size limits The complete event MUST NOT be larger than 65536 bytes, when formatted diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index ca788429..f8127bf5 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -264,23 +264,13 @@ paths: title: InviteState type: object description: |- - The state of a room that the user has been invited - to. 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. Instead the - client should keep two separate copies of the - state: the one from the `invite_state` and one - from the archived `state`. If the client joins - the room then the current state will be given as a - delta against the archived `state` not the - `invite_state`. + The [stripped state](#stripped-state) of a room that the user has been invited + to. properties: events: - description: The StrippedState events that form the invite state. + description: The [stripped state events](#stripped-state) that form the invite state. items: - $ref: "../../event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" type: array knock: title: Knocked rooms @@ -295,14 +285,12 @@ paths: title: KnockState type: object description: |- - The state of a room that the user has knocked upon. The state - events contained here have the same restrictions as `InviteState` - above. + The [stripped state](#stripped-state) of a room that the user has knocked upon. properties: events: - description: The StrippedState events that form the knock state. + description: The [stripped state events](#stripped-state) that form the knock state. items: - $ref: "../../event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" type: array leave: title: Left rooms diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index 14f1665a..cd9812c0 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -78,11 +78,10 @@ paths: invite_room_state: type: array description: |- - An optional list of simplified events to help the receiver of the invite - identify the room. The recommended events to include are the join rules, - canonical alias, avatar, and name of the room. + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. items: - $ref: "../../event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" example: $ref: "../../event-schemas/examples/invite_room_state.json" example: { diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 8296bb8b..b8b66f13 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -79,11 +79,10 @@ paths: invite_room_state: type: array description: |- - An optional list of simplified events to help the receiver of the invite - identify the room. The recommended events to include are the join rules, - canonical alias, avatar, and name of the room. + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the receiver of the invite identify the room. items: - $ref: "../../event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" example: $ref: "../../event-schemas/examples/invite_room_state.json" required: ['room_version', 'event'] diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index e65a7d01..2ef5ceaa 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -285,11 +285,10 @@ paths: knock_room_state: type: array items: - $ref: "../../event-schemas/schema/stripped_state.yaml" + $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml" description: |- - A list of simplified events to help the initiator of the knock identify - the room. The recommended events to include are the join rules, canonical - alias, avatar, name, and encryption state of the room. + An optional list of [stripped state events](/client-server-api/#stripped-state) + to help the initiator of the knock identify the room. example: $ref: "../../event-schemas/examples/knock_room_state.json" required: ['knock_room_state'] diff --git a/data/event-schemas/schema/stripped_state.yaml b/data/event-schemas/schema/core-event-schema/stripped_state.yaml similarity index 98% rename from data/event-schemas/schema/stripped_state.yaml rename to data/event-schemas/schema/core-event-schema/stripped_state.yaml index 92306dc9..c98d8878 100644 --- a/data/event-schemas/schema/stripped_state.yaml +++ b/data/event-schemas/schema/core-event-schema/stripped_state.yaml @@ -18,7 +18,7 @@ # difficult because the schema would be at two different locations, with # different relative pathing. -title: StrippedState +title: StrippedStateEvent type: object description: |- A stripped down state event, with only the `type`, `state_key`, diff --git a/data/event-schemas/schema/m.room.member.yaml b/data/event-schemas/schema/m.room.member.yaml index df992ee2..9427d25f 100644 --- a/data/event-schemas/schema/m.room.member.yaml +++ b/data/event-schemas/schema/m.room.member.yaml @@ -19,8 +19,8 @@ description: |- The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise. This event may also include an `invite_room_state` key inside the event's `unsigned` data. - If present, this contains an array of `StrippedState` Events. These events provide information - on a subset of state events such as the room name. + If present, this contains an array of [stripped state events](/client-server-api/#stripped-state) + to assist the receiver in identifying the room. The user for which a membership applies is represented by the `state_key`. Under some conditions, the `sender` and `state_key` may not match - this may be interpreted as the `sender` affecting @@ -136,7 +136,7 @@ properties: state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name` SHOULD be included. items: - $ref: "stripped_state.yaml" + $ref: "core-event-schema/stripped_state.yaml" type: array knock_room_state: description: |- @@ -145,7 +145,7 @@ properties: the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, `m.room.name`, and `m.room.encryption` SHOULD be included. items: - $ref: "stripped_state.yaml" + $ref: "core-event-schema/stripped_state.yaml" type: array title: The current membership state of a user in the room. type: object