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

Add Spaces to the spec (#3610)

Browse source 
* First iteration of specifying Spaces

MSCs:
* https://github.com/matrix-org/matrix-doc/pull/3288
* https://github.com/matrix-org/matrix-doc/pull/2946
* https://github.com/matrix-org/matrix-doc/pull/1772

Note that this makes modifications to the underlying MSCs as well. These are intended to be minor edits to aid clarity/accuracy of the MSCs, as per the proposal process. Functionally, clients and servers might need to change their behaviour slightly as is expected of implementing this stuff early. Synapse has these changes (alongside backwards compatibility) here: https://github.com/matrix-org/synapse/pull/11667

* add changelogs

* Accuracy per review

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* fully prefix new endpoints

* Fully prefix endpoint in 3616 too

* Fix ordering example

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
This commit is contained in:
Travis Ralston 2022-01-17 10:03:14 -07:00 • committed by GitHub
parent 21882b6006
commit 9af83dfd41
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
21 changed files with 924 additions and 138 deletions
Download patch file Download diff file Expand all files Collapse all files

70
data/api/client-server/definitions/public_rooms_chunk.yaml Normal file
View file

@ -0,0 +1,70 @@
# Copyright 2021 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
title: "PublicRoomsChunk"
properties:
aliases:
type: array
description: Aliases of the room. May be empty.
items:
type: string
example: ["#general:example.org"]
canonical_alias:
type: string
description: The canonical alias of the room, if any.
example: "#general:example.org"
name:
type: string
description: The name of the room, if any.
example: "General Chat"
num_joined_members:
type: integer
description: The number of members joined to the room.
example: 42
room_id:
type: string
description: The ID of the room.
example: "!abcdefg:example.org"
topic:
type: string
description: The topic of the room, if any.
example: "All things general"
world_readable:
type: boolean
description: Whether the room may be viewed by guest users without joining.
example: false
guest_can_join:
type: boolean
description: |-
Whether guest users may join the room and participate in it.
If they can, they will be subject to ordinary power level
rules like any other user.
example: true
avatar_url:
type: string
format: uri
description: The URL for the room's avatar, if one is set.
example: "mxc://example.org/abcdef"
join_rule:
type: string
description: |-
The room's join rule. When not present, the room is assumed to
be `public`.
example: "public"
required:
- room_id
- num_joined_members
- world_readable
- guest_can_join

68
data/api/client-server/definitions/public_rooms_response.yaml
View file

@ -22,61 +22,19 @@ properties:
description: |-
A paginated chunk of public rooms.
items:
type: object
title: "PublicRoomsChunk"
required:
- room_id
- num_joined_members
- world_readable
- guest_can_join
properties:
aliases:
type: array
description: |-
Aliases of the room. May be empty.
items:
type: string
canonical_alias:
type: string
description: |-
The canonical alias of the room, if any.
name:
type: string
description: |-
The name of the room, if any.
num_joined_members:
type: integer
description: |-
The number of members joined to the room.
room_id:
type: string
description: |-
The ID of the room.
topic:
type: string
description: |-
The topic of the room, if any.
world_readable:
type: boolean
description: |-
Whether the room may be viewed by guest users without joining.
guest_can_join:
type: boolean
description: |-
Whether guest users may join the room and participate in it.
If they can, they will be subject to ordinary power level
rules like any other user.
avatar_url:
type: string
format: uri
description: The URL for the room's avatar, if one is set.
join_rule:
type: string
description: |-
The room's join rule. When not present, the room is assumed to
be `public`. Note that rooms with `invite` join rules are not
expected here, but rooms with `knock` rules are given their
near-public nature.
allOf:
- $ref: "public_rooms_chunk.yaml"
- type: object
properties:
# Override description of join_rule
join_rule:
type: string
description: |-
The room's join rule. When not present, the room is assumed to
be `public`. Note that rooms with `invite` join rules are not
expected here, but rooms with `knock` rules are given their
near-public nature.
example: "public"
next_batch:
type: string
description: |-

194
data/api/client-server/space_hierarchy.yaml Normal file
View file

@ -0,0 +1,194 @@
# Copyright 2021 The Matrix.org Foundation C.I.C.
#
# 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.
swagger: '2.0'
info:
title: "Matrix Client-Server Space Hierarchy API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomId}/hierarchy":
get:
x-addedInMatrixVersion: "1.2"
summary: Retrieve a portion of a space tree.
description: |-
Paginates over the space tree in a depth-first manner to locate child rooms of a given space.
Where a child room is unknown to the local server, federation is used to fill in the details.
The servers listed in the `via` array should be contacted to attempt to fill in missing rooms.
Only [`m.space.child`](#mspacechild) state events of the room are considered. Invalid child
rooms and parent events are not covered by this endpoint.
operationId: getSpaceHierarchy
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID of the space to get a hierarchy for.
required: true
x-example: "!space:example.org"
- in: query
type: boolean
name: suggested_only
description: |-
Optional (default `false`) flag to indicate whether or not the server should only consider
suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event
contents.
x-example: true
- in: query
type: number
name: limit
description: |-
Optional limit for the maximum number of rooms to include per response. Must be an integer
greater than zero.
Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
x-example: 20
- in: query
type: number
name: max_depth
description: |-
Optional limit for how far to go into the space. Must be a non-negative integer.
When reached, no further child rooms will be returned.
Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
x-example: 5
- in: query
type: string
name: from
description: |-
A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot
be changed from the first request.
x-example: "next_batch_token"
responses:
200:
description: |-
A portion of the space tree, starting at the provided room ID.
examples:
application/json: {
"rooms": [
{
"room_id": "!space:example.org",
"avatar_url": "mxc://example.org/abcdef",
"guest_can_join": false,
"name": "The First Space",
"topic": "No other spaces were created first, ever",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space",
"num_joined_members": 42,
"aliases": ["#general:example.org"],
"canonical_alias": "#general:example.org",
"children_state": [
{
"type": "m.space.child",
"state_key": "!a:example.org",
"content": {
"via": ["example.org"]
},
"sender": "@alice:example.org",
"origin_server_ts": 1629413349153
}
]
}
],
"next_batch": "next_batch_token"
}
schema:
type: object
properties:
rooms:
type: array
description: |-
The rooms for the current page, with the current filters.
items:
allOf:
- $ref: "definitions/public_rooms_chunk.yaml"
- type: object
properties:
room_type:
type: string
description: |-
The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
children_state:
type: array
description: |-
The [`m.space.child`](#mspacechild) events of the space-room, represented
as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key.
If the room is not a space-room, this should be empty.
items:
allOf:
- $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
- type: object
properties:
origin_server_ts:
type: number
format: int64
description: The `origin_server_ts` for the event.
required: [origin_server_ts]
required: [room_type, children_state]
next_batch:
type: string
description: |-
A token to supply to `from` to keep paginating the responses. Not present when there are
no further results.
required: [rooms]
403:
description: |-
The user cannot view or peek on the room. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The room is not set up for peeking.
- The user has been banned from the room.
- The room does not exist.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to view this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
400:
description: |-
The request was invalid in some way. A meaningful `errcode`
and description error text will be returned. Example reasons for rejection are:
- The `from` token is unknown to the server.
- `suggested_only` or `max_depth` changed during pagination.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "suggested_only and max_depth cannot change on paginated requests"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Spaces