Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-16 19:13:43 +01:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge 2933ab5f52 into 817ec5380f

Browse source
This commit is contained in:
Johannes Marbach 2025-03-28 14:09:57 +00:00 committed by GitHub
parent 817ec5380f 2933ab5f52
commit 07b959c078
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 75 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/2104.clarification Normal file
View file

@ -0,0 +1 @@
Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

1
changelogs/server_server/newsfragments/2104.clarification Normal file
View file

@ -0,0 +1 @@
Rooms published in `/publicRooms` don't necessarily have `public` join rules or `world_readable` history visibility.

33
content/client-server-api/_index.md
View file

@ -2831,7 +2831,38 @@ re-invited.
{{% http-api spec="client-server" api="banning" %}}
### Listing rooms
### Room directory
Homeservers MAY publish a room directory to allow users to discover rooms. A room
can have one of two visibility settings in the directory:
`public`
The room will be shown in the published room directory.
`private`
The room will be hidden from the published room directory.
Clients can define a room's initial visibility in the directory via the `visibility`
parameter in [`/createRoom`](#post_matrixclientv3createroom). Irrespective of room
creation, clients can query and change a room's visibility in the directory through
the endpoints listed below, provided that the server permits this.
{{% boxes/warning %}}
The visibility setting merely defines whether a room is included in the published
room directory or not. It doesn't make any guarantees about the room's
[join rule](#mroomjoin_rules) or [history visibility](#room-history-visibility).
In particular, a visibility setting of `public` should not be confused with a `public`
join rule. Rooms with a join rule of `knock`, for instance, could reasonably be published
in the directory, too.
Similarly, a visibility setting of `public` does not necessarily imply a `world_readable`
history visibility.
To increase performance, servers MAY apply additional filters when listing the
directory, for instance, by automatically excluding rooms with `invite` join rules
that are not `world_readable` regarless of their visibility.
{{% /boxes/warning %}}
{{% http-api spec="client-server" api="list_public_rooms" %}}

7
content/server-server-api.md
View file

@ -1045,11 +1045,10 @@ user's Matrix ID and the token delivered when the invite was stored,
this verification will prove that the `m.room.member` invite event comes
from the user owning the invited third-party identifier.
## Public Room Directory
## Room Directory
To complement the [Client-Server
API](/client-server-api)'s room directory,
homeservers need a way to query the public rooms for another server.
To complement the [room directory in the Client-Server API](/client-server-api#room-directory),
homeservers need a way to query the published rooms of another server.
This can be done by making a request to the `/publicRooms` endpoint for
the server the room directory should be retrieved for.

8
data/api/client-server/create_room.yaml
View file

@ -87,12 +87,8 @@ paths:
- public
- private
description: |-
A `public` visibility indicates that the room will be shown
in the published room list. A `private` visibility will hide
the room from the published room list. Rooms default to
`private` visibility if this key is not included. NB: This
should not be confused with `join_rules` which also uses the
word `public`.
The room's visibility in the server's [room directory](#room-directory).
Defaults to `private`.
room_alias_name:
type: string
description: |-

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

@ -13,7 +13,7 @@
# limitations under the License.
type: object
title: "PublicRoomsChunk"
title: "PublishedRoomsChunk"
properties:
canonical_alias:
type: string

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

@ -13,28 +13,15 @@
# limitations under the License.
type: object
description: A list of the rooms on the server.
description: A list of the published rooms on the server.
required: ["chunk"]
properties:
chunk:
type: array
description: |-
A paginated chunk of public rooms.
A paginated chunk of published rooms.
items:
allOf:
- $ref: "public_rooms_chunk.yaml"
- type: object
title: PublicRoomsChunk
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"
$ref: "public_rooms_chunk.yaml"
next_batch:
type: string
description: |-
@ -50,7 +37,7 @@ properties:
total_room_count_estimate:
type: integer
description: |-
An estimate on the total number of public rooms, if the
An estimate on the total number of published rooms, if the
server has an estimate.
example: {
"chunk": [

36
data/api/client-server/list_public_rooms.yaml
View file

@ -19,8 +19,7 @@ paths:
"/directory/list/room/{roomId}":
get:
summary: Gets the visibility of a room in the directory
description: Gets the visibility of a given room on the server's public room
directory.
description: Gets the visibility of a given room in the server's room directory.
operationId: getRoomVisibilityOnDirectory
parameters:
- in: path
@ -32,7 +31,7 @@ paths:
type: string
responses:
"200":
description: The visibility of the room in the directory
description: The visibility of the room in the directory.
content:
application/json:
schema:
@ -50,7 +49,7 @@ paths:
"visibility": "public"
}
"404":
description: The room is not known to the server
description: The room is not known to the server.
content:
application/json:
schema:
@ -66,12 +65,11 @@ paths:
put:
summary: Sets the visibility of a room in the room directory
description: |-
Sets the visibility of a given room in the server's public room
directory.
Sets the visibility of a given room in the server's room directory.
Servers may choose to implement additional access control checks
here, for instance that room visibility can only be changed by
the room creator or a server administrator.
Servers MAY implement additional access control checks, for instance,
to ensure that a room's visibility can only be changed by the room creator
or a server administrator.
operationId: setRoomVisibilityOnDirectory
security:
- accessTokenQuery: []
@ -97,7 +95,7 @@ paths:
- public
description: |-
The new visibility setting for the room.
Defaults to 'public'.
Defaults to `public`.
example: {
"visibility": "public"
}
@ -114,7 +112,7 @@ paths:
response:
value: {}
"404":
description: The room is not known to the server
description: The room is not known to the server.
content:
application/json:
schema:
@ -129,9 +127,9 @@ paths:
- Room discovery
/publicRooms:
get:
summary: Lists the public rooms on the server.
summary: Lists a server's published room directory
description: |-
Lists the public rooms on the server.
Lists a server's published room directory.
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
@ -154,13 +152,13 @@ paths:
- in: query
name: server
description: |-
The server to fetch the public room lists from. Defaults to the
The server to fetch the room directory from. Defaults to the
local server. Case sensitive.
schema:
type: string
responses:
"200":
description: A list of the rooms on the server.
description: A list of the published rooms on the server.
content:
application/json:
schema:
@ -168,9 +166,9 @@ paths:
tags:
- Room discovery
post:
summary: Lists the public rooms on the server with optional filter.
summary: Lists a server's published room directory with an optional filter
description: |-
Lists the public rooms on the server, with optional filter.
Lists a server's published room directory with an optional filter.
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
@ -182,7 +180,7 @@ paths:
- in: query
name: server
description: |-
The server to fetch the public room lists from. Defaults to the
The server to fetch the room directory from. Defaults to the
local server. Case sensitive.
schema:
type: string
@ -253,7 +251,7 @@ paths:
required: true
responses:
"200":
description: A list of the rooms on the server.
description: A filtered list of the published rooms on the server.
content:
application/json:
schema:

85
data/api/server-server/public_rooms.yaml
View file

@ -13,16 +13,20 @@
# limitations under the License.
openapi: 3.1.0
info:
title: Matrix Federation Public Rooms API
title: Matrix Federation Room Directory API
version: 1.0.0
paths:
/publicRooms:
get:
summary: Get all the public rooms for a homeserver
summary: Lists the server's published room directory.
description: |-
Gets all the public rooms for the homeserver. This should not return
rooms that are listed on another homeserver's directory, just those
listed on the receiving homeserver's directory.
Lists the server's published room directory.
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
This should not return rooms that are listed on another homeserver's directory,
just those listed on the receiving homeserver's directory.
operationId: getPublicRooms
security:
- signedRequest: []
@ -62,21 +66,18 @@ paths:
type: string
responses:
"200":
description: The public room list for the homeserver.
description: A list of the published rooms on the server.
content:
application/json:
schema:
$ref: ../client-server/definitions/public_rooms_response.yaml
post:
summary: Gets the public rooms on the server with optional filter.
summary: Lists the server's published room directory with an optional filter
description: |-
Lists the public rooms on the server, with optional filter.
Lists the server's published room directory with an optional filter.
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
Note that this endpoint receives and returns the same format that is seen
in the Client-Server API's `POST /publicRooms` endpoint.
operationId: queryPublicRooms
security:
- signedRequest: []
@ -147,69 +148,11 @@ paths:
required: true
responses:
"200":
description: A list of the rooms on the server.
description: A filtered list of the published rooms on the server.
content:
application/json:
schema:
type: object
description: A list of the rooms on the server.
required:
- chunk
properties:
chunk:
title: PublicRoomsChunks
type: array
description: A paginated chunk of public rooms.
items:
allOf:
- $ref: ../client-server/definitions/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.
next_batch:
type: string
description: |-
A pagination token for the response. The absence of this token
means there are no more results to fetch and the client should
stop paginating.
prev_batch:
type: string
description: |-
A pagination token that allows fetching previous results. The
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
response:
value: {
"chunk": [
{
"avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true,
"join_rule": "public",
"room_type": "m.space"
}
],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
$ref: ../client-server/definitions/public_rooms_response.yaml
servers:
- url: "{protocol}://{hostname}{basePath}"
variables: