mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-02-22 05:53:42 +01:00
Part 1: Invites
This commit is contained in:
Travis Ralston
parent
6e16a19ac9
commit
a07f2d0f23
|
|
@ -2810,7 +2810,7 @@ fresh state can be acquired from a join.
|
|||
Stripped state should contain some or all of the following state events, which
|
||||
should be represented as stripped state events when possible:
|
||||
|
||||
* [`m.room.create`](#mroomcreate)
|
||||
* [`m.room.create`](#mroomcreate) ({{% changed-in v="1.16" %}} required on invites and knocks)
|
||||
* [`m.room.name`](#mroomname)
|
||||
* [`m.room.avatar`](#mroomavatar)
|
||||
* [`m.room.topic`](#mroomtopic)
|
||||
|
|
|
|||
|
|
@ -945,6 +945,18 @@ Note that invites are used to indicate that knocks were accepted. As such,
|
|||
receiving servers should be prepared to manually link up a previous knock
|
||||
to an invite if the invite event does not directly reference the knock.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.16" %}} `invite_room_state` MUST now have its entries formatted
|
||||
according to the room's version (see [room version specification](/rooms)). However,
|
||||
servers SHOULD consider their local ecosystems before returning the described
|
||||
`400 M_MISSING_PARAM` error code. While migrating, servers SHOULD warn about
|
||||
invites which fail the validation rather than error in room versions 1 through 11.
|
||||
All invites to other room versions which fail validation SHOULD result in an error.
|
||||
|
||||
The specification suggests that servers finish their migration no later than
|
||||
January 2026, though servers may extend this as required to support their users.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% http-api spec="server-server" api="invites-v1" %}}
|
||||
|
||||
{{% http-api spec="server-server" api="invites-v2" %}}
|
||||
|
|
|
|||
|
|
@ -71,9 +71,20 @@ paths:
|
|||
properties:
|
||||
invite_room_state:
|
||||
type: array
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |
|
||||
`m.room.create` and format requirements were added.
|
||||
description: |-
|
||||
An optional list of [stripped state events](/client-server-api/#stripped-state)
|
||||
to help the receiver of the invite identify the room.
|
||||
A list of state events to help the receiver of the invite identify the room.
|
||||
Translated as [stripped state events](/client-server-api/#stripped-state)
|
||||
over the Client-Server API.
|
||||
|
||||
MUST contain the `m.room.create` event for the room. All events listed
|
||||
MUST additionally be formatted according to the room version specification.
|
||||
|
||||
Servers might need to apply validation to the `invite_room_state` depending
|
||||
on room version. See the `400 M_MISSING_PARAM` error definition for more
|
||||
information.
|
||||
items:
|
||||
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
||||
example:
|
||||
|
|
@ -119,13 +130,23 @@ paths:
|
|||
"sender": "@someone:example.org",
|
||||
"unsigned": {
|
||||
"invite_room_state": [
|
||||
{
|
||||
"type": "m.room.create",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"version": "12"
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
},
|
||||
{
|
||||
"type": "m.room.name",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"name": "Example Room"
|
||||
}
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
},
|
||||
{
|
||||
"type": "m.room.join_rules",
|
||||
|
|
@ -133,7 +154,8 @@ paths:
|
|||
"state_key": "",
|
||||
"content": {
|
||||
"join_rule": "invite"
|
||||
}
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
@ -168,6 +190,35 @@ paths:
|
|||
"errcode": "M_FORBIDDEN",
|
||||
"error": "User cannot invite the target user."
|
||||
}
|
||||
"400":
|
||||
description: |-
|
||||
The `M_MISSING_PARAM` error code is used to indicate one or more of
|
||||
the following:
|
||||
|
||||
* The `m.room.create` event is missing from `invite_room_state`.
|
||||
* One or more entries in `invite_room_state` are not formatted according
|
||||
to the room's version.
|
||||
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
|
||||
* One or more events does not reside in the same room as the invite.
|
||||
Note: Some room versions may require calculating the room ID for an
|
||||
event rather than relying on the presence of `room_id`.
|
||||
|
||||
Servers MAY apply the validation above to room versions 1 through 11,
|
||||
and SHOULD apply the validation above to all other room versions.
|
||||
|
||||
If `M_MISSING_PARAM` is returned and the request is associated with a
|
||||
Client-Server API request, the Client-Server API request SHOULD fail
|
||||
with a 5xx error rather than being passed through.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: ../client-server/definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_MISSING_PARAM",
|
||||
"error": "Create event not among invite state entries."
|
||||
}
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
|
|||
|
|
@ -72,9 +72,20 @@ paths:
|
|||
$ref: definitions/invite_event.yaml
|
||||
invite_room_state:
|
||||
type: array
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |
|
||||
`m.room.create` and format requirements were added.
|
||||
description: |-
|
||||
An optional list of [stripped state events](/client-server-api/#stripped-state)
|
||||
to help the receiver of the invite identify the room.
|
||||
A list of state events to help the receiver of the invite identify the room.
|
||||
Translated as [stripped state events](/client-server-api/#stripped-state)
|
||||
over the Client-Server API.
|
||||
|
||||
MUST contain the `m.room.create` event for the room. All events listed
|
||||
MUST additionally be formatted according to the room version specification.
|
||||
|
||||
Servers might need to apply validation to the `invite_room_state` depending
|
||||
on room version. See the `400 M_MISSING_PARAM` error definition for more
|
||||
information.
|
||||
items:
|
||||
$ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
|
||||
example:
|
||||
|
|
@ -112,22 +123,33 @@ paths:
|
|||
"sender": "@someone:example.org",
|
||||
"unsigned": {
|
||||
"invite_room_state": [
|
||||
{
|
||||
"type": "m.room.name",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"name": "Example Room"
|
||||
{
|
||||
"type": "m.room.create",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"version": "12"
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
},
|
||||
{
|
||||
"type": "m.room.name",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"name": "Example Room"
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
},
|
||||
{
|
||||
"type": "m.room.join_rules",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"join_rule": "invite"
|
||||
},
|
||||
"remaining_fields": "are formatted according to the room version specification"
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "m.room.join_rules",
|
||||
"sender": "@bob:example.org",
|
||||
"state_key": "",
|
||||
"content": {
|
||||
"join_rule": "invite"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"content": {
|
||||
|
|
@ -151,6 +173,24 @@ paths:
|
|||
|
||||
The error should be passed through to clients so that they
|
||||
may give better feedback to users.
|
||||
|
||||
The `M_MISSING_PARAM` error code is used to indicate one or more of
|
||||
the following:
|
||||
|
||||
* The `m.room.create` event is missing from `invite_room_state`.
|
||||
* One or more entries in `invite_room_state` are not formatted according
|
||||
to the room's version.
|
||||
* One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
|
||||
* One or more events does not reside in the same room as the invite.
|
||||
Note: Some room versions may require calculating the room ID for an
|
||||
event rather than relying on the presence of `room_id`.
|
||||
|
||||
Servers MAY apply the validation above to room versions 1 through 11,
|
||||
and SHOULD apply the validation above to all other room versions.
|
||||
|
||||
If `M_MISSING_PARAM` is returned and the request is associated with a
|
||||
Client-Server API request, the Client-Server API request SHOULD fail
|
||||
with a 5xx error rather than being passed through.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -137,6 +137,9 @@ properties:
|
|||
- type: object
|
||||
properties:
|
||||
invite_room_state:
|
||||
x-changedInMatrixVersion:
|
||||
"1.16": |
|
||||
`m.room.create` was made a required event type for stripped state.
|
||||
description: |-
|
||||
A subset of the state of the room at the time of the invite, if `membership` is `invite`.
|
||||
Note that this state is informational, and SHOULD NOT be trusted; once the client has
|
||||
|
|
@ -145,7 +148,8 @@ properties:
|
|||
they SHOULD behave properly (with possibly a degraded but not a broken experience) in
|
||||
the absence of any particular events here. If they are set on the room, at least the
|
||||
state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name`
|
||||
SHOULD be included.
|
||||
SHOULD be included. The `m.room.create` event MUST be included, though MAY be missing if
|
||||
the server hasn't updated to support the Matrix 1.16 specification.
|
||||
items:
|
||||
$ref: "core-event-schema/stripped_state.yaml"
|
||||
type: array
|
||||
|
|
|
|||
Loading…
Reference in a new issue