From 45c68e323a17f3e6b25b1c21038a5a6d600b3e03 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 15 Aug 2018 17:25:30 -0600 Subject: [PATCH] Add general clarity to the /createRoom endpoint 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: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/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 --- api/client-server/create_room.yaml | 67 ++++++++++++++----- event-schemas/power_level_content_schema.yaml | 56 ++++++++++++++++ event-schemas/schema/m.room.power_levels | 44 +----------- 3 files changed, 107 insertions(+), 60 deletions(-) create mode 100644 event-schemas/power_level_content_schema.yaml diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 66b5578a5..be99c4ab1 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -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 diff --git a/event-schemas/power_level_content_schema.yaml b/event-schemas/power_level_content_schema.yaml new file mode 100644 index 000000000..5859d56ee --- /dev/null +++ b/event-schemas/power_level_content_schema.yaml @@ -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 \ No newline at end of file diff --git a/event-schemas/schema/m.room.power_levels b/event-schemas/schema/m.room.power_levels index 13a44c709..174ada820 100644 --- a/event-schemas/schema/m.room.power_levels +++ b/event-schemas/schema/m.room.power_levels @@ -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: '^$'