Merge pull request #2562 from matrix-org/travis/spec/2432-alias-semantics

Add spec for new alias handling (client-server)

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 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.
+
+      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

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

changelogs/client_server/newsfragments/2562.feature

@@ -0,0 +1 @@
+Replaced legacy room alias handling with a more sustainable solution per `MSC2432 <https://github.com/matrix-org/matrix-doc/pull/2432>`_.

changelogs/client_server/newsfragments/2562.new

@@ -0,0 +1 @@
+Added ``/rooms/{roomId}/aliases`` for retrieving local aliases for a room.

event-schemas/examples/m.room.aliases

@@ -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"]
-  }
-}

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"
+    ]
   }
 }

event-schemas/schema/m.room.aliases

@@ -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

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: '^$'

specification/client_server_api.rst

@@ -1614,8 +1614,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}}
@@ -1628,6 +1626,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
 ~~~~~~~
@@ -1891,15 +1898,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}}
 

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