From b11cf560b54ddc7a73c03443a05cde41f7a98302 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 15 May 2020 17:24:27 -0600 Subject: [PATCH 1/4] Add spec for new alias handling (client-server) MSC: https://github.com/matrix-org/matrix-doc/pull/2432 This commit does not deal with areas which will be covered by the room version specifications (namely the redaction algorithm). It feels a bit overly cruel to completely obliterate all mentions of `m.room.aliases` from the spec as client/server developers may encounter the event type in the wild. To ensure that CTRL+F still works, a brief mention that they do nothing has been put in place, leaving no other references (except the redaction algorithm - see previous paragraph). --- api/client-server/directory.yaml | 82 ++++++++++++++++++- api/client-server/room_state.yaml | 24 ++++++ event-schemas/examples/m.room.aliases | 8 -- event-schemas/examples/m.room.canonical_alias | 6 +- event-schemas/schema/m.room.aliases | 24 ------ event-schemas/schema/m.room.canonical_alias | 22 +++-- specification/client_server_api.rst | 31 ++++--- specification/modules/instant_messaging.rst | 10 +-- 8 files changed, 144 insertions(+), 63 deletions(-) delete mode 100644 event-schemas/examples/m.room.aliases delete mode 100644 event-schemas/schema/m.room.aliases diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 2c7c8386..67bdf236 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -19,7 +19,7 @@ host: localhost:8008 schemes: - https - http -basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% consumes: - application/json produces: @@ -27,7 +27,7 @@ produces: securityDefinitions: $ref: definitions/security.yaml paths: - "/room/{roomAlias}": + "/directory/room/{roomAlias}": put: summary: Create a new mapping from room alias to room ID. operationId: setRoomAlias @@ -129,7 +129,16 @@ paths: description: |- Remove a mapping of room alias to room ID. - Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator. + Servers may choose to implement additional access control checks here, for instance that + room aliases can only be deleted by their creator or a server administrator. + + .. Note:: + Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias`` + state event in the room when an alias is removed. Servers which choose to update the + canonical alias event are recommended to, in addition to their other relevant permission + checks, delete the alias and return a successful response even if the user does not + have permission to update the ``m.room.canonical_alias`` event. + operationId: deleteRoomAlias security: - accessToken: [] @@ -159,3 +168,70 @@ paths: "$ref": "definitions/errors/error.yaml" tags: - Room directory + "/rooms/{roomId}/aliases": + get: + summary: Get a list of local aliases on a given room. + description: |- + Get a list of aliases maintained by the local server for the + given room. + + This endpoint can be called by users who are in the room (external + users receive an ``M_FORBIDDEN`` error response). If the room's + ``m.room.history_visibility`` maps to ``world_readable``, any + user can call this endpoint. + + Servers may choose to implement additional access control checks here, + such as allowing server administrators to view aliases regardless of + membership. + + .. Note:: + Clients are not recommended to display this list of aliases prominently + as they are not curated, unlike those listed in the ``m.room.canonical_alias`` + state event. + + operationId: getLocalAliases + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID to find local aliases of. + required: true + x-example: "!abc123:example.org" + responses: + 200: + description: |- + The list of local aliases for the room. + examples: + application/json: { + "aliases": [ + "#somewhere:example.com", + "#another:example.com", + "#hat_trick:example.com" + ] + } + schema: + type: object + properties: + aliases: + type: array + description: The server's local aliases on the room. Can be empty. + items: + type: string + required: ['aliases'] + 403: + description: The user is not permitted to retrieve the list of local aliases for the room. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You are not a member of the room." + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room directory diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index 640e2009..20b9c1fd 100644 --- a/api/client-server/room_state.yaml +++ b/api/client-server/room_state.yaml @@ -45,6 +45,12 @@ paths: The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See `Room Events`_ for the ``m.`` event specification. + + If the event type being sent is ``m.room.canonical_alias`` servers + SHOULD ensure that any new aliases being listed in the event are valid + per their grammar/syntax and that they point to the room ID where the + state event is to be sent. Servers do not validate aliases which are + being removed or are already present in the state event. operationId: setRoomStateWithKey security: - accessToken: [] @@ -104,5 +110,23 @@ paths: "errcode": "M_FORBIDDEN", "error": "You do not have permission to send the event." } + 400: + description: |- + The sender's request is malformed. + + Some example error codes include: + + * ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias`` + event have invalid syntax. + + * ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event + do not point to the room ID for which the state event is to be sent to. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_BAD_ALIAS", + "error": "The alias '#hello:example.org' does not point to this room." + } tags: - Room participation diff --git a/event-schemas/examples/m.room.aliases b/event-schemas/examples/m.room.aliases deleted file mode 100644 index 3e20332f..00000000 --- a/event-schemas/examples/m.room.aliases +++ /dev/null @@ -1,8 +0,0 @@ -{ - "$ref": "core/state_event.json", - "state_key": "example.org", - "type": "m.room.aliases", - "content": { - "aliases": ["#somewhere:example.org", "#another:example.org"] - } -} diff --git a/event-schemas/examples/m.room.canonical_alias b/event-schemas/examples/m.room.canonical_alias index 06c3226c..698c11b8 100644 --- a/event-schemas/examples/m.room.canonical_alias +++ b/event-schemas/examples/m.room.canonical_alias @@ -3,6 +3,10 @@ "type": "m.room.canonical_alias", "state_key": "", "content": { - "alias": "#somewhere:localhost" + "alias": "#somewhere:localhost", + "alt_aliases": [ + "#somewhere:example.org", + "#myroom:example.com" + ] } } diff --git a/event-schemas/schema/m.room.aliases b/event-schemas/schema/m.room.aliases deleted file mode 100644 index 348d490d..00000000 --- a/event-schemas/schema/m.room.aliases +++ /dev/null @@ -1,24 +0,0 @@ ---- -allOf: - - $ref: core-event-schema/state_event.yaml -description: 'This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The ``state_key`` for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the ``m.room.aliases`` events, one for each homeserver. Clients **should** check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.' -properties: - content: - properties: - aliases: - description: A list of room aliases. - items: - type: string - type: array - required: - - aliases - type: object - state_key: - description: The homeserver domain which owns these room aliases. - type: string - type: - enum: - - m.room.aliases - type: string -title: Informs the room about what room aliases it has been given. -type: object diff --git a/event-schemas/schema/m.room.canonical_alias b/event-schemas/schema/m.room.canonical_alias index 5e8e0524..f227871a 100644 --- a/event-schemas/schema/m.room.canonical_alias +++ b/event-schemas/schema/m.room.canonical_alias @@ -3,21 +3,25 @@ allOf: - $ref: core-event-schema/state_event.yaml description: |- This event is used to inform the room about which alias should be - considered the canonical one. This could be for display purposes or as - suggestion to users which alias to use to advertise the room. - - A room with an ``m.room.canonical_alias`` event with an absent, null, or - empty ``alias`` field should be treated the same as a room with no - ``m.room.canonical_alias`` event. + considered the canonical one, and which other aliases point to the room. + This could be for display purposes or as suggestion to users which alias + to use to advertise and access the room. properties: content: properties: alias: - description: The canonical alias. + description: | + The canonical alias for the room. If not present, null, or empty the + room should be considered to have no canonical alias. type: string + alt_aliases: + description: | + Alternative aliases the room advertises. This list can have aliases + despite the ``alias`` field being null, empty, or otherwise not present. + type: array + items: + type: string type: object - required: - - alias state_key: description: A zero-length string. pattern: '^$' diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index fce879a2..fda2c106 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1594,8 +1594,6 @@ Room Events This specification outlines several standard event types, all of which are prefixed with ``m.`` -{{m_room_aliases_event}} - {{m_room_canonical_alias_event}} {{m_room_create_event}} @@ -1608,6 +1606,15 @@ prefixed with ``m.`` {{m_room_redaction_event}} +Historical events ++++++++++++++++++ + +Some events within the ``m.`` namespace might appear in rooms, however they +serve no significant meaning in this version of the specification. They are: + +* ``m.room.aliases`` + +Previous versions of the specification have more information on these events. Syncing ~~~~~~~ @@ -1813,6 +1820,8 @@ one of the following event types: - ``m.room.aliases`` allows key ``aliases``. - ``m.room.history_visibility`` allows key ``history_visibility``. +.. TODO: Room v6 changes how redaction works in MSC2432 (no special meaning for aliases) + The server should add the event causing the redaction to the ``unsigned`` property of the redacted event, under the ``redacted_because`` key. When a client receives a redaction event it should change the redacted event in the @@ -1871,15 +1880,15 @@ send update requests to other servers. However, homeservers MUST handle ``GET`` requests to resolve aliases on other servers; they should do this using the federation API if necessary. -Rooms store a *partial* list of room aliases via the ``m.room.aliases`` state -event. This alias list is partial because it cannot guarantee that the alias -list is in any way accurate or up-to-date, as room aliases can point to -different room IDs over time. Crucially, the aliases in this event are -**purely informational** and SHOULD NOT be treated as accurate. They SHOULD -be checked before they are used or shared with another user. If a room -appears to have a room alias of ``#alias:example.com``, this SHOULD be checked -to make sure that the room's ID matches the ``room_id`` returned from the -request. +Rooms do not store a list of all aliases present on a room, though members +of the room with relevant permissions may publish preferred aliases through +the ``m.room.canonical_alias`` state event. The aliases in the state event +should point to the room ID they are published within, however room aliases +can and do drift to other room IDs over time. Clients SHOULD NOT treat the +aliases as accurate. They SHOULD be checked before they are used or shared +with another user. If a room appears to have a room alias of ``#alias:example.com``, +this SHOULD be checked to make sure that the room's ID matches the ``room_id`` +returned from the request. {{directory_cs_http_api}} diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 679eabdc..705fd2d9 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -275,13 +275,9 @@ choose a name: 1. If the room has an `m.room.name`_ state event with a non-empty ``name`` field, use the name given by that field. -#. If the room has an `m.room.canonical_alias`_ state event with a non-empty - ``alias`` field, use the alias given by that field as the name. - -#. If neither of the above conditions are met, the client can optionally guess - an alias from the ``m.room.alias`` events in the room. This is a temporary - measure while clients do not promote canonical aliases as prominently. This - step may be removed in a future version of the specification. +#. If the room has an `m.room.canonical_alias`_ state event with a valid + ``alias`` field, use the alias given by that field as the name. Note that + clients should avoid using ``alt_aliases`` when calculating the room name. #. If none of the above conditions are met, a name should be composed based on the members of the room. Clients should consider `m.room.member`_ events From 2b6086d87c269f4d246b2a9dc22fd7de1f5e792e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 20 May 2020 20:15:09 -0600 Subject: [PATCH 2/4] Add changelog entries It's a bit awkward that this shows up as a backwards compatible change, but it's also not breaking. --- changelogs/client_server/newsfragments/2562.feature | 1 + changelogs/client_server/newsfragments/2562.new | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2562.feature create mode 100644 changelogs/client_server/newsfragments/2562.new diff --git a/changelogs/client_server/newsfragments/2562.feature b/changelogs/client_server/newsfragments/2562.feature new file mode 100644 index 00000000..556018da --- /dev/null +++ b/changelogs/client_server/newsfragments/2562.feature @@ -0,0 +1 @@ +Replaced legacy room alias handling with a more sustainable solution per `MSC2432 `_. diff --git a/changelogs/client_server/newsfragments/2562.new b/changelogs/client_server/newsfragments/2562.new new file mode 100644 index 00000000..c7b3e4ca --- /dev/null +++ b/changelogs/client_server/newsfragments/2562.new @@ -0,0 +1 @@ +Added ``/rooms/{roomId}/aliases`` for retrieving local aliases for a room. From bea6b321a59fb06d255bb2d02862613ca54fe732 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 May 2020 12:37:52 -0600 Subject: [PATCH 3/4] Change the nots order Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- api/client-server/directory.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 67bdf236..7a08faf2 100644 --- a/api/client-server/directory.yaml +++ b/api/client-server/directory.yaml @@ -185,7 +185,7 @@ paths: membership. .. Note:: - Clients are not recommended to display this list of aliases prominently + Clients are recommended not to display this list of aliases prominently as they are not curated, unlike those listed in the ``m.room.canonical_alias`` state event. From 4b64d804374eea4d48185772a5599f9c0201dd8f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 26 May 2020 13:04:04 -0600 Subject: [PATCH 4/4] Remove v6 TODO To avoid the conflict, hopefully. --- specification/client_server_api.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index fda2c106..6060388b 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1820,8 +1820,6 @@ one of the following event types: - ``m.room.aliases`` allows key ``aliases``. - ``m.room.history_visibility`` allows key ``history_visibility``. -.. TODO: Room v6 changes how redaction works in MSC2432 (no special meaning for aliases) - The server should add the event causing the redaction to the ``unsigned`` property of the redacted event, under the ``redacted_because`` key. When a client receives a redaction event it should change the redacted event in the