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
This commit is contained in:
Travis Ralston
GitHub
parent
224773dc6a
commit
56532dd688
8 changed files with 83 additions and 36 deletions
|
|
@ -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).
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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: {
|
||||
|
|
|
|||
|
|
@ -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']
|
||||
|
|
|
|||
|
|
@ -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']
|
||||
|
|
|
|||
|
|
@ -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`,
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue