Describe and hoist stripped state to a first-class citizen (#3606)

* Describe and hoist stripped state to a first-class citizen

Fixes #3413
MSC: #3173

* Add changelog

* may->can for clarity

* Update text per review

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).

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

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

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: {

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']

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']

data/event-schemas/schema/stripped_state.yaml → 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`,

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