wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add general clarity to the /createRoom endpoint

Browse source 
This commit does a number of things:
* Minor formatting/alignment changes
* Document the room_alias response key. This could be deprecated now, or forfeited, if needed.
* Remove the guest_can_join parameter - it is not actually supported
* Document the previously undocumented power_level_content_override parameter
* Clarify that the room_id is required on the response
* More clearly spell out which events are created as part of the request
* Clarify how the room alias becomes the canonical alias
* Clarify how the `visibility` may be used to determine a default preset to apply
* Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value

References:
* Preset being inferred by the visibility: cd32c19a60/synapse/handlers/room.py (L172-L177)
* Power level content overrides:
  * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198
  * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359
* Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370
* `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315

Fixes https://github.com/matrix-org/matrix-doc/issues/1243
Fixes https://github.com/matrix-org/matrix-doc/issues/1471
Inspired by https://github.com/matrix-org/matrix-doc/issues/1213
This commit is contained in:
Travis Ralston 2018-08-15 17:25:30 -06:00
parent 669d526ea7
commit 45c68e323a
3 changed files with 107 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

67
api/client-server/create_room.yaml
View file

@ -39,16 +39,20 @@ paths:
apply the events implied by the request in the following order:
0. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events.
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
1. Events set by the ``preset``.
1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
2. Events listed in ``initial_state``, in the order that they are
listed.
3. Events implied by ``name`` and ``topic``.
3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
4. Invite events implied by ``invite`` and ``invite_3pid``.
4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
The available presets do the following with respect to room state:
@ -60,6 +64,9 @@ paths:
``public_chat`` ``public`` ``shared`` ``forbidden``
======================== ============== ====================== ================ =========
The server will create a ``m.room.create`` event in the room with the
requesting user as the creator, alongside other keys provided in the
``creation_content``.
operationId: createRoom
security:
- accessToken: []
@ -70,14 +77,14 @@ paths:
schema:
type: object
example: {
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
}
properties:
visibility:
type: string
@ -89,6 +96,11 @@ paths:
``private`` visibility if this key is not included. NB: This
should not be confused with ``join_rules`` which also uses the
word ``public``.
If no ``preset`` is specificed, the server may use the visbility
to determine which preset to use. A visbility of ``public``
equates to a preset of ``public_chat`` and ``private`` visibility
equates to a preset of ``private_chat``.
room_alias_name:
type: string
description: |-
@ -98,6 +110,9 @@ paths:
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
The complete room alias will become the canonical alias for
the room.
name:
type: string
description: |-
@ -145,6 +160,14 @@ paths:
The server will clobber the following keys: ``creator``. Future
versions of the specification may allow the server to clobber
other keys.
properties:
"m.federate":
type: boolean
description: |-
Whether users on other servers can join this room. Defaults
to ``true`` or what the server specifies. Setting this to
``false`` may prevent users from being invited as part of
this room creation request if they reside on other servers.
initial_state:
type: array
description: |-
@ -181,10 +204,14 @@ paths:
This flag makes the server set the ``is_direct`` flag on the
``m.room.member`` events sent to the users in ``invite`` and
``invite_3pid``. See `Direct Messaging`_ for more information.
guest_can_join:
type: boolean
power_level_content_override:
title: Power Level Event Content
description: |-
Allows guests to join the room. See `Guest Access`_ for more information.
The power level content to override in the default power level
event. This object is applied on top of the generated power
level event prior to it being sent to the room. Defaults
to overriding nothing.
$ref: "definitions/event-schemas/power_level_content_schema.yaml"
responses:
200:
description: Information about the newly created room.
@ -196,10 +223,17 @@ paths:
type: string
description: |-
The created room's ID.
room_alias:
type: string
description: |-
The complete room alias for the room, if a room alias was created
for the room.
required: ['room_id']
examples:
application/json: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
"room_id": "!sefiuhWgwghwWgh:example.com",
"room_alias": "#thepub:example.com"
}
400:
description: |-
@ -218,6 +252,5 @@ paths:
``M_INVALID_ROOM_STATE``).
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room creation

56
event-schemas/power_level_content_schema.yaml Normal file
View file

@ -0,0 +1,56 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
properties:
ban:
description: The level required to ban a user. Defaults to 50 if unspecified.
type: number
events:
additionalProperties:
type: number
description: The level required to send specific event types. This is a mapping from event type to power level required.
title: Event power levels
type: object
events_default:
description: |-
The default level required to send message events. Can be
overridden by the ``events`` key. Defaults to 0 if unspecified.
type: number
invite:
description: The level required to invite a user. Defaults to 50 if unspecified.
type: number
kick:
description: The level required to kick a user. Defaults to 50 if unspecified.
type: number
redact:
description: The level required to redact an event. Defaults to 50 if unspecified.
type: number
state_default:
description: |-
The default level required to send state events. Can be overridden
by the ``events`` key. Defaults to 50 if unspecified, but 0 if
there is no ``m.room.power_levels`` event at all.
type: number
users:
additionalProperties:
type: number
description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
title: User power levels
type: object
users_default:
description: |-
The default power level for every user in the room, unless their
``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
unspecified.
type: number
type: object

44
event-schemas/schema/m.room.power_levels
View file

@ -43,49 +43,7 @@ description: |-
properties:
content:
properties:
ban:
description: The level required to ban a user. Defaults to 50 if unspecified.
type: number
events:
additionalProperties:
type: number
description: The level required to send specific event types. This is a mapping from event type to power level required.
title: Event power levels
type: object
events_default:
description: |-
The default level required to send message events. Can be
overridden by the ``events`` key. Defaults to 0 if unspecified.
type: number
invite:
description: The level required to invite a user. Defaults to 50 if unspecified.
type: number
kick:
description: The level required to kick a user. Defaults to 50 if unspecified.
type: number
redact:
description: The level required to redact an event. Defaults to 50 if unspecified.
type: number
state_default:
description: |-
The default level required to send state events. Can be overridden
by the ``events`` key. Defaults to 50 if unspecified, but 0 if
there is no ``m.room.power_levels`` event at all.
type: number
users:
additionalProperties:
type: number
description: The power levels for specific users. This is a mapping from ``user_id`` to power level for that user.
title: User power levels
type: object
users_default:
description: |-
The default power level for every user in the room, unless their
``user_id`` is mentioned in the ``users`` key. Defaults to 0 if
unspecified.
type: number
type: object
$ref: "../power_level_content_schema.yaml"
state_key:
description: A zero-length string.
pattern: '^$'