From 1e303b3bbcf46a0be692265d31f4ab6158c6a760 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 6 Jun 2024 12:06:32 +0200 Subject: [PATCH 01/60] Do not require UIA when first uploading cross-signing keys (#1828) As per MSC3967. --- .../client_server/newsfragments/1828.feature | 1 + data/api/client-server/cross_signing.yaml | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1828.feature diff --git a/changelogs/client_server/newsfragments/1828.feature b/changelogs/client_server/newsfragments/1828.feature new file mode 100644 index 00000000..65d7420b --- /dev/null +++ b/changelogs/client_server/newsfragments/1828.feature @@ -0,0 +1 @@ +Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 0f3a46be..8f499d23 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -19,11 +19,26 @@ paths: /keys/device_signing/upload: post: x-addedInMatrixVersion: "1.1" + x-changedInMatrixVersion: + "1.11": UIA is not always required for this endpoint. summary: Upload cross-signing keys. description: |- Publishes cross-signing keys for the user. This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + User-Interactive Authentication MUST be performed, except in these cases: + - there is no existing cross-signing master key uploaded to the homeserver, OR + - there is an existing cross-signing master key and it exactly matches the + cross-signing master key provided in the request body. If there are any additional + keys provided in the request (self-signing key, user-signing key) they MUST also + match the existing keys stored on the server. In other words, the request contains + no new keys. + + This allows clients to freely upload one set of keys, but not modify/overwrite keys if + they already exist. Allowing clients to upload the same set of keys more than once + makes this endpoint idempotent in the case where the response is lost over the network, + which would otherwise cause a UIA challenge upon retry. operationId: uploadCrossSigningKeys security: - accessTokenQuery: [] From 5a86e384dd94298764fa36d5a6b52b12ce5f9cdc Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 7 Jun 2024 10:34:34 +0200 Subject: [PATCH 02/60] Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement (#1846) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1846.clarification | 1 + data/api/client-server/login_token.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1846.clarification diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification new file mode 100644 index 00000000..6f57eb35 --- /dev/null +++ b/changelogs/client_server/newsfragments/1846.clarification @@ -0,0 +1 @@ +Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement. diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index a8ab1248..19fa350e 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -45,7 +45,7 @@ paths: intend to log in multiple devices must generate a token for each. With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt - for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + for verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt the user for verification to ensure explicit consent is gained for each additional client. Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum From 7d5b5065557ab4f5c964a20126f76d34aedc1122 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 7 Jun 2024 18:13:32 +0200 Subject: [PATCH 03/60] Remove extra preposition in room version 11 description of redactions (#1848) Signed-off-by: Johannes Marbach --- changelogs/room_versions/newsfragments/1848.clarification | 1 + content/rooms/v11.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1848.clarification diff --git a/changelogs/room_versions/newsfragments/1848.clarification b/changelogs/room_versions/newsfragments/1848.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1848.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/rooms/v11.md b/content/rooms/v11.md index 782edb3e..d21c76ba 100644 --- a/content/rooms/v11.md +++ b/content/rooms/v11.md @@ -72,7 +72,7 @@ The `redacts` property of `m.room.redaction` events is moved from a top-level event property to a property under the event `content`. For backwards-compatibility with older clients, servers should add a `redacts` property -to the top level of `m.room.redaction` events in when serving such events over the +to the top level of `m.room.redaction` events when serving such events over the Client-Server API. For improved compatibility with newer clients, servers should add a `redacts` property From 1b40a7789b4a28857fd53d19bf43914091b2de24 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 10 Jun 2024 13:26:50 +0200 Subject: [PATCH 04/60] Fix typos around relations recursion (#1853) --- changelogs/client_server/newsfragments/1853.clarification | 1 + content/client-server-api/_index.md | 2 +- data/api/client-server/relations.yaml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1853.clarification diff --git a/changelogs/client_server/newsfragments/1853.clarification b/changelogs/client_server/newsfragments/1853.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1853.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b0ce7289..71f92bec 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2316,7 +2316,7 @@ following endpoint. This endpoint is particularly useful if the client has lost context on the aggregation for a parent event and needs to rebuild/verify it. -When using the `recurse` parameter, note that there no way for a client to +When using the `recurse` parameter, note that there is no way for a client to control how far the server recurses. If the client decides that the server's recursion level is insufficient, it could, for example, perform the recursion itself, or disable whatever feature requires more recursion. diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index b033e88f..3f3d5baa 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -312,7 +312,7 @@ components: Whether to additionally include events which only relate indirectly to the given event, i.e. events related to the given event via two or more direct relationships. - If set to `false`, only events which have direct a relation with the given + If set to `false`, only events which have a direct relation with the given event will be included. If set to `true`, all events which relate to the given event, or relate to From 96057638ce7e7bbde97fec6373d703b5ebe1dff9 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 10 Jun 2024 13:17:27 +0100 Subject: [PATCH 05/60] Spec `unsigned.membership` property, per MSC4115 (#1847) --- .../client_server/newsfragments/1847.feature | 1 + .../client_event_without_room_id.yaml | 21 +++++++++++++++++++ .../examples/core/room_event.json | 3 ++- 3 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1847.feature diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature new file mode 100644 index 00000000..25d1914b --- /dev/null +++ b/changelogs/client_server/newsfragments/1847.feature @@ -0,0 +1 @@ +Add the new `unsigned.membership` property to events served over the client-server API, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml index d78dcc68..b12611a2 100644 --- a/data/api/client-server/definitions/client_event_without_room_id.yaml +++ b/data/api/client-server/definitions/client_event_without_room_id.yaml @@ -90,6 +90,7 @@ properties: "origin_server_ts": 1632491098485, "unsigned": { "age": 1257, + "membership": "leave" } } transaction_id: @@ -112,3 +113,23 @@ properties: this. title: EventContent type: object + membership: + description: | + The room membership of the user making the request, at the time of the event. + + This property is the value of the `membership` property of the + requesting user's [`m.room.member`](/client-server-api#mroommember) + state at the point of the event, including any changes caused by the + event. If the user had yet to join the room at the time of the event + (i.e, they have no `m.room.member` state), this property is set to + `leave`. + + Homeservers SHOULD populate this property + wherever practical, but they MAY omit it if necessary (for example, + if calculating the value is expensive, servers might choose to only + implement it in encrypted rooms). The property is *not* normally populated + in events pushed to application services via the application service transaction API + (where there is no clear definition of "requesting user"). + type: string + example: join + x-addedInMatrixVersion: "1.11" diff --git a/data/event-schemas/examples/core/room_event.json b/data/event-schemas/examples/core/room_event.json index 521225cc..9bd62e28 100644 --- a/data/event-schemas/examples/core/room_event.json +++ b/data/event-schemas/examples/core/room_event.json @@ -5,6 +5,7 @@ "sender": "@example:example.org", "origin_server_ts": 1432735824653, "unsigned": { - "age": 1234 + "age": 1234, + "membership": "join" } } From 57042769819f1fad921f54a8f0cd9ebb112ebb9c Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2024 12:15:01 -0600 Subject: [PATCH 06/60] Fix issue template for releases --- .github/ISSUE_TEMPLATE/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index e46834b9..9093b17c 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -1,6 +1,6 @@ --- name: [SCT] Release checklist -about: Used by the Spec Core Team to create a new release. +description: Used by the Spec Core Team to create a new release. title: 'Matrix 1.X' labels: 'release-blocker' assignees: '' From 0a9ab956bdd65606e4aa70e887144deade27dcd3 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2024 12:16:14 -0600 Subject: [PATCH 07/60] Revert "Fix issue template for releases" This reverts commit 57042769819f1fad921f54a8f0cd9ebb112ebb9c. --- .github/ISSUE_TEMPLATE/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index 9093b17c..e46834b9 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -1,6 +1,6 @@ --- name: [SCT] Release checklist -description: Used by the Spec Core Team to create a new release. +about: Used by the Spec Core Team to create a new release. title: 'Matrix 1.X' labels: 'release-blocker' assignees: '' From 08bc8e8a1f1f12290324e534a920fff054a449d4 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 10 Jun 2024 12:40:31 -0600 Subject: [PATCH 08/60] Fix YAML syntax in SCT release template (#1856) * Fix YAML syntax in SCT release template * changelog --- .github/ISSUE_TEMPLATE/release.md | 4 ++-- changelogs/internal/newsfragments/1856.clarification | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/internal/newsfragments/1856.clarification diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index e46834b9..4128bb9b 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -1,6 +1,6 @@ --- -name: [SCT] Release checklist -about: Used by the Spec Core Team to create a new release. +name: '[SCT] Release checklist' +about: 'Used by the Spec Core Team to create a new release.' title: 'Matrix 1.X' labels: 'release-blocker' assignees: '' diff --git a/changelogs/internal/newsfragments/1856.clarification b/changelogs/internal/newsfragments/1856.clarification new file mode 100644 index 00000000..838b8af5 --- /dev/null +++ b/changelogs/internal/newsfragments/1856.clarification @@ -0,0 +1 @@ +Fix syntax errors in the spec release issue template. \ No newline at end of file From 2f528029c9ff77367b84afa7fce8aa0e3582e3af Mon Sep 17 00:00:00 2001 From: reivilibre Date: Tue, 11 Jun 2024 15:22:12 +0100 Subject: [PATCH 09/60] Note that /logout doesn't take a body (#1644) --- .../client_server/newsfragments/1644.clarification | 1 + content/client-server-api/_index.md | 13 ++++++++++--- 2 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1644.clarification diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification new file mode 100644 index 00000000..78c0919d --- /dev/null +++ b/changelogs/client_server/newsfragments/1644.clarification @@ -0,0 +1 @@ +Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 71f92bec..9a6c6a68 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -22,13 +22,20 @@ recommended outside test environments. Clients are authenticated using opaque `access_token` strings (see [Client Authentication](#client-authentication) for details). -All `POST` and `PUT` endpoints, with the exception of [`POST -/_matrix/media/v3/upload`](#post_matrixmediav3upload) and [`PUT -/_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), +All `POST` and `PUT` endpoints, with the exception of those listed below, require the client to supply a request body containing a (potentially empty) JSON object. Clients should supply a `Content-Type` header of `application/json` for all requests with JSON bodies, but this is not required. +The exceptions are: + +- [`POST /_matrix/media/v3/upload`](#post_matrixmediav3upload) and + [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](#put_matrixmediav3uploadservernamemediaid), + both of which take the uploaded media as the request body. +- [`POST /_matrix/client/v3/logout`](#post_matrixclientv3logout) and + [`POST /_matrix/client/v3/logout/all`](#post_matrixclientv3logoutall), + which take an empty request body. + Similarly, all endpoints require the server to return a JSON object, with the exception of 200 responses to [`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid) From c4b4c896b74a13b0eb0782e7de175f578a9dfe72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 17:59:29 +0200 Subject: [PATCH 10/60] Replace references to RFC7235 and RFC7230 with references to RFC9110 (#1844) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../server_server/newsfragments/1844.clarification | 1 + content/server-server-api.md | 11 +++++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1844.clarification diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification new file mode 100644 index 00000000..81013eb6 --- /dev/null +++ b/changelogs/server_server/newsfragments/1844.clarification @@ -0,0 +1 @@ +Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. \ No newline at end of file diff --git a/content/server-server-api.md b/content/server-server-api.md index e92d871c..365613df 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -349,14 +349,14 @@ def authorization_headers(origin_name, origin_signing_key, ``` The format of the Authorization header is given in -[RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). In +[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In summary, the header begins with authorization scheme `X-Matrix`, followed by one or more spaces, followed by a comma-separated list of parameters written as name=value pairs. Zero or more spaces and tabs around each comma are allowed. The names are case insensitive and order does not matter. The values must be enclosed in quotes if they contain characters that are not allowed in `token`s, as defined in -[RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6); if a +[Section 5.6.2 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2); if a value is a valid `token`, it may or may not be enclosed in quotes. Quoted values may include backslash-escaped characters. When parsing the header, the recipient must unescape the characters. That is, a backslash-character pair is @@ -388,6 +388,13 @@ The authorization parameters to include are: Unknown parameters are ignored. +{{% boxes/note %}} +{{< changed-in v="1.11" >}} +This section used to reference [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1) +and [RFC 7230](https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2), that +were obsoleted by RFC 9110 without changes to the sections of interest here. +{{% /boxes/note %}} + ### Response Authentication Responses are authenticated by the TLS server certificate. A homeserver From acec09f567a7bef7e3ac09df15b13f7ce2c920b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 18:03:53 +0200 Subject: [PATCH 11/60] Do not add empty arrays to examples (#1849) --- changelogs/internal/newsfragments/1849.clarification | 1 + layouts/partials/json-schema/resolve-example.html | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) create mode 100644 changelogs/internal/newsfragments/1849.clarification diff --git a/changelogs/internal/newsfragments/1849.clarification b/changelogs/internal/newsfragments/1849.clarification new file mode 100644 index 00000000..fc7c5d88 --- /dev/null +++ b/changelogs/internal/newsfragments/1849.clarification @@ -0,0 +1 @@ +Do not add empty arrays to examples. diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html index 09b4254e..8fa98400 100644 --- a/layouts/partials/json-schema/resolve-example.html +++ b/layouts/partials/json-schema/resolve-example.html @@ -35,9 +35,9 @@ */}} {{ if reflect.IsMap $this_object.items }} {{ $items_example := partial "json-schema/resolve-example" $this_object.items }} - {{ $example = slice $items_example }} - {{ else }} - {{ $example = slice }} + {{ if $items_example }} + {{ $example = slice $items_example }} + {{ end }} {{ end }} {{ end }} From a7a7eadf2cad1dbe72f41488b3f9bfcb08ea1c37 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 11 Jun 2024 13:02:46 -0400 Subject: [PATCH 12/60] Clarify when an event is returned from /send_join. (#1840) --- changelogs/server_server/newsfragments/1834.clarification | 2 +- changelogs/server_server/newsfragments/1840.clarification | 1 + data/api/server-server/joins-v2.yaml | 6 +++--- 3 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1840.clarification diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification index fa927cca..80c2fa48 100644 --- a/changelogs/server_server/newsfragments/1834.clarification +++ b/changelogs/server_server/newsfragments/1834.clarification @@ -1 +1 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when `join_authorised_via_users_server` was present in the `content` field of the request. +Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1840.clarification b/changelogs/server_server/newsfragments/1840.clarification new file mode 100644 index 00000000..80c2fa48 --- /dev/null +++ b/changelogs/server_server/newsfragments/1840.clarification @@ -0,0 +1 @@ +Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 7804a6f6..465207e9 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -207,9 +207,9 @@ paths: title: SignedMembershipEvent x-addedInMatrixVersion: "1.2" description: |- - Required if the `content` of the event in the request contained the `join_authorised_via_users_server` - field. The signed copy of the membership event sent to other servers by the resident server, - including the resident server's signature. + The membership event sent to other servers by the resident server including a signature + from the resident server. Required if the room is [restricted](/client-server-api/#restricted-rooms) + and the joining user is authorised by one of the conditions. servers_in_room: type: array x-addedInMatrixVersion: "1.6" From 784b8984f36aa3d0317471d858ccbc875a78893e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 11 Jun 2024 23:24:23 +0200 Subject: [PATCH 13/60] Generate ToC with Hugo rather than JavaScript (#1851) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .github/workflows/main.yml | 2 +- .htmltest.yaml | 1 + README.md | 2 +- .../internal/newsfragments/1851.clarification | 1 + config.toml | 6 +- content/client-server-api/_index.md | 78 ++++---- layouts/partials/sidebar-tree.html | 83 +++++++++ layouts/partials/toc.html | 15 ++ layouts/shortcodes/changelog/changelogs.html | 2 +- layouts/shortcodes/cs-module.html | 2 +- static/js/toc.js | 170 ------------------ 11 files changed, 148 insertions(+), 214 deletions(-) create mode 100644 changelogs/internal/newsfragments/1851.clarification create mode 100644 layouts/partials/sidebar-tree.html create mode 100644 layouts/partials/toc.html diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 09a184a7..cb14a0c1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -193,7 +193,7 @@ jobs: - name: "➕ Setup Hugo" uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0 with: - hugo-version: '0.113.0' + hugo-version: '0.117.0' extended: true - name: "📥 Source checkout" uses: actions/checkout@v4 diff --git a/.htmltest.yaml b/.htmltest.yaml index 1563408b..52eedee5 100644 --- a/.htmltest.yaml +++ b/.htmltest.yaml @@ -4,3 +4,4 @@ IgnoreDirectoryMissingTrailingSlash: true DirectoryPath: spec CheckExternal: false +IgnoreInternalEmptyHash: true diff --git a/README.md b/README.md index 17fa5614..a0ba854e 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself. 1. Install the extended version (often the OS default) of Hugo: . Note that at least Hugo - v0.113.0 is required. + v0.117.0 is required. Alternatively, use the Docker image at https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification new file mode 100644 index 00000000..e89777c5 --- /dev/null +++ b/changelogs/internal/newsfragments/1851.clarification @@ -0,0 +1 @@ +Generate ToC with Hugo rather than JavaScript. diff --git a/config.toml b/config.toml index a4245d0b..15003eee 100644 --- a/config.toml +++ b/config.toml @@ -37,6 +37,10 @@ description = "Home of the Matrix specification for decentralised communication" weight = 30 [markup] + [markup.tableOfContents] + startLevel = 2 + endLevel = 6 + ordered = true [markup.goldmark] [markup.goldmark.renderer] # Enables us to render raw HTML @@ -130,7 +134,7 @@ sidebar_menu_compact = true [module] [module.hugoVersion] extended = true - min = "0.113.0" + min = "0.117.0" [[module.imports]] path = "github.com/matrix-org/docsy" disable = false diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9a6c6a68..86dcda1a 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2812,42 +2812,42 @@ operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems. -{{< cs-module name="instant_messaging" >}} -{{< cs-module name="rich_replies" >}} -{{< cs-module name="voip_events" >}} -{{< cs-module name="typing_notifications" >}} -{{< cs-module name="receipts" >}} -{{< cs-module name="read_markers" >}} -{{< cs-module name="presence" >}} -{{< cs-module name="content_repo" >}} -{{< cs-module name="send_to_device" >}} -{{< cs-module name="device_management" >}} -{{< cs-module name="end_to_end_encryption" >}} -{{< cs-module name="secrets" >}} -{{< cs-module name="history_visibility" >}} -{{< cs-module name="push" >}} -{{< cs-module name="third_party_invites" >}} -{{< cs-module name="search" >}} -{{< cs-module name="guest_access" >}} -{{< cs-module name="room_previews" >}} -{{< cs-module name="tags" >}} -{{< cs-module name="account_data" >}} -{{< cs-module name="admin" >}} -{{< cs-module name="event_context" >}} -{{< cs-module name="sso_login" >}} -{{< cs-module name="dm" >}} -{{< cs-module name="ignore_users" >}} -{{< cs-module name="stickers" >}} -{{< cs-module name="report_content" >}} -{{< cs-module name="third_party_networks" >}} -{{< cs-module name="openid" >}} -{{< cs-module name="server_acls" >}} -{{< cs-module name="mentions" >}} -{{< cs-module name="room_upgrades" >}} -{{< cs-module name="server_notices" >}} -{{< cs-module name="moderation_policies" >}} -{{< cs-module name="spaces" >}} -{{< cs-module name="event_replacements" >}} -{{< cs-module name="event_annotations" >}} -{{< cs-module name="threading" >}} -{{< cs-module name="reference_relations" >}} +{{% cs-module name="instant_messaging" %}} +{{% cs-module name="rich_replies" %}} +{{% cs-module name="voip_events" %}} +{{% cs-module name="typing_notifications" %}} +{{% cs-module name="receipts" %}} +{{% cs-module name="read_markers" %}} +{{% cs-module name="presence" %}} +{{% cs-module name="content_repo" %}} +{{% cs-module name="send_to_device" %}} +{{% cs-module name="device_management" %}} +{{% cs-module name="end_to_end_encryption" %}} +{{% cs-module name="secrets" %}} +{{% cs-module name="history_visibility" %}} +{{% cs-module name="push" %}} +{{% cs-module name="third_party_invites" %}} +{{% cs-module name="search" %}} +{{% cs-module name="guest_access" %}} +{{% cs-module name="room_previews" %}} +{{% cs-module name="tags" %}} +{{% cs-module name="account_data" %}} +{{% cs-module name="admin" %}} +{{% cs-module name="event_context" %}} +{{% cs-module name="sso_login" %}} +{{% cs-module name="dm" %}} +{{% cs-module name="ignore_users" %}} +{{% cs-module name="stickers" %}} +{{% cs-module name="report_content" %}} +{{% cs-module name="third_party_networks" %}} +{{% cs-module name="openid" %}} +{{% cs-module name="server_acls" %}} +{{% cs-module name="mentions" %}} +{{% cs-module name="room_upgrades" %}} +{{% cs-module name="server_notices" %}} +{{% cs-module name="moderation_policies" %}} +{{% cs-module name="spaces" %}} +{{% cs-module name="event_replacements" %}} +{{% cs-module name="event_annotations" %}} +{{% cs-module name="threading" %}} +{{% cs-module name="reference_relations" %}} diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html new file mode 100644 index 00000000..f5a34b23 --- /dev/null +++ b/layouts/partials/sidebar-tree.html @@ -0,0 +1,83 @@ +{{/* + + A modified version of the siderbar-tree.html partial in Docsy, adding: + + * The "toc.html" partial at L45. + +*/}} + +{{/* We cache this partial for bigger sites and set the active class client side. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}} +
+ {{ if not .Site.Params.ui.sidebar_search_disable -}} +
+ {{ partial "search-input.html" . }} + +
+ {{ else -}} +
+
+ {{ partial "search-input.html" . }} + +
+
+
+ {{ end -}} + +
+{{ define "section-tree-nav-section" -}} +{{ $s := .section -}} +{{ $p := .page -}} +{{ $shouldDelayActive := .shouldDelayActive -}} +{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}} +{{ $treeRoot := cond (eq .ulNr 0) true false -}} +{{ $ulNr := .ulNr -}} +{{ $ulShow := .ulShow -}} +{{ $active := and (not $shouldDelayActive) (eq $s $p) -}} +{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}} +{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}} +{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}} +{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}} +{{ $pages := $pages_tmp | first $sidebarMenuTruncate -}} +{{ $withChild := gt (len $pages) 0 -}} +{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}} +{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}} +
  • + {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}} + + + {{ else -}} + {{ with $s.Params.Icon}}{{ end }}{{ $s.LinkTitle }} + {{- end }} + {{- if $withChild }} + {{- $ulNr := add $ulNr 1 }} +
      + {{ range $pages -}} + {{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}} + {{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }} + {{- end }} + {{- end }} +
    + {{- end }} +
    • +{{- end }} \ No newline at end of file diff --git a/layouts/partials/toc.html b/layouts/partials/toc.html new file mode 100644 index 00000000..318335f2 --- /dev/null +++ b/layouts/partials/toc.html @@ -0,0 +1,15 @@ +{{/* + + A modified version of the toc.html partial in Docsy. + +*/}} +{{ $page := .Params }} +{{ if not .Params.notoc -}} + {{ with .TableOfContents -}} +
    +
    + {{ $page.Title }} + {{ . }} +
    + {{ end -}} +{{ end -}} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index 78b5932f..f42963da 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -5,6 +5,6 @@ {{ with .Page.Resources.Match "*.md" }} {{ range ((sort . "Params.date" "desc")) }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/cs-module.html b/layouts/shortcodes/cs-module.html index 475ebd48..52c9a5d9 100644 --- a/layouts/shortcodes/cs-module.html +++ b/layouts/shortcodes/cs-module.html @@ -11,6 +11,6 @@ {{ with .Site.GetPage "client-server-api/modules" }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/static/js/toc.js b/static/js/toc.js index 6386e40d..786ec6c6 100644 --- a/static/js/toc.js +++ b/static/js/toc.js @@ -14,174 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. */ -/* -Account for id attributes that are in the sidebar nav -*/ -function populateIds() { - const navItems = document.querySelectorAll(".td-sidebar-nav li"); - return Array.from(navItems).map(item => item.id).filter(id => id != ""); -} - -/* -Given an ID and an array of IDs, return s version of the original ID that's -not equal to any of the IDs in the array. -*/ -function uniquifyHeadingId(id, uniqueIDs) { - const baseId = id; - let counter = 0; - while (uniqueIDs.includes(id)) { - counter = counter + 1; - id = baseId + "-" + counter.toString(); - } - return id; -} - -/* -Given an array of heading nodes, ensure they all have unique IDs. - -We have to do this mostly because of client-server modules, which are -rendered separately then glued together with a template. -Because heading IDs are generated in rendering, this means they can and will -end up with duplicate IDs. -*/ -function uniquifyHeadingIds(headings) { - const uniqueIDs = populateIds(); - for (let heading of headings) { - const uniqueID = uniquifyHeadingId(heading.id, uniqueIDs); - uniqueIDs.push(uniqueID); - heading.id = uniqueID; - } -} - -/* -The document contains "normal" headings, and these have corresponding items -in the ToC. - -The document might also contain H1 headings that act as titles for blocks of -rendered data, like HTTP APIs or event schemas. Unlike "normal" headings, -these headings don't appear in the ToC. But they do have anchor IDs to enable -links to them. When someone follows a link to one of these "rendered data" -headings we want to scroll the ToC to the item corresponding to the "normal" -heading preceding the "rendered data" heading we have visited. - -To support this we need to add `data` attributes to ToC items. -These attributes identify which "rendered data" headings live underneath -the heading corresponding to that ToC item. -*/ -function setTocItemChildren(toc, headings) { - let tocEntryForHeading = null; - for (const heading of headings) { - // H1 headings are rendered-data headings - if (heading.tagName !== "H1") { - tocEntryForHeading = document.querySelector(`nav li a[href="#${heading.id}"]`); - } else { - // on the ToC entry for the parent heading, - // set a data-* attribute whose name is the child's fragment ID - tocEntryForHeading.setAttribute(`data-${heading.id}`, "true"); - } - } -} - -/* -Generate a table of contents based on the headings in the document. -*/ -function makeToc() { - - // make the title from the H1 - const h1 = document.body.querySelector("h1"); - const title = document.createElement("a"); - title.id = "toc-title"; - title.setAttribute("href", "#"); - title.textContent = h1.textContent; - - // make the content - const content = document.body.querySelector(".td-content"); - let headings = [].slice.call(content.querySelectorAll("h2, h3, h4, h5, h6, .rendered-data > details > summary > h1")); - - // exclude headings that don't have IDs. - headings = headings.filter(heading => heading.id); - uniquifyHeadingIds(headings); - - // exclude .rendered-data > h1 headings from the ToC - const tocTargets = headings.filter(heading => heading.tagName !== "H1"); - - // we have to adjust heading IDs to ensure that they are unique - const nav = document.createElement("nav"); - nav.id = "TableOfContents"; - - const section = makeTocSection(tocTargets, 0); - nav.appendChild(section.content); - // build the TOC and append to it title and content - const toc = document.createElement("div"); - toc.id = "toc"; - toc.appendChild(title); - toc.appendChild(nav); - - // append TOC to the section navigation - const section_nav = document.body.querySelector("#td-section-nav"); - let hr = document.createElement("hr"); - section_nav.appendChild(hr); - section_nav.appendChild(toc); - - // tell ToC items about any rendered-data headings they contain - setTocItemChildren(section.content, headings); -} - -// create a single ToC entry -function makeTocEntry(heading) { - const li = document.createElement("li"); - const a = document.createElement("a"); - a.setAttribute("href", `#${heading.id}`); - a.textContent = heading.textContent; - li.appendChild(a); - return li; -} - -/* -Each ToC section is an `
      ` element. -ToC entries are `
    1. ` elements and these contain nested ToC sections, -whenever we go to the next heading level down. -*/ -function makeTocSection(headings, index) { - const ol = document.createElement("ol"); - let previousHeading = null; - let previousLi = null; - let i = index; - const lis = []; - for (i; i < headings.length; i++) { - const thisHeading = headings[i]; - if (previousHeading && (thisHeading.tagName > previousHeading.tagName)) { - // we are going down a heading level, create a new nested section - const section = makeTocSection(headings, i); - previousLi.appendChild(section.content); - i = section.index -1; - } - else if (previousHeading && (previousHeading.tagName > thisHeading.tagName)) { - // we have come back up a level, so a section is finished - for (let li of lis) { - ol.appendChild(li); - } - return { - content: ol, - index: i - } - } - else { - // we are still processing this section, so add this heading to the current section - previousLi = makeTocEntry(thisHeading); - lis.push(previousLi); - previousHeading = thisHeading; - } - } - for (let li of lis) { - ol.appendChild(li); - } - return { - content: ol, - index: i - } -} - /* Set a new ToC entry. Clear any previously highlighted ToC items, set the new one, @@ -303,8 +135,6 @@ for the corresponding ToC entry. */ window.addEventListener('DOMContentLoaded', () => { - makeToc(); - const toc = document.querySelector("#toc"); toc.addEventListener("click", event => { if (event.target.tagName === "A") { From 520b8398d86e8211f237ca0e8c0ef46915bdf9e3 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 11 Jun 2024 23:36:24 +0200 Subject: [PATCH 14/60] Add missing word header (#1852) * Add missing word header Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1852.clarification | 1 + content/client-server-api/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1852.clarification diff --git a/changelogs/client_server/newsfragments/1852.clarification b/changelogs/client_server/newsfragments/1852.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1852.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 86dcda1a..126a5103 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -234,7 +234,7 @@ return a standard error response of the form: ``` Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) -for any response with a 429 status code. +header for any response with a 429 status code. The `retry_after_ms` property MAY be included to tell the client how long they have to wait in milliseconds before they can try again. This property is From da3e884aaa388c246944262038f4229d2d354641 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Tue, 11 Jun 2024 17:42:46 -0400 Subject: [PATCH 15/60] Fix broken link to push rule condition kinds. (#1841) --- changelogs/client_server/newsfragments/1841.clarification | 1 + data/api/client-server/definitions/push_condition.yaml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1841.clarification diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification new file mode 100644 index 00000000..faf8aae9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1841.clarification @@ -0,0 +1 @@ +Fix broken link to push rule condition kinds. diff --git a/data/api/client-server/definitions/push_condition.yaml b/data/api/client-server/definitions/push_condition.yaml index 4c35cfe4..1e7a8583 100644 --- a/data/api/client-server/definitions/push_condition.yaml +++ b/data/api/client-server/definitions/push_condition.yaml @@ -18,7 +18,7 @@ properties: kind: type: string description: |- - The kind of condition to apply. See [conditions](/client-server-api/#conditions) for + The kind of condition to apply. See [conditions](/client-server-api/#conditions-1) for more information on the allowed kinds and how they work. key: type: string From 3517846916c83aac01bfcbfd763fd118230d4b87 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 12 Jun 2024 03:38:33 +0200 Subject: [PATCH 16/60] Add missing modules to feature profiles (#1860) * Add missing modules to feature profiles Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1860.clarification | 1 + content/client-server-api/_index.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1860.clarification diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification new file mode 100644 index 00000000..ca6e4117 --- /dev/null +++ b/changelogs/client_server/newsfragments/1860.clarification @@ -0,0 +1 @@ +Add missing secrets, third-party invites and room tagging modules to feature profiles table. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 126a5103..851c64cb 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2764,6 +2764,9 @@ that profile. | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | | [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | +| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Room Tagging](#room-tagging) | Optional | Optional | Optional | Optional | Optional | *Please see each module for more details on what clients need to implement.* From 7916032a787b4e7bbbb163ff9da2fb5d965514d2 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 12 Jun 2024 10:11:07 +0200 Subject: [PATCH 17/60] Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes (#1850) Fixes: #1826 Relates to: #1001 Signed-off-by: Johannes Marbach --- .../appendices/newsfragments/1850.clarification | 1 + .../client_server/newsfragments/1850.clarification | 1 + content/appendices.md | 13 +++++++++---- content/client-server-api/_index.md | 9 ++++----- 4 files changed, 15 insertions(+), 9 deletions(-) create mode 100644 changelogs/appendices/newsfragments/1850.clarification create mode 100644 changelogs/client_server/newsfragments/1850.clarification diff --git a/changelogs/appendices/newsfragments/1850.clarification b/changelogs/appendices/newsfragments/1850.clarification new file mode 100644 index 00000000..cc200bdf --- /dev/null +++ b/changelogs/appendices/newsfragments/1850.clarification @@ -0,0 +1 @@ +Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/client_server/newsfragments/1850.clarification b/changelogs/client_server/newsfragments/1850.clarification new file mode 100644 index 00000000..cc200bdf --- /dev/null +++ b/changelogs/client_server/newsfragments/1850.clarification @@ -0,0 +1 @@ +Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/content/appendices.md b/content/appendices.md index 9c7cf82a..f9dbb455 100644 --- a/content/appendices.md +++ b/content/appendices.md @@ -556,7 +556,7 @@ The `domain` of a user ID is the [server name](#server-name) of the homeserver which allocated the account. The length of a user ID, including the `@` sigil and the domain, MUST -NOT exceed 255 characters. +NOT exceed 255 bytes. The complete grammar for a legal user ID is: @@ -663,6 +663,9 @@ Room IDs are case-sensitive. They are not meant to be human-readable. They are intended to be treated as fully opaque strings by clients. +The length of a room ID, including the `!` sigil and the domain, MUST +NOT exceed 255 bytes. + #### Room Aliases A room may have zero or more aliases. A room alias has the format: @@ -673,8 +676,8 @@ The `domain` of a room alias is the [server name](#server-name) of the homeserver which created the alias. Other servers may contact this homeserver to look up the alias. -Room aliases MUST NOT exceed 255 bytes (including the `#` sigil and the -domain). +The length of a room alias, including the `#` sigil and the domain, MUST +NOT exceed 255 bytes. #### Event IDs @@ -686,10 +689,12 @@ However, the precise format depends upon the [room version specification](/rooms): early room versions included a `domain` component, whereas more recent versions omit the domain and use a base64-encoded hash instead. +In addition to the requirements of the room version, the length of an event ID, +including the `$` sigil and the domain where present, MUST NOT exceed 255 bytes. + Event IDs are case-sensitive. They are not meant to be human-readable. They are intended to be treated as fully opaque strings by clients. - ### URIs There are two major kinds of referring to a resource in Matrix: matrix.to diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 851c64cb..c2c01465 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1849,16 +1849,15 @@ updates not being sent. The complete event MUST NOT be larger than 65536 bytes, when formatted with the [federation event format](#room-event-format), including any -signatures, and encoded as [Canonical -JSON](/appendices#canonical-json). +signatures, and encoded as [Canonical JSON](/appendices#canonical-json). There are additional restrictions on sizes per key: -- `sender` MUST NOT exceed 255 bytes (including domain). -- `room_id` MUST NOT exceed 255 bytes. +- `sender` MUST NOT exceed the size limit for [user IDs](/appendices/#user-identifiers). +- `room_id` MUST NOT exceed the size limit for [room IDs](/appendices/#room-ids). - `state_key` MUST NOT exceed 255 bytes. - `type` MUST NOT exceed 255 bytes. -- `event_id` MUST NOT exceed 255 bytes. +- `event_id` MUST NOT exceed the size limit for [event IDs](/appendices/#event-ids). Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other From eb49b28ea9f0182931d5dab36492acff188a81e1 Mon Sep 17 00:00:00 2001 From: davidegirardi <16451191+davidegirardi@users.noreply.github.com> Date: Wed, 12 Jun 2024 15:14:37 +0200 Subject: [PATCH 18/60] Use environment variables in workflow (#1865) * Use environment variables in workflow * Add newsfragment --- .github/workflows/netlify.yaml | 5 ++++- changelogs/internal/newsfragments/1865.clarification | 1 + 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1865.clarification diff --git a/.github/workflows/netlify.yaml b/.github/workflows/netlify.yaml index 889d6eed..7c59f64c 100644 --- a/.github/workflows/netlify.yaml +++ b/.github/workflows/netlify.yaml @@ -25,8 +25,11 @@ jobs: id: readctx # we need to find the PR number that corresponds to the branch, which we do by # searching the GH API + env: + OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }} + HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }} run: | - head_branch='${{github.event.workflow_run.head_repository.owner.login}}:${{github.event.workflow_run.head_branch}}' + head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}" echo "head branch: $head_branch" pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)" pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" | diff --git a/changelogs/internal/newsfragments/1865.clarification b/changelogs/internal/newsfragments/1865.clarification new file mode 100644 index 00000000..f50be96f --- /dev/null +++ b/changelogs/internal/newsfragments/1865.clarification @@ -0,0 +1 @@ +Use environment variables for Netlify build job. From cd8ce97563205ea950b67c95a22d860638205df7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 12 Jun 2024 22:17:37 +0100 Subject: [PATCH 19/60] Minor clarifications to the "end-to-end encryption" module (#1863) --- changelogs/client_server/newsfragments/1863.clarification | 1 + .../client-server-api/modules/end_to_end_encryption.md | 8 +++++--- 2 files changed, 6 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1863.clarification diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification new file mode 100644 index 00000000..d054d41d --- /dev/null +++ b/changelogs/client_server/newsfragments/1863.clarification @@ -0,0 +1 @@ +Minor clarifications to the "end-to-end encryption" module. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 1b3bd7b3..c3a801f9 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1530,9 +1530,11 @@ claiming to have sent messages which they didn't. `sender` must correspond to the user who sent the event, `recipient` to the local user, and `recipient_keys` to the local ed25519 key. -Clients must confirm that the `sender_key` and the `ed25519` field value -under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientv3keysquery) for -the given user, and must also verify the signature of the keys from the +Clients must confirm that the `sender_key` property in the cleartext +`m.room.encrypted` event body, and the `keys.ed25519` property in the +decrypted plaintext, match the keys returned by +[`/keys/query`](#post_matrixclientv3keysquery) for +the given user. Clients must also verify the signature of the keys from the `/keys/query` response. Without this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm payload. This is crucial when the ed25519 key corresponds From 4a280bcd87ae233f0e4e923dea8d5fd1f4b5317e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 12 Jun 2024 22:48:50 +0100 Subject: [PATCH 20/60] Clarifications around encoding of data within verification QR codes (#1839) --- .../newsfragments/1839.clarification | 1 + .../modules/end_to_end_encryption.md | 26 ++++++++++++------- 2 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1839.clarification diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification new file mode 100644 index 00000000..eea109b1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1839.clarification @@ -0,0 +1 @@ +Specify the encoding to be used when generating QR codes for device verification. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index c3a801f9..5787205a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1179,10 +1179,16 @@ The process between Alice and Bob verifying each other would be: ###### QR code format -The QR codes to be displayed and scanned using this format will encode binary -strings in the general form: +The QR codes to be displayed and scanned MUST be +compatible with [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) and +contain a single segment that uses the byte mode encoding. -- the ASCII string `MATRIX` +The error correction level can be chosen by the device displaying the QR code. + +The binary segment MUST be of the following form: + +- the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`, + `0x41`, `0x54`, `0x52`, `0x49`, `0x58`) - one byte indicating the QR code version (must be `0x02`) - one byte indicating the QR code verification mode. Should be one of the following values: @@ -1194,23 +1200,23 @@ strings in the general form: request event, encoded as: - two bytes in network byte order (big-endian) indicating the length in bytes of the ID as a UTF-8 string - - the ID as a UTF-8 string + - the ID encoded as a UTF-8 string - the first key, as 32 bytes. The key to use depends on the mode field: - if `0x00` or `0x01`, then the current user's own master cross-signing public key - if `0x02`, then the current device's Ed25519 signing key - the second key, as 32 bytes. The key to use depends on the mode field: - if `0x00`, then what the device thinks the other user's master - cross-signing key is + cross-signing public key is - if `0x01`, then what the device thinks the other device's Ed25519 signing + public key is + - if `0x02`, then what the device thinks the user's master cross-signing public key is - - if `0x02`, then what the device thinks the user's master cross-signing key - is -- a random shared secret, as a byte string. It is suggested to use a secret +- a random shared secret, as a sequence of bytes. It is suggested to use a secret that is about 8 bytes long. Note: as we do not share the length of the secret, and it is not a fixed size, clients will just use the remainder of - binary string as the shared secret. + binary segment as the shared secret. -For example, if Alice displays a QR code encoding the following binary string: +For example, if Alice displays a QR code encoding the following binary data: ``` "MATRIX" |ver|mode| len | event ID From 7a51ae879c4c9274c638d19cd36eda630eb75e41 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Jun 2024 12:08:27 -0600 Subject: [PATCH 21/60] Add authenticated media (MSC3916) (#1858) * C2S: Deprecate now-legacy endpoints * C2S: Fix MXC URI code block while we're here * C2S: Describe the authentication and deprecation requirements * C2S: Intro the upload/download endpoints differently * C2S: Literally copy/paste the `content-repo.yaml` spec * C2S: Drop `/upload` and `/create` because we aren't replacing them today * C2S: Fix notes while we're here * C2S: Update metadata for new endpoints * C2S: Add authentication to new endpoints * C2S: Drop `allow_remote` and `allow_redirect` on new endpoints * C2S: Append backwards compatibility notes * C2S: Decorate old media endpoints with pointers to the new ones The server-server spec might have a harder time linking to these, but that can be fixed with verbiage. * C2S: Annotate IdP icon spec with media auth implications * S2S: Modernize section text * S2S: Create content repository API This is largely a copy/paste of the new authed content repo API in the Client-Server API, though some keywords (like "client") have been changed. Paths and response formats have also been changed to support the federation-specific requirements. * C2S & S2S: Add plethora of changelogs * Reference RFC 1341 * Upgrade keywords in changed text * Mention caching * Cross-reference IdP icons * Update content/client-server-api/modules/content_repo.md --- .../newsfragments/1858.deprecation | 1 + .../newsfragments/1858.feature.1 | 1 + .../newsfragments/1858.feature.2 | 1 + .../client_server/newsfragments/1858.new.1 | 1 + .../client_server/newsfragments/1858.new.2 | 1 + .../client_server/newsfragments/1858.new.3 | 1 + .../client_server/newsfragments/1858.new.4 | 1 + .../client_server/newsfragments/1858.new.5 | 1 + .../newsfragments/1858.deprecation | 1 + .../server_server/newsfragments/1858.feature | 1 + .../server_server/newsfragments/1858.new.1 | 1 + .../server_server/newsfragments/1858.new.2 | 1 + content/client-server-api/_index.md | 5 +- .../client-server-api/modules/content_repo.md | 58 +- content/server-server-api.md | 23 +- .../client-server/authed-content-repo.yaml | 518 ++++++++++++++++++ data/api/client-server/content-repo.yaml | 51 +- .../definitions/sso_login_flow.yaml | 12 + .../api/server-server/content_repository.yaml | 303 ++++++++++ 19 files changed, 967 insertions(+), 15 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1858.deprecation create mode 100644 changelogs/client_server/newsfragments/1858.feature.1 create mode 100644 changelogs/client_server/newsfragments/1858.feature.2 create mode 100644 changelogs/client_server/newsfragments/1858.new.1 create mode 100644 changelogs/client_server/newsfragments/1858.new.2 create mode 100644 changelogs/client_server/newsfragments/1858.new.3 create mode 100644 changelogs/client_server/newsfragments/1858.new.4 create mode 100644 changelogs/client_server/newsfragments/1858.new.5 create mode 100644 changelogs/server_server/newsfragments/1858.deprecation create mode 100644 changelogs/server_server/newsfragments/1858.feature create mode 100644 changelogs/server_server/newsfragments/1858.new.1 create mode 100644 changelogs/server_server/newsfragments/1858.new.2 create mode 100644 data/api/client-server/authed-content-repo.yaml create mode 100644 data/api/server-server/content_repository.yaml diff --git a/changelogs/client_server/newsfragments/1858.deprecation b/changelogs/client_server/newsfragments/1858.deprecation new file mode 100644 index 00000000..6e93dca5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.deprecation @@ -0,0 +1 @@ +Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.1 b/changelogs/client_server/newsfragments/1858.feature.1 new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.feature.1 @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.2 b/changelogs/client_server/newsfragments/1858.feature.2 new file mode 100644 index 00000000..63dfbb78 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.feature.2 @@ -0,0 +1 @@ +Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.1 b/changelogs/client_server/newsfragments/1858.new.1 new file mode 100644 index 00000000..9d02447f --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.1 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.2 b/changelogs/client_server/newsfragments/1858.new.2 new file mode 100644 index 00000000..07e7763a --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.2 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.3 b/changelogs/client_server/newsfragments/1858.new.3 new file mode 100644 index 00000000..49b67f04 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.3 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.4 b/changelogs/client_server/newsfragments/1858.new.4 new file mode 100644 index 00000000..dda53b33 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.4 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.5 b/changelogs/client_server/newsfragments/1858.new.5 new file mode 100644 index 00000000..021b4023 --- /dev/null +++ b/changelogs/client_server/newsfragments/1858.new.5 @@ -0,0 +1 @@ +[`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.deprecation b/changelogs/server_server/newsfragments/1858.deprecation new file mode 100644 index 00000000..fd3d2576 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.deprecation @@ -0,0 +1 @@ +Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.feature b/changelogs/server_server/newsfragments/1858.feature new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.feature @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.1 b/changelogs/server_server/newsfragments/1858.new.1 new file mode 100644 index 00000000..e50d5fd1 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.new.1 @@ -0,0 +1 @@ +[`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.2 b/changelogs/server_server/newsfragments/1858.new.2 new file mode 100644 index 00000000..1da2a693 --- /dev/null +++ b/changelogs/server_server/newsfragments/1858.new.2 @@ -0,0 +1 @@ +[`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index c2c01465..3e8a8670 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -37,9 +37,8 @@ The exceptions are: which take an empty request body. Similarly, all endpoints require the server to return a JSON object, -with the exception of 200 responses to -[`GET /_matrix/media/v3/download/{serverName}/{mediaId}`](#get_matrixmediav3downloadservernamemediaid) -and [`GET /_matrix/media/v3/thumbnail/{serverName}/{mediaId}`](#get_matrixmediav3thumbnailservernamemediaid). +with the exception of 200 responses to the media download endpoints in the +[Content Repository module](#content-repository). Servers must include a `Content-Type` header of `application/json` for all JSON responses. All JSON data, in requests or responses, must be encoded using UTF-8. diff --git a/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index cef70b3d..a0138156 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a interacting with the media repository. {{% /boxes/added-in-paragraph %}} +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been +deprecated in favour of newer, authenticated, ones. This change includes updating +the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`, +with the exception of the `/upload` and `/create` endpoints. The upload/create +endpoints are expected to undergo a similar transition in a later version of the +specification. +{{% /boxes/added-in-paragraph %}} + #### Matrix Content (`mxc://`) URIs Content locations are represented as Matrix Content (`mxc://`) URIs. They look like: - mxc:/// +``` +mxc:/// - : The name of the homeserver where this content originated, e.g. matrix.org - : An opaque ID which identifies the content. + : The name of the homeserver where this content originated, e.g. matrix.org + : An opaque ID which identifies the content. +``` -#### Client behaviour +#### Client behaviour {id="content-repo-client-behaviour"} -Clients can upload and download content using the following HTTP APIs. +Clients can access the content repository using the following endpoints. + +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints +described below. Instead, they SHOULD use the new endpoints which require authentication. +{{% /boxes/added-in-paragraph %}} + +{{% boxes/warning %}} +By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints +to prevent newly-uploaded media from being downloaded. This SHOULD mean that any +media uploaded *before* the freeze remains accessible via the deprecated endpoints, +and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible +through the new, authenticated, endpoints. For remote media, "newly-uploaded" is +determined by the date the cache was populated. This may mean the media is older +than the freeze, but because the server had to re-download it, it is now considered +"new". + +Clients SHOULD update to support the authenticated endpoints before servers freeze +unauthenticated access. + +Servers SHOULD consider their local ecosystem impact before enacting a freeze. +This could mean ensuring their users' typical clients support the new endpoints +when available, or updating bridges to start using media proxies. + +In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema) +from the freeze. See the `m.login.sso` flow schema for details. + +An *example* timeline for a server may be: + +* Matrix 1.11 release: Clients begin supporting authenticated media. +* Matrix 1.12 release: Servers freeze unauthenticated media access. + * Media uploaded prior to this point still works with the deprecated endpoints. + * Newly uploaded (or cached) media *only* works on the authenticated endpoints. + +Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter. +{{% /boxes/warning %}} + +{{% http-api spec="client-server" api="authed-content-repo" %}} {{% http-api spec="client-server" api="content-repo" %}} diff --git a/content/server-server-api.md b/content/server-server-api.md index 365613df..9e92bfd9 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1196,15 +1196,26 @@ using the following EDU: Attachments to events (images, files, etc) are uploaded to a homeserver via the Content Repository described in the [Client-Server -API](/client-server-api). When a server wishes +API](/client-server-api/#content-repository). When a server wishes to serve content originating from a remote server, it needs to ask the remote server for the media. -Servers should use the server described in the Matrix Content URI, which -has the format `mxc://{ServerName}/{MediaID}`. Servers should use the -download endpoint described in the [Client-Server -API](/client-server-api), being sure to use -the `allow_remote` parameter (set to `false`). +Servers MUST use the server described in the [Matrix Content URI](/client-server-api/#matrix-content-mxc-uris). +Formatted as `mxc://{ServerName}/{MediaID}`, servers MUST download the media from +`ServerName` using the below endpoints. + +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} Servers were previously advised to use the `/_matrix/media/*` +endpoints described by the [Content Repository module in the Client-Server API](/client-server-api/#content-repository), +however, those endpoints have been deprecated. New endpoints are introduced which +require authentication. Naturally, as a server is not a user, they cannot provide +the required access token to those endpoints. Instead, servers MUST try the endpoints +described below before falling back to the deprecated `/_matrix/media/*` endpoints +when they receive a `404 M_UNRECOGNIZED` error. When falling back, servers MUST +be sure to set `allow_remote` to `false`. +{{% /boxes/added-in-paragraph %}} + +{{% http-api spec="server-server" api="content_repository" %}} ## Server Access Control Lists (ACLs) diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml new file mode 100644 index 00000000..9741d618 --- /dev/null +++ b/data/api/client-server/authed-content-repo.yaml @@ -0,0 +1,518 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019-2024 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. +openapi: 3.1.0 +info: + title: Matrix Client-Server (Authenticated) Content Repository API + version: 1.0.0 +paths: + "/media/download/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository. + description: |- + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: The name of the file that was previously uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/download/{serverName}/{mediaId}/{fileName}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository overriding the file name. + description: |- + This will download content from the content repository (same as + the previous endpoint) but replaces the target file name with the one + provided by the caller. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentOverrideNameAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: path + name: fileName + required: true + description: A filename to give in the `Content-Disposition` header. + example: filename.jpg + schema: + type: string + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: |- + The `fileName` requested or the name of the file that was previously + uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/thumbnail/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentThumbnailAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: query + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: method + description: |- + The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) + section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale + - $ref: '#/components/parameters/timeout_ms' + - in: query + name: animated + x-addedInMatrixVersion: "1.11" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server should behave as though `animated` is `false`. + example: false + schema: + type: boolean + responses: + "200": + description: A thumbnail of the requested content. + headers: + Content-Type: + description: The content type of the thumbnail. + schema: + type: string + enum: + - image/jpeg + - image/png + - image/apng + - image/gif + - image/webp + content: + image/jpeg: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + image/png: + schema: + x-changedInMatrixVersion: + "1.11": The PNG may be of the APNG variety if animation is supported and requested. + description: | + **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated + format if `animated=true`. + image/apng: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/gif: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/webp: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + "307": + $ref: '#/components/responses/thumbnailRedirect' + "308": + $ref: '#/components/responses/thumbnailRedirect' + "400": + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the client requested non-integer dimensions or asked + for negatively-sized images. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + /media/preview_url: + get: + x-addedInMatrixVersion: "1.11" + summary: Get information about a URL for a client + description: |- + Get information about a URL for the client. Typically this is called when a + client sees a URL in a message and wants to render a preview for the user. + + {{% boxes/note %}} + Clients should consider avoiding this endpoint for URLs posted in encrypted + rooms. Encrypted rooms often contain more sensitive information the users + do not want to share with the homeserver, and this can mean that the URLs + being shared should also not be shared with the homeserver. + {{% /boxes/note %}} + operationId: getUrlPreviewAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - in: query + name: url + description: The URL to get a preview of. + required: true + example: https://matrix.org + schema: + type: string + format: uri + - in: query + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + example: 1510610716656 + schema: + type: integer + format: int64 + responses: + "200": + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + content: + application/json: + schema: + type: object + properties: + matrix:image:size: + type: integer + format: int64 + description: The byte-size of the image. Omitted if there is no image attached. + og:image: + type: string + format: uri + description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the image. Omitted if there is no image. + examples: + response: + value: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media + /media/config: + get: + x-addedInMatrixVersion: "1.11" + summary: Get the configuration for the content repository. + description: |- + This endpoint allows clients to retrieve the configuration of the content + repository, such as upload limitations. + Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. + + {{% boxes/note %}} + Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. + {{% /boxes/note %}} + operationId: getConfigAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: The public content repository configuration for the matrix server. + content: + application/json: + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + response: + value: { + "m.upload.size": 50000000 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer + parameters: + serverName: + in: path + name: serverName + required: true + description: | + The server name from the `mxc://` URI (the authority component). + example: matrix.org + schema: + type: string + format: mx-server-name + mediaId: + in: path + name: mediaId + required: true + description: | + The media ID from the `mxc://` URI (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string + timeout_ms: + in: query + name: timeout_ms + x-addedInMatrixVersion: "1.7" + description: | + The maximum number of milliseconds that the client is willing to wait to + start receiving data, in the case that the content has not yet been + uploaded. The default value is 20000 (20 seconds). The content + repository can and should impose a maximum value for this parameter. The + content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 + responses: + rateLimited: + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + notYetUploaded: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } + downloadRedirect: + description: A redirect to the requested content. + headers: + Location: + description: The URL of the content. + schema: + type: string + format: uri + downloadTooLarge: + description: The content is too large for the server to serve. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + thumbnailRedirect: + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string + format: uri + headers: + downloadContentType: + description: The content type of the file that was previously uploaded. + schema: + type: string + diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index e6d55b51..1dac8b10 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -217,7 +217,20 @@ paths: - Media "/media/v3/download/{serverName}/{mediaId}": get: + deprecated: true summary: Download content from the content repository. + description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) + (requires authentication). + {{% /boxes/note %}} + + {{% boxes/warning %}} + {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND` + for media which exists, but is after the server froze unauthenticated + media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more + information. + {{% /boxes/warning %}} operationId: getContent parameters: - $ref: '#/components/parameters/serverName' @@ -254,11 +267,24 @@ paths: - Media "/media/v3/download/{serverName}/{mediaId}/{fileName}": get: + deprecated: true summary: Download content from the content repository overriding the file name description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) + (requires authentication). + {{% /boxes/note %}} + This will download content from the content repository (same as the previous endpoint) but replace the target file name with the one provided by the caller. + + {{% boxes/warning %}} + {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND` + for media which exists, but is after the server froze unauthenticated + media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more + information. + {{% /boxes/warning %}} operationId: getContentOverrideName parameters: - $ref: '#/components/parameters/serverName' @@ -304,10 +330,23 @@ paths: - Media "/media/v3/thumbnail/{serverName}/{mediaId}": get: + deprecated: true summary: Download a thumbnail of content from the content repository description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) + (requires authentication). + {{% /boxes/note %}} + Download a thumbnail of content from the content repository. See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + + {{% boxes/warning %}} + {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND` + for media which exists, but is after the server froze unauthenticated + media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more + information. + {{% /boxes/warning %}} operationId: getContentThumbnail parameters: - $ref: '#/components/parameters/serverName' @@ -455,8 +494,13 @@ paths: - Media /media/v3/preview_url: get: + deprecated: true summary: Get information about a URL for a client description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url). + {{% /boxes/note %}} + Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user. @@ -525,8 +569,13 @@ paths: - Media /media/v3/config: get: + deprecated: true summary: Get the configuration for the content repository. description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig). + {{% /boxes/note %}} + This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. @@ -625,7 +674,7 @@ components: Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. - + Defaults to `true` if not provided. example: false schema: diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 3b95e664..0996511e 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/data/api/client-server/definitions/sso_login_flow.yaml @@ -53,6 +53,18 @@ properties: description: |- Optional `mxc://` URI to provide an image/icon representing the IdP. Intended to be shown alongside the `name` if provided. + + {{% boxes/note %}} + Clients SHOULD use the deprecated [`/download`](/client-server-api/#get_matrixmediav3downloadservernamemediaid) + and [`/thumbnail`](/client-server-api/#get_matrixmediav3thumbnailservernamemediaid) + endpoints to retrieve this media item because clients will not have + an access token they can authenticate with yet. Servers SHOULD ensure + media used for IdP icons is excluded from the freeze described by the + [Content Repository module's Client Behaviour section](/client-server-api/#content-repo-client-behaviour). + + This may be addressed in the future with proposals like [MSC4148](https://github.com/matrix-org/matrix-spec-proposals/pull/4148), + or removed entirely through the transition to OIDC. + {{% /boxes/note %}} example: "mxc://example.org/abc123" brand: type: string diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml new file mode 100644 index 00000000..6c19d6ec --- /dev/null +++ b/data/api/server-server/content_repository.yaml @@ -0,0 +1,303 @@ +# Copyright 2024 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. +openapi: 3.1.0 +info: + title: Matrix Federation Content Repository API + version: 1.0.0 +paths: + "/media/download/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository. + operationId: getContent + security: + - signedRequest: [] + parameters: + - $ref: '#/components/parameters/mediaId' + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + content: + multipart/mixed: + schema: + # This is a workaround for us not being able to say the response is required. + description: |- + **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + delineating exactly two parts: + + The first part has a `Content-Type` header of `application/json` + and describes the media's metadata, if any. Currently, this will + always be an empty object. + + The second part is either: + + 1. the bytes of the media itself, using `Content-Type` and + `Content-Disposition` headers as appropriate; + 2. or a `Location` header to redirect the caller to where the media + can be retrieved. The URL at `Location` SHOULD have appropriate + `Content-Type` and `Content-Disposition` headers which describe + the media. + + When `Location` is present, servers SHOULD NOT cache the URL. + The remote server may have applied time limits on its validity. + If the caller requires an up-to-date URL, it SHOULD re-request + the media download. + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The content is too large for the server to serve. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to serve" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/thumbnail/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Client-Server API Thumbnails](/client-server-api/#thumbnails) + section for more information. + operationId: getContentThumbnail + security: + - signedRequest: [] + parameters: + - $ref: '#/components/parameters/mediaId' + - in: query + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: method + description: |- + The desired resizing method. See the [Client-Server API Thumbnails](/client-server-api/#thumbnails) + section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale + - $ref: '#/components/parameters/timeout_ms' + - in: query + name: animated + x-addedInMatrixVersion: "1.11" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server should behave as though `animated` is `false`. + example: false + schema: + type: boolean + responses: + "200": + description: A thumbnail of the requested content. + headers: + Content-Type: + description: Must be `multipart/mixed`. + schema: + type: string + content: + multipart/mixed: + schema: + # This is a workaround for us not being able to say the response is required. + description: |- + **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + delineating exactly two parts: + + The first part has a `Content-Type` header of `application/json` + and describes the media's metadata, if any. Currently, this will + always be an empty object. + + The second part is either: + + 1. the bytes of the media itself, using `Content-Type` and + `Content-Disposition` headers as appropriate; + 2. or a `Location` header to redirect the caller to where the media + can be retrieved. The URL at `Location` SHOULD have appropriate + `Content-Type` and `Content-Disposition` headers which describe + the media. + + When `Location` is present, servers SHOULD NOT cache the URL. + The remote server may have applied time limits on its validity. + If the caller requires an up-to-date URL, it SHOULD re-request + the media download. + + {{% boxes/note %}} + The `Content-Type` for the second part SHOULD be one of: + * `image/png` (possibly of the APNG variety) + * `image/apng` + * `image/jpeg` + * `image/gif` + * `image/webp` + {{% /boxes/note %}} + "400": + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the caller requested non-integer dimensions or asked + for negatively-sized images. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8448 + basePath: + default: /_matrix/federation/v1 +components: + securitySchemes: + signedRequest: + $ref: definitions/security.yaml#/signedRequest + parameters: + mediaId: + in: path + name: mediaId + required: true + description: | + The media ID from the `mxc://` URI (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string + timeout_ms: + in: query + name: timeout_ms + x-addedInMatrixVersion: "1.7" + description: | + The maximum number of milliseconds that the client is willing to wait to + start receiving data, in the case that the content has not yet been + uploaded. The default value is 20000 (20 seconds). The content + repository can and should impose a maximum value for this parameter. The + content repository may also choose to respond before the timeout. + example: 5000 + schema: + type: integer + format: int64 + default: 20000 + responses: + rateLimited: + description: This request was rate-limited. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/rate_limited.yaml + notYetUploaded: + description: |- + The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) + will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + content: + application/json: + schema: + # XXX: We should move error definitions into a more generic place. + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_YET_UPLOADED", + "error": "Content has not yet been uploaded" + } + headers: + downloadContentType: + description: |- + Must be `multipart/mixed`. + schema: + type: string From f38b0525690b7fe331b4156e8fde74484097a228 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 13 Jun 2024 12:27:06 -0600 Subject: [PATCH 22/60] Use RFC 2119 keywords across the content repository spec (#1861) * Use RFC 2119 keywords across the content repository spec * changelog --- changelogs/client_server/newsfragments/1861.clarification | 1 + data/api/client-server/authed-content-repo.yaml | 6 +++--- data/api/client-server/content-repo.yaml | 6 +++--- data/api/server-server/content_repository.yaml | 6 +++--- 4 files changed, 10 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1861.clarification diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification new file mode 100644 index 00000000..9d877ff5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1861.clarification @@ -0,0 +1 @@ +Use RFC 2119 keywords more consistently throughout various parts of the specification. \ No newline at end of file diff --git a/data/api/client-server/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml index 9741d618..43cb5881 100644 --- a/data/api/client-server/authed-content-repo.yaml +++ b/data/api/client-server/authed-content-repo.yaml @@ -200,7 +200,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -454,8 +454,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 1dac8b10..038ac618 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -401,7 +401,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -688,8 +688,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml index 6c19d6ec..bd07e252 100644 --- a/data/api/server-server/content_repository.yaml +++ b/data/api/server-server/content_repository.yaml @@ -137,7 +137,7 @@ paths: Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the - server should behave as though `animated` is `false`. + server SHOULD behave as though `animated` is `false`. example: false schema: type: boolean @@ -265,8 +265,8 @@ components: The maximum number of milliseconds that the client is willing to wait to start receiving data, in the case that the content has not yet been uploaded. The default value is 20000 (20 seconds). The content - repository can and should impose a maximum value for this parameter. The - content repository may also choose to respond before the timeout. + repository SHOULD impose a maximum value for this parameter. The + content repository MAY respond before the timeout. example: 5000 schema: type: integer From 672af37cbd2a9b7c78e72e5e847b593154ebc7be Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 13 Jun 2024 20:34:54 +0200 Subject: [PATCH 23/60] Clarify that relations recursion should be capped at a certain depth (#1854) --- .../client_server/newsfragments/1854.clarification | 1 + data/api/client-server/relations.yaml | 9 ++++----- 2 files changed, 5 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1854.clarification diff --git a/changelogs/client_server/newsfragments/1854.clarification b/changelogs/client_server/newsfragments/1854.clarification new file mode 100644 index 00000000..cb996bd6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1854.clarification @@ -0,0 +1 @@ + Clarify that relations recursion should be capped at a certain depth. diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 3f3d5baa..c4b0228c 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -315,11 +315,10 @@ components: If set to `false`, only events which have a direct relation with the given event will be included. - If set to `true`, all events which relate to the given event, or relate to - events that relate to the given event, will be included. - - It is recommended that homeservers traverse at least 3 levels of relationships. - Implementations may perform more but should be careful to not infinitely recurse. + If set to `true`, events which have an indirect relation with the given event + will be included additionally up to a certain depth level. Homeservers SHOULD traverse + at least 3 levels of relationships. Implementations MAY perform more but MUST be careful + to not infinitely recurse. The default value is `false`. schema: From f434fdfba7c1d0f651e9e002bcfdb5ef9224501f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 13 Jun 2024 23:37:07 +0200 Subject: [PATCH 24/60] Replace references to obsolete RFC 1341 with RFC 2046 (#1869) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Replace references to obsolete RFC 1341 with RFC 2046 Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/server_server/newsfragments/1869.feature | 1 + data/api/server-server/content_repository.yaml | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1869.feature diff --git a/changelogs/server_server/newsfragments/1869.feature b/changelogs/server_server/newsfragments/1869.feature new file mode 100644 index 00000000..02b9b51e --- /dev/null +++ b/changelogs/server_server/newsfragments/1869.feature @@ -0,0 +1 @@ +Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml index bd07e252..66439b79 100644 --- a/data/api/server-server/content_repository.yaml +++ b/data/api/server-server/content_repository.yaml @@ -37,7 +37,7 @@ paths: schema: # This is a workaround for us not being able to say the response is required. description: |- - **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1)) delineating exactly two parts: The first part has a `Content-Type` header of `application/json` @@ -154,7 +154,7 @@ paths: schema: # This is a workaround for us not being able to say the response is required. description: |- - **Required.** MUST contain a `boundary` (per [RFC 1341](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html)) + **Required.** MUST contain a `boundary` (per [RFC 2046](https://datatracker.ietf.org/doc/html/rfc2046#section-5.1)) delineating exactly two parts: The first part has a `Content-Type` header of `application/json` From 5f47b9624088a94518b735c90c082bcff762d913 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Fri, 14 Jun 2024 12:34:35 +0100 Subject: [PATCH 25/60] Clarify when server name is used and link to definition (#1862) * Clarify when server name is used and link to definition * Changelog --- changelogs/client_server/newsfragments/1862.clarification | 1 + content/client-server-api/_index.md | 4 ++-- content/client-server-api/modules/sso_login.md | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1862.clarification diff --git a/changelogs/client_server/newsfragments/1862.clarification b/changelogs/client_server/newsfragments/1862.clarification new file mode 100644 index 00000000..021b117c --- /dev/null +++ b/changelogs/client_server/newsfragments/1862.clarification @@ -0,0 +1 @@ +Clarify when server name is used and link to the definition. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 3e8a8670..8b40fe99 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -355,9 +355,9 @@ as per the [CORS](#web-browser-clients) section in this specification. The `.well-known` method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows: -1. Extract the server name from the user's Matrix ID by splitting the +1. Extract the [server name](/appendices/#server-name) from the user's Matrix ID by splitting the Matrix ID at the first colon. -2. Extract the hostname from the server name. +2. Extract the hostname from the server name as described by the [grammar](/appendices/#server-name). 3. Make a GET request to `https://hostname/.well-known/matrix/client`. 1. If the returned status code is 404, then `IGNORE`. 2. If the returned status code is not 200, or the response body is diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 1a46c84d..f50a2eb1 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -123,8 +123,8 @@ authentication is successful, the browser will be redirected to that For example, consider a web-based client at `https://client.example.com`, which wants to initiate SSO login on - the homeserver at `server.example.org`. It does this by storing the - homeserver name in a query parameter for the `redirectUrl`: it + the homeserver with [server name](/appendices/#server-name) `server.example.org`. It does this by storing the + server name in a query parameter for the `redirectUrl`: it redirects to `https://server.example.org/login/sso/redirect?redirectUrl=https://client.example.com?hs=server.example.org`. From 7773716d189b16c1d5fa1dd2bfb8a1685bfb1108 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 14 Jun 2024 16:44:01 +0200 Subject: [PATCH 26/60] Clarify that asynchronous media upload requires authentication (#1872) Fixes: #1554 Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1872.clarification | 1 + data/api/client-server/content-repo.yaml | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1872.clarification diff --git a/changelogs/client_server/newsfragments/1872.clarification b/changelogs/client_server/newsfragments/1872.clarification new file mode 100644 index 00000000..4bcea39e --- /dev/null +++ b/changelogs/client_server/newsfragments/1872.clarification @@ -0,0 +1 @@ +Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 038ac618..d0a6e5bb 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -81,6 +81,9 @@ paths: earlier via [POST /_matrix/media/v1/create](/client-server-api/#post_matrixmediav1create). operationId: uploadContentToMXC x-addedInMatrixVersion: "1.7" + security: + - accessTokenQuery: [] + - accessTokenBearer: [] parameters: - $ref: '#/components/parameters/serverName' description: | From 6dfab46268d68e139255c6cd74260a17cf1f69ab Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 18 Jun 2024 16:20:57 +0200 Subject: [PATCH 27/60] Fix typo in SRV delegation (#1877) Signed-off-by: Johannes Marbach --- changelogs/server_server/newsfragments/1877.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1877.clarification diff --git a/changelogs/server_server/newsfragments/1877.clarification b/changelogs/server_server/newsfragments/1877.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1877.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/content/server-server-api.md b/content/server-server-api.md index 9e92bfd9..5c9bd31e 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -166,7 +166,7 @@ to send. The process overall is as follows: target server must present a valid certificate for ``. 5. If no SRV record is found, an IP address is resolved using CNAME, AAAA - or A records. Requests are then made to the resolve IP address + or A records. Requests are then made to the resolved IP address and a port of 8448, using a `Host` header of ``. The target server must present a valid certificate for ``. From 4e32fca05fd89492a3acb82b7a2a922d155ee824 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 18 Jun 2024 17:59:26 +0200 Subject: [PATCH 28/60] Clarify that an access token is optional on `/account/password` and `/account/deactivate` (#1843) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- changelogs/client_server/newsfragments/1843.clarification | 1 + data/api/client-server/registration.yaml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1843.clarification diff --git a/changelogs/client_server/newsfragments/1843.clarification b/changelogs/client_server/newsfragments/1843.clarification new file mode 100644 index 00000000..7ccfe4a7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1843.clarification @@ -0,0 +1 @@ +Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. \ No newline at end of file diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index afd30459..84aef5b1 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -387,6 +387,7 @@ paths: access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: changePassword @@ -592,6 +593,7 @@ paths: parameter because the homeserver is expected to sign the request to the identity server instead. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: deactivateAccount From 9c46fa3f35f5e1517c401b7654a2faad1fbf65d7 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 19 Jun 2024 21:52:21 -0600 Subject: [PATCH 29/60] Normalize the changelog for Matrix 1.11 --- changelogs/application_service/newsfragments/1810.clarification | 2 +- changelogs/client_server/newsfragments/1644.clarification | 2 +- .../newsfragments/{1755.clarification => 1755.feature} | 0 changelogs/client_server/newsfragments/1757.feature | 2 +- changelogs/client_server/newsfragments/1772.clarification | 1 - changelogs/client_server/newsfragments/1808.clarification | 1 - changelogs/client_server/newsfragments/1808.deprecation | 1 + changelogs/client_server/newsfragments/1813.clarification | 2 +- .../newsfragments/{1816.clarification => 1816.feature} | 0 changelogs/client_server/newsfragments/1841.clarification | 2 +- changelogs/client_server/newsfragments/1846.clarification | 2 +- changelogs/client_server/newsfragments/1847.feature | 2 +- changelogs/client_server/newsfragments/1861.clarification | 2 +- changelogs/client_server/newsfragments/1863.clarification | 2 +- changelogs/identity_service/newsfragments/1772.clarification | 1 - changelogs/identity_service/newsfragments/1808.clarification | 1 - changelogs/identity_service/newsfragments/1808.deprecation | 1 + changelogs/internal/newsfragments/1769.clarification | 2 +- changelogs/internal/newsfragments/1770.clarification | 2 +- changelogs/internal/newsfragments/1771.clarification | 2 +- .../newsfragments/1772.clarification | 0 changelogs/internal/newsfragments/1781.clarification | 2 +- changelogs/internal/newsfragments/1786.clarification | 2 +- .../internal/newsfragments/{1793.misc => 1793.clarification} | 0 changelogs/internal/newsfragments/1803.clarification | 2 +- changelogs/internal/newsfragments/1804.clarification | 2 +- changelogs/internal/newsfragments/1813.clarification | 1 + .../newsfragments/1822.clarification | 0 changelogs/room_versions/newsfragments/1827.clarification | 2 +- changelogs/server_server/newsfragments/1772.clarification | 1 - changelogs/server_server/newsfragments/1813.clarification | 2 +- 31 files changed, 21 insertions(+), 23 deletions(-) rename changelogs/client_server/newsfragments/{1755.clarification => 1755.feature} (100%) delete mode 100644 changelogs/client_server/newsfragments/1772.clarification delete mode 100644 changelogs/client_server/newsfragments/1808.clarification create mode 100644 changelogs/client_server/newsfragments/1808.deprecation rename changelogs/client_server/newsfragments/{1816.clarification => 1816.feature} (100%) delete mode 100644 changelogs/identity_service/newsfragments/1772.clarification delete mode 100644 changelogs/identity_service/newsfragments/1808.clarification create mode 100644 changelogs/identity_service/newsfragments/1808.deprecation rename changelogs/{application_service => internal}/newsfragments/1772.clarification (100%) rename changelogs/internal/newsfragments/{1793.misc => 1793.clarification} (100%) create mode 100644 changelogs/internal/newsfragments/1813.clarification rename changelogs/{client_server => internal}/newsfragments/1822.clarification (100%) delete mode 100644 changelogs/server_server/newsfragments/1772.clarification diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification index 66dab495..fd21375c 100644 --- a/changelogs/application_service/newsfragments/1810.clarification +++ b/changelogs/application_service/newsfragments/1810.clarification @@ -1 +1 @@ -Clarify that appservices should be notified of events relating to the sender_localpart user. +Clarify that appservices should be notified of events relating to the `sender_localpart` user. diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification index 78c0919d..279c4312 100644 --- a/changelogs/client_server/newsfragments/1644.clarification +++ b/changelogs/client_server/newsfragments/1644.clarification @@ -1 +1 @@ -Clarify specification by adding `/logout` to the overview list of endpoints that don't take a JSON request body. +Add `/logout` and clarify the endpoints which do not take a JSON request body. diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.feature similarity index 100% rename from changelogs/client_server/newsfragments/1755.clarification rename to changelogs/client_server/newsfragments/1755.feature diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature index 3471c1b9..f65d48ba 100644 --- a/changelogs/client_server/newsfragments/1757.feature +++ b/changelogs/client_server/newsfragments/1757.feature @@ -1 +1 @@ -Add optional `animated` query string option to `GET /_matrix/media/v3/thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file +Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1772.clarification b/changelogs/client_server/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/client_server/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1808.clarification b/changelogs/client_server/newsfragments/1808.clarification deleted file mode 100644 index ff2c1651..00000000 --- a/changelogs/client_server/newsfragments/1808.clarification +++ /dev/null @@ -1 +0,0 @@ -Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/changelogs/client_server/newsfragments/1808.deprecation b/changelogs/client_server/newsfragments/1808.deprecation new file mode 100644 index 00000000..ae9f620d --- /dev/null +++ b/changelogs/client_server/newsfragments/1808.deprecation @@ -0,0 +1 @@ +Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification index af643e2e..fa76c2a1 100644 --- a/changelogs/client_server/newsfragments/1813.clarification +++ b/changelogs/client_server/newsfragments/1813.clarification @@ -1 +1 @@ -Use `patternProperties` in more places with supported formats. +Link to existing grammar where possible in types. diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.feature similarity index 100% rename from changelogs/client_server/newsfragments/1816.clarification rename to changelogs/client_server/newsfragments/1816.feature diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification index faf8aae9..3ccb2333 100644 --- a/changelogs/client_server/newsfragments/1841.clarification +++ b/changelogs/client_server/newsfragments/1841.clarification @@ -1 +1 @@ -Fix broken link to push rule condition kinds. +Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification index 6f57eb35..ee5387a8 100644 --- a/changelogs/client_server/newsfragments/1846.clarification +++ b/changelogs/client_server/newsfragments/1846.clarification @@ -1 +1 @@ -Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement. +Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature index 25d1914b..ab3dbc34 100644 --- a/changelogs/client_server/newsfragments/1847.feature +++ b/changelogs/client_server/newsfragments/1847.feature @@ -1 +1 @@ -Add the new `unsigned.membership` property to events served over the client-server API, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). +Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification index 9d877ff5..ee5387a8 100644 --- a/changelogs/client_server/newsfragments/1861.clarification +++ b/changelogs/client_server/newsfragments/1861.clarification @@ -1 +1 @@ -Use RFC 2119 keywords more consistently throughout various parts of the specification. \ No newline at end of file +Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification index d054d41d..688288cf 100644 --- a/changelogs/client_server/newsfragments/1863.clarification +++ b/changelogs/client_server/newsfragments/1863.clarification @@ -1 +1 @@ -Minor clarifications to the "end-to-end encryption" module. +Clarify where keys reside when checking an `m.room.encrypted` event. diff --git a/changelogs/identity_service/newsfragments/1772.clarification b/changelogs/identity_service/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/identity_service/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/identity_service/newsfragments/1808.clarification b/changelogs/identity_service/newsfragments/1808.clarification deleted file mode 100644 index ff2c1651..00000000 --- a/changelogs/identity_service/newsfragments/1808.clarification +++ /dev/null @@ -1 +0,0 @@ -Deprecate authentication via a query string, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). diff --git a/changelogs/identity_service/newsfragments/1808.deprecation b/changelogs/identity_service/newsfragments/1808.deprecation new file mode 100644 index 00000000..ae9f620d --- /dev/null +++ b/changelogs/identity_service/newsfragments/1808.deprecation @@ -0,0 +1 @@ +Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification index ebf8030d..c092b8f7 100644 --- a/changelogs/internal/newsfragments/1769.clarification +++ b/changelogs/internal/newsfragments/1769.clarification @@ -1 +1 @@ -Formatting fixes in CONTRIBUTING.rst. +Formatting fixes in `CONTRIBUTING.rst`. diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification index e5fb516f..0eb57682 100644 --- a/changelogs/internal/newsfragments/1770.clarification +++ b/changelogs/internal/newsfragments/1770.clarification @@ -1 +1 @@ -Reduce whitespace on mobile viewports +Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification index b1941e18..0eb57682 100644 --- a/changelogs/internal/newsfragments/1771.clarification +++ b/changelogs/internal/newsfragments/1771.clarification @@ -1 +1 @@ -Arrange rows in `.basic-info` tables vertically when horizontal space is constrained. +Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1772.clarification b/changelogs/internal/newsfragments/1772.clarification similarity index 100% rename from changelogs/application_service/newsfragments/1772.clarification rename to changelogs/internal/newsfragments/1772.clarification diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification index 4fb58650..8776d77b 100644 --- a/changelogs/internal/newsfragments/1781.clarification +++ b/changelogs/internal/newsfragments/1781.clarification @@ -1 +1 @@ -Fix `github-labels.rst` +Fix `github-labels.rst`. diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification index 1810c632..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1786.clarification +++ b/changelogs/internal/newsfragments/1786.clarification @@ -1 +1 @@ -Upgrade jsonschema and python-jsonpath CI scripts dependencies. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1793.misc b/changelogs/internal/newsfragments/1793.clarification similarity index 100% rename from changelogs/internal/newsfragments/1793.misc rename to changelogs/internal/newsfragments/1793.clarification diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification index dbfaa8c9..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1803.clarification +++ b/changelogs/internal/newsfragments/1803.clarification @@ -1 +1 @@ -Update most CI actions. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification index 39249cb8..c66e15e3 100644 --- a/changelogs/internal/newsfragments/1804.clarification +++ b/changelogs/internal/newsfragments/1804.clarification @@ -1 +1 @@ -Update typos CI action. +Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1813.clarification b/changelogs/internal/newsfragments/1813.clarification new file mode 100644 index 00000000..af643e2e --- /dev/null +++ b/changelogs/internal/newsfragments/1813.clarification @@ -0,0 +1 @@ +Use `patternProperties` in more places with supported formats. diff --git a/changelogs/client_server/newsfragments/1822.clarification b/changelogs/internal/newsfragments/1822.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1822.clarification rename to changelogs/internal/newsfragments/1822.clarification diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification index c122052d..ca5f3aea 100644 --- a/changelogs/room_versions/newsfragments/1827.clarification +++ b/changelogs/room_versions/newsfragments/1827.clarification @@ -1 +1 @@ -Fix minor spelling mistake of object being spelt "obiect". +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1772.clarification b/changelogs/server_server/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/server_server/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification index af643e2e..fa76c2a1 100644 --- a/changelogs/server_server/newsfragments/1813.clarification +++ b/changelogs/server_server/newsfragments/1813.clarification @@ -1 +1 @@ -Use `patternProperties` in more places with supported formats. +Link to existing grammar where possible in types. From 560f29cff35c497a0a088e0c25391d958575d163 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 19 Jun 2024 22:08:20 -0600 Subject: [PATCH 30/60] Update release documentation (Q2 2024 edition) (#1759) * Update release documentation (Q2 2024 edition) * changelog * Drop the ranges we don't follow * Don't discourage maintenance * Patch releases just aren't a good idea --- .github/ISSUE_TEMPLATE/release.md | 24 ++++---- .../internal/newsfragments/1759.clarification | 1 + meta/releasing.md | 59 +++++++++---------- 3 files changed, 43 insertions(+), 41 deletions(-) create mode 100644 changelogs/internal/newsfragments/1759.clarification diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index 4128bb9b..bbe12160 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -16,20 +16,22 @@ Previous release: Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): +* [ ] Pin this issue to the repo. * [ ] Ensure the social media account holders are available for the release day. -* [ ] Blog post written -* [ ] Check for release blockers that may have been missed -* [ ] Review/fix the changelog +* [ ] Blog post written. +* [ ] Check for release blockers that may have been missed. +* [ ] Review/fix the changelog. Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): -* [ ] Branch stuffs -* [ ] Github release artifact -* [ ] Published to spec.matrix.org -* [ ] All links work -* [ ] Publish blog post -* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted -* [ ] Post to Twitter/Mastodon -* [ ] Close this issue +* [ ] Branch stuffs. +* [ ] Github release artifact. +* [ ] Published to spec.matrix.org. +* [ ] All links work. +* [ ] Publish blog post. +* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted. +* [ ] Post to Twitter/Mastodon. +* [ ] Close this issue. +* [ ] Unpin this issue from the repo. Known release blockers: * [ ] diff --git a/changelogs/internal/newsfragments/1759.clarification b/changelogs/internal/newsfragments/1759.clarification new file mode 100644 index 00000000..a44c98df --- /dev/null +++ b/changelogs/internal/newsfragments/1759.clarification @@ -0,0 +1 @@ +Update the spec release process and related documentation. \ No newline at end of file diff --git a/meta/releasing.md b/meta/releasing.md index 83261385..eb2c16b7 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -6,48 +6,43 @@ machinery works. ## Timeline -The spec is released each calendar quarter. The target release dates are within the -following ranges: +The spec is released each calendar quarter. The *target* months are: -* Q1: January 20-27 (critically, before FOSDEM). -* Q2: May 20-27. -* Q3: August 20-27. -* Q4: November 1-15 (before recurring November conflicts, like IETF). +* Q1: January or February. +* Q2: May. +* Q3: August. +* Q4: November. -The SCT aims to have dates picked out by: - -* Q1: January 10. -* Q2: May 1. -* Q3: August 1. -* Q4: October 15. +The SCT aims to have dates picked out 2 weeks before the chosen release date. When +possible, releases should be scheduled for Thursdays and Fridays to allow a few +consecutive business days for identifying blockers. When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X) -issue is created to track details of the release. Release blockers should continue to -be accepted up until 7 calendar days prior to the release date. +issue is created to track details of the release. Release blockers should continue +to be accepted at the discretion of whoever is doing the release (typically, blockers +should be allowed up to 1-2 days before the release date). **Release dates are not promises.** The SCT reserves the ability to change, cancel, postpone, etc a release for any reason. Do not rely on a release happening on a given day until the release has actually happened & blog post published. -Once a release is scheduled, the SCT will begin planning what the next release is +Once a release is *scheduled*, the SCT will begin planning what the next release is expected to look like. The plan should be included in the spec release blog post, and be ready for execution on spec release day. Plans are guides and not promises. -A blog post for the SCT members to review should be ready at minimum 1 week before -the target release date. 1-2 days before the release itself, the prerequisite steps -below are executed to ensure the spec release can go ahead. +A blog post for the SCT members to review should be ready 2-3 days prior to the +release at minimum. Preferably a week in advance. + +1-2 days before the release itself, the prerequisite steps below are executed to +ensure the spec release can go ahead. ## Release composition *This section is a work in progress.* -Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a -slightly different theme to it: - -* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM. -* Q2: Regular feature release, if possible. -* Q3: Momentum-continuing feature release, if possible. -* Q4: Preferably a maintenance release, but will accept features per normal. +Spec releases do not currently have attached themes, though when planning a release +a broad theme may be considered. Ideally, each release contains a "hero feature" +which is highlighted in the later blog post. ## Prerequisites / preparation @@ -115,12 +110,16 @@ release. ## Patching a release -From time to time we'll need to update a release in the wild. Examples include fixing typos, -updating build machinery, etc. Typically it is not considered a good idea to patch a release -more than 1 month after the original release date - this is because the administrative effort -is typically best reserved for the next release cycle. +Patch releases are used to fix the most recent release on record. Typically a patch +release will be deployed if there is an issue with the build machinery, a factual +error is introduced by the release, or there are notable clarity issues introduced +by the release which may affect implementation. It's usually not a good idea to +ship a patch release if it can be avoided. -**Patch releases are not to be used for spec changes. Only typos and equivalent.** +Typos and similar do not generally require a patch release. + +**Patch releases must not to be used for spec changes (new MSCs, etc) beyond fixing +factual errors.** 1. Add the required changes to the release branch (`release/v1.2` for example). 2. Fast forward the `v1.2` tag to the release branch head. From 5fbfdd6821bc3b7aa02976a888052272fd16fbe4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 10:42:40 +0200 Subject: [PATCH 31/60] Fix generated HTML (#1880) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add tr as child of thead in HTML tables It is invalid HTML for th to be the direct children of thead Signed-off-by: Kévin Commaille * Remove unnecessary HTML code end tag Signed-off-by: Kévin Commaille * Avoid nesting p HTML elements A p HTML element cannot contain other block elements, so the "parent" element is closed when the first "child" one is opened. We need to use Page.RenderString with options to force Hugo to keep the wrapping p elements even if the content contains a single paragraph. Signed-off-by: Kévin Commaille * Add missing HTML details end tags Signed-off-by: Kévin Commaille * Replace HTML a self-closing tag with start and end tags The a element start and end tags are mandatory. Signed-off-by: Kévin Commaille * Replace obsolete HTML name attribute with id Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1880.clarification | 1 + content/client-server-api/modules/push.md | 14 +++++++------- layouts/partials/events/render-event.html | 2 ++ .../partials/openapi/render-content-type.html | 6 ++++-- .../partials/openapi/render-object-table.html | 16 ++++++++++------ layouts/partials/openapi/render-operation.html | 2 +- layouts/partials/openapi/render-responses.html | 6 ++++-- layouts/shortcodes/definition.html | 2 ++ 8 files changed, 31 insertions(+), 18 deletions(-) create mode 100644 changelogs/internal/newsfragments/1880.clarification diff --git a/changelogs/internal/newsfragments/1880.clarification b/changelogs/internal/newsfragments/1880.clarification new file mode 100644 index 00000000..56090e20 --- /dev/null +++ b/changelogs/internal/newsfragments/1880.clarification @@ -0,0 +1 @@ +Fix validation errors in generated HTML. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index c674bac9..2d828a01 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -521,7 +521,7 @@ Definition: } ``` - **`.m.rule.is_user_mention`** + **`.m.rule.is_user_mention`** {{< added-in v="1.7" >}} @@ -555,7 +555,7 @@ Definition: } ``` - **`.m.rule.contains_display_name`** + **`.m.rule.contains_display_name`** {{% changed-in v="1.7" %}} @@ -590,7 +590,7 @@ Definition: } ``` - **`.m.rule.is_room_mention`** + **`.m.rule.is_room_mention`** {{< added-in v="1.7" >}} @@ -624,7 +624,7 @@ Definition: } ``` - **`.m.rule.roomnotif`** + **`.m.rule.roomnotif`** {{% changed-in v="1.7" %}} @@ -662,7 +662,7 @@ Definition: } ``` -**`.m.rule.tombstone`** +**`.m.rule.tombstone`** Matches any state event whose type is `m.room.tombstone`. This is intended to notify users of a room when it is upgraded, similar to what @@ -696,7 +696,7 @@ Definition: } ``` -**`.m.rule.reaction`** +**`.m.rule.reaction`** {{% added-in v="1.7" %}} @@ -776,7 +776,7 @@ Definition: ##### Default Content Rules - **`.m.rule.contains_user_name`** + **`.m.rule.contains_user_name`** {{% changed-in v="1.7" %}} diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 71ba60bd..154e51bf 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -101,4 +101,6 @@ {{ end }} {{ end }} + + diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index 036522de..96033e16 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -16,8 +16,10 @@ - - + + + + {{ range $idx, $content_type := $content_types }} diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index d2b09acb..3fd49f0b 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -31,9 +31,11 @@ {{ end }} - - - + + + + + {{ range $property_name, $property := $properties }} @@ -68,7 +70,7 @@ {{ if reflect.IsMap .additionalProperties }} - + @@ -90,8 +92,10 @@ resolve-additional-types.) {{ end }} - - + + + + {{ $property := . }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 8c6fce0e..ef525353 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -46,7 +46,7 @@ {{ partial "changed-in" (dict "changes_dict" (index $operation_data "x-changedInMatrixVersion")) }} {{ end -}} -

      {{ $operation_data.description | markdownify }}

      +{{ $operation_data.description | page.RenderString (dict "display" "block") }}
      Content-TypeDescription
      Content-TypeDescription
      {{ . }}
      NameTypeDescription
      NameTypeDescription
      <Other properties><Other properties> {{ partial "partials/property-type" .additionalProperties | safeHTML }} {{ partial "partials/property-description" (dict "property" .additionalProperties) }}
      {{ . }}
      TypeDescription
      TypeDescription
      diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 0ffc4884..80dcb582 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -20,8 +20,10 @@
      - - + + + + {{ range $code, $response := $responses }} diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index a1f0904e..f5d50e75 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -66,4 +66,6 @@ {{ jsonify (dict "indent" " ") $example }} ``` + + From 27e71fff1018cde9529767e729793b93c6e42307 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 20 Jun 2024 10:46:33 +0200 Subject: [PATCH 32/60] Render added/changed in info on request and response content types (#1876) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Render added/changed in info on request and response content types Fixes: #1774 Signed-off-by: Johannes Marbach Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com> --- .../internal/newsfragments/1876.clarification | 1 + data/api/client-server/content-repo.yaml | 5 +++-- .../partials/openapi/render-content-type.html | 18 +++++++++--------- layouts/partials/openapi/render-request.html | 8 +------- layouts/partials/openapi/render-responses.html | 8 +------- 5 files changed, 15 insertions(+), 25 deletions(-) create mode 100644 changelogs/internal/newsfragments/1876.clarification diff --git a/changelogs/internal/newsfragments/1876.clarification b/changelogs/internal/newsfragments/1876.clarification new file mode 100644 index 00000000..9f840914 --- /dev/null +++ b/changelogs/internal/newsfragments/1876.clarification @@ -0,0 +1 @@ +Render added/changed in info on request and response content types. diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index d0a6e5bb..92ca6caa 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -715,8 +715,9 @@ components: bytes: content: application/octet-stream: - example: - description: The content to be uploaded. + schema: + description: The content to be uploaded. + example: required: true responses: uploadTooLarge: diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index 96033e16..a7c90e1a 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,16 +1,12 @@ {{/* - Render a table showing content types and their descriptions, given - two arrays with equal length: + Render a table showing content types and their descriptions, given: - * `content_types`: the content type strings - - * `descriptions`: the description strings + * `content_types`: OpenAPI data specifying the content types as a dictionary of the form {string: {"schema": JsonSchema}} */}} {{ $content_types := .content_types }} -{{ $descriptions := .descriptions}} {{ if (gt (len $content_types) 0) }} @@ -21,10 +17,14 @@ - {{ range $idx, $content_type := $content_types }} + {{ range $mime, $body := $content_types }} - - + + {{ end }}
      StatusDescription
      StatusDescription
      Description
      {{ $content_type }}{{ index $descriptions $idx | markdownify -}}{{ $mime }} + {{ $body.schema.description | markdownify -}} + {{ if (index $body.schema "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $body.schema "x-addedInMatrixVersion")) }}{{ end -}} + {{ if (index $body.schema "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $body.schema "x-changedInMatrixVersion")) }}{{ end -}} +
      diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5fa0c255..92811f12 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -50,13 +50,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $request_body.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $request_body.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }} {{ end }}

      Request body example

      diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 80dcb582..f26110b4 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -123,13 +123,7 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} - {{ $descriptions := slice }} - {{ range $mime, $body := $response.content }} - {{ $mimes = $mimes | append $mime }} - {{ $descriptions = $descriptions | append $body.schema.description }} - {{ end }} - {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} + {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }} {{ end }} {{ end }} {{ end }} From 8ef84d1cc7c7dd4494c1232150c4d4ec6dca2fd8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 09:26:58 -0600 Subject: [PATCH 33/60] More normalization --- changelogs/internal/newsfragments/1851.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification index e89777c5..af7c653e 100644 --- a/changelogs/internal/newsfragments/1851.clarification +++ b/changelogs/internal/newsfragments/1851.clarification @@ -1 +1 @@ -Generate ToC with Hugo rather than JavaScript. +Generate the Table of Contents with Hugo rather than JavaScript. From 094e25b6cdf3c4bac4606dd180d8ae0fd77c3583 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:36:33 +0200 Subject: [PATCH 34/60] Ensure more uniqueness for generated HTML IDs (#1881) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Include method in all API endpoint children's IDs Avoids duplicate IDs for object of endpoints that use the same path but a different method. Signed-off-by: Kévin Commaille * Differentiate API endpoints' request and response children's IDs Ensures that the objects have a unique ID compared to other parts of the endpoint. Mostly useful for the Error type that can be used for responses with different status codes. Signed-off-by: Kévin Commaille * Differentiate the names of both SessionData formats Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1881.clarification | 1 + content/client-server-api/modules/end_to_end_encryption.md | 4 ++-- .../client-server/definitions/key_backup_session_data.yaml | 2 +- .../client-server/definitions/megolm_export_session_data.yaml | 1 + layouts/partials/openapi/render-operation.html | 4 ++-- layouts/partials/openapi/render-request.html | 3 ++- layouts/partials/openapi/render-responses.html | 3 ++- 7 files changed, 11 insertions(+), 7 deletions(-) create mode 100644 changelogs/internal/newsfragments/1881.clarification diff --git a/changelogs/internal/newsfragments/1881.clarification b/changelogs/internal/newsfragments/1881.clarification new file mode 100644 index 00000000..d698545f --- /dev/null +++ b/changelogs/internal/newsfragments/1881.clarification @@ -0,0 +1 @@ +Ensure most generated HTML IDs are unique. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 5787205a..49b053f6 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1349,7 +1349,7 @@ the following format: The `session_data` field in the backups is constructed as follows: 1. Encode the session key to be backed up as a JSON object using the - `SessionData` format defined below. + `BackedUpSessionData` format defined below. 2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral key and the backup's public key to generate a shared @@ -1427,7 +1427,7 @@ user-supplied passphrase, and is created as follows: ###### Key export format -The exported sessions are formatted as a JSON array of `SessionData` +The exported sessions are formatted as a JSON array of `ExportedSessionData` objects described as follows: {{% definition path="api/client-server/definitions/megolm_export_session_data" %}} diff --git a/data/api/client-server/definitions/key_backup_session_data.yaml b/data/api/client-server/definitions/key_backup_session_data.yaml index 18963cbe..bc61bb30 100644 --- a/data/api/client-server/definitions/key_backup_session_data.yaml +++ b/data/api/client-server/definitions/key_backup_session_data.yaml @@ -14,7 +14,7 @@ type: object -title: SessionData +title: BackedUpSessionData description: |- The format of a backed-up session key, prior to encryption, when using the `m.megolm_backup.v1.curve25519-aes-sha2` algorithm. diff --git a/data/api/client-server/definitions/megolm_export_session_data.yaml b/data/api/client-server/definitions/megolm_export_session_data.yaml index 8c1e5010..f5d1e409 100644 --- a/data/api/client-server/definitions/megolm_export_session_data.yaml +++ b/data/api/client-server/definitions/megolm_export_session_data.yaml @@ -16,6 +16,7 @@ allOf: - $ref: key_backup_session_data.yaml - type: object + title: ExportedSessionData description: |- The format used to encode a Megolm session key for export. diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index ef525353..13e7128c 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -20,14 +20,14 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} -{{ $anchor := anchorize $endpoint }} +{{ $anchor := printf "%s%s" (lower $method) (anchorize $endpoint) }}
      -

      +

      {{ $method }} {{ $endpoint }}

      diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 92811f12..80b352c6 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -16,6 +16,7 @@ {{ $parameters := .parameters }} {{ $request_body := .request_body }} {{ $anchor_base := .anchor_base }} +{{ $anchor := printf "%s_request" $anchor_base }}

      Request

      @@ -42,7 +43,7 @@ */}} {{ $schema := $json_body.schema }} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} {{ range $additional_types }} {{ partial "openapi/render-object-table" . }} {{ end }} diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index f26110b4..084e9481 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -39,6 +39,7 @@ {{ range $code, $response := $responses }} {{ if $response.content }} + {{ $anchor := printf "%s_response-%s" $anchor_base $code }}

      {{$code}} response

      {{/* Display defined headers */}} {{ if $response.headers }} @@ -97,7 +98,7 @@ response. (This will be a no-op for response types which aren't objects or arrays.) */}} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} + {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }} {{ range $additional_types }} {{ partial "openapi/render-object-table" . }} {{ end }} From bd20d946c49016bca6e8eca77e1cece6b0eeab5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:39:44 +0200 Subject: [PATCH 35/60] Fix the rendering of the event format for room versions 1 and 2 (#1883) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix rendering of array with items using anyOf Signed-off-by: Kévin Commaille * Use a single definition for Event Hash Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Add ending newline Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../newsfragments/1883.clarification | 1 + .../server-server/definitions/event_hash.yaml | 13 ++++++++++ data/api/server-server/definitions/pdu.yaml | 14 +---------- .../server-server/definitions/pdu_v11.yaml | 14 +---------- .../api/server-server/definitions/pdu_v3.yaml | 14 +---------- .../definitions/unsigned_pdu_base.yaml | 24 ++----------------- .../json-schema/resolve-additional-types.html | 4 ++++ .../partials/openapi/render-object-table.html | 12 ++++++++-- 8 files changed, 33 insertions(+), 63 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1883.clarification create mode 100644 data/api/server-server/definitions/event_hash.yaml diff --git a/changelogs/room_versions/newsfragments/1883.clarification b/changelogs/room_versions/newsfragments/1883.clarification new file mode 100644 index 00000000..0676c664 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1883.clarification @@ -0,0 +1 @@ +Fix the rendering of the event format for room versions 1 and 2. diff --git a/data/api/server-server/definitions/event_hash.yaml b/data/api/server-server/definitions/event_hash.yaml new file mode 100644 index 00000000..b88ac82e --- /dev/null +++ b/data/api/server-server/definitions/event_hash.yaml @@ -0,0 +1,13 @@ +type: object +title: Event Hash +description: |- + Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). +example: { + "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" +} +properties: + sha256: + type: string + description: The hash. + example: ThisHashCoversAllFieldsInCaseThisIsRedacted +required: ['sha256'] diff --git a/data/api/server-server/definitions/pdu.yaml b/data/api/server-server/definitions/pdu.yaml index 5903f80e..00b83321 100644 --- a/data/api/server-server/definitions/pdu.yaml +++ b/data/api/server-server/definitions/pdu.yaml @@ -25,19 +25,7 @@ allOf: description: For redaction events, the ID of the event being redacted. example: "$def456:matrix.org" hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/pdu_v11.yaml b/data/api/server-server/definitions/pdu_v11.yaml index 3edfb6c8..60f9b3ac 100644 --- a/data/api/server-server/definitions/pdu_v11.yaml +++ b/data/api/server-server/definitions/pdu_v11.yaml @@ -47,19 +47,7 @@ allOf: Must contain less than or equal to 20 events. example: ["$URLsafe-base64EncodedHash", "$Another_Event"] hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/pdu_v3.yaml b/data/api/server-server/definitions/pdu_v3.yaml index 32d05b36..e801518c 100644 --- a/data/api/server-server/definitions/pdu_v3.yaml +++ b/data/api/server-server/definitions/pdu_v3.yaml @@ -49,19 +49,7 @@ allOf: Must contain less than or equal to 20 events. example: ["$base64EncodedHash", "$AnotherEvent"] hashes: - type: object - title: Event Hash - description: |- - Content hashes of the PDU, following the algorithm specified in [Signing Events](/server-server-api/#signing-events). - example: { - "sha256": "ThisHashCoversAllFieldsInCaseThisIsRedacted" - } - properties: - sha256: - type: string - description: The hash. - example: ThisHashCoversAllFieldsInCaseThisIsRedacted - required: ['sha256'] + $ref: "event_hash.yaml" signatures: type: object description: |- diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index ce42236f..a2ec9552 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -60,17 +60,7 @@ properties: - type: string title: Event ID example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + - $ref: "event_hash.yaml" depth: type: integer description: |- @@ -96,17 +86,7 @@ properties: - type: string title: Event ID example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + - $ref: "event_hash.yaml" unsigned: type: object title: UnsignedData diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html index f6f09646..9d5e630a 100644 --- a/layouts/partials/json-schema/resolve-additional-types.html +++ b/layouts/partials/json-schema/resolve-additional-types.html @@ -155,6 +155,7 @@ {{ if eq $this_object.type "array" }} /* Add any nested objects referenced in this object's `items` */ {{ if $this_object.items.anyOf }} + {{ $updated_schemas := slice }} {{ range $idx, $item := $this_object.items.anyOf }} {{ $res := partial "get-additional-objects" (dict "this_object" $item @@ -163,7 +164,10 @@ "name" (printf "%s.items[%d]" $name $idx) ) }} {{ $all_objects = $res.objects }} + {{ $updated_schemas = $updated_schemas | append $res.schema }} {{ end }} + /* Update the top-level schema with the updated subschemas for the items */ + {{ $this_object = merge $this_object (dict "items" (dict "anyOf" $updated_schemas)) }} {{ else if reflect.IsMap $this_object.items}} {{ $res := partial "get-additional-objects" (dict "this_object" $this_object.items diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 3fd49f0b..656f556a 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -117,6 +117,9 @@ resolve-additional-types.) * `oneOf`: optional array of dictionaries describing the different formats that the property can have + + * `anyOf`: optional array of dictionaries describing the different formats + that the property can have * `properties`: if the type is an object, optional dictionary for well-defined properties, each given as: `property_name` : `property_data` @@ -158,13 +161,14 @@ resolve-additional-types.) {{ $type = . }} {{ end }} {{ end }} - {{ else if or (reflect.IsSlice .type) .oneOf }} + {{ else if or (reflect.IsSlice .type) .oneOf .anyOf }} {{/* It's legal to specify an array of types. - There are two ways to do that: + There are three ways to do that: - Use an array of strings. - Use oneOf, with items having a schema. + - Use anyOf, with items having a schema. Join them together in that case, like `type|other_type`. */}} @@ -174,6 +178,10 @@ resolve-additional-types.) {{ range .oneOf }} {{ $types = $types | append (partial "property-type" .) }} {{ end }} + {{ else if .anyOf }} + {{ range .anyOf }} + {{ $types = $types | append (partial "property-type" .) }} + {{ end }} {{ else }} {{ range .type }} {{ $types = $types | append (htmlEscape .) }} From 18628dc5d74eb3cc03ac5e89968c23c9fa27c982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:39:50 +0200 Subject: [PATCH 36/60] Allow to specify a prefix for generated HTML IDs of API endpoints (#1882) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Allow to specify a prefix for generated HTML IDs of API endpoints Allows to deduplicate IDs of duplicate endpoints Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- .../internal/newsfragments/1882.clarification | 1 + content/client-server-api/modules/room_previews.md | 2 +- .../modules/third_party_invites.md | 2 +- layouts/partials/openapi/render-api.html | 13 +++++++++---- layouts/partials/openapi/render-operation.html | 9 ++++++++- layouts/shortcodes/http-api.html | 6 +++++- 6 files changed, 25 insertions(+), 8 deletions(-) create mode 100644 changelogs/internal/newsfragments/1882.clarification diff --git a/changelogs/internal/newsfragments/1882.clarification b/changelogs/internal/newsfragments/1882.clarification new file mode 100644 index 00000000..99c0ca05 --- /dev/null +++ b/changelogs/internal/newsfragments/1882.clarification @@ -0,0 +1 @@ +Allow to specify a prefix for generated HTML IDs of API endpoints. diff --git a/content/client-server-api/modules/room_previews.md b/content/client-server-api/modules/room_previews.md index 277f7c39..ef9238b2 100644 --- a/content/client-server-api/modules/room_previews.md +++ b/content/client-server-api/modules/room_previews.md @@ -21,7 +21,7 @@ Clients can of course also call other endpoints such as [GET and [GET /search](#post_matrixclientv3search) to access events outside the `/events` stream. -{{% http-api spec="client-server" api="peeking_events" %}} +{{% http-api spec="client-server" api="peeking_events" anchor_base="peeking" %}} #### Server behaviour diff --git a/content/client-server-api/modules/third_party_invites.md b/content/client-server-api/modules/third_party_invites.md index aff7b530..7e418e15 100644 --- a/content/client-server-api/modules/third_party_invites.md +++ b/content/client-server-api/modules/third_party_invites.md @@ -33,7 +33,7 @@ invitee does indeed own that third-party identifier. See the A client asks a server to invite a user by their third-party identifier. -{{% http-api spec="client-server" api="third_party_membership" %}} +{{% http-api spec="client-server" api="third_party_membership" anchor_base="thirdparty" %}} #### Server behaviour diff --git a/layouts/partials/openapi/render-api.html b/layouts/partials/openapi/render-api.html index fcbb1cfc..608cfa33 100644 --- a/layouts/partials/openapi/render-api.html +++ b/layouts/partials/openapi/render-api.html @@ -5,11 +5,16 @@ * `api_data`: the OpenAPI data * `base_url`: the base URL: that is, the part we glue onto the front of each value in `paths` to get a complete URL. + * `anchor_base`: an optional prefix for the HTML IDs generated by + this template. + + This template replaces the old {{*_http_api}} template. */}} {{ $api_data := index .api_data }} {{ $base_url := .base_url }} +{{ $anchor_base := .anchor_base }} {{ range $path_name, $path_data := $api_data.paths }} @@ -21,28 +26,28 @@ {{ with $path_data.get }} - {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.post }} - {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.put }} - {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} {{ with $path_data.delete }} - {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . ) }} + {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }} {{ partial "openapi/render-operation" $operation_params }} {{ end }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 13e7128c..9b0e25d1 100644 --- a/layouts/partials/openapi/render-operation.html +++ b/layouts/partials/openapi/render-operation.html @@ -5,6 +5,8 @@ * `method`: the method, e.g. GET, PUT * `endpoint`: the endpoint * `operation_data`: the OpenAPI data for the operation + * `anchor_base`: an optional prefix for the HTML IDs generated by + this template. This template renders the operation as a `
      ` containing: @@ -20,7 +22,12 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} -{{ $anchor := printf "%s%s" (lower $method) (anchorize $endpoint) }} + +{{ $anchor := "" }} +{{ if .anchor_base }} + {{ $anchor = printf "%s_" .anchor_base }} +{{ end }} +{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
      diff --git a/layouts/shortcodes/http-api.html b/layouts/shortcodes/http-api.html index 489385de..b5201c49 100644 --- a/layouts/shortcodes/http-api.html +++ b/layouts/shortcodes/http-api.html @@ -11,6 +11,9 @@ The file extension is omitted. For example: {{% http-api spec="server-server" api="public_rooms" %}} + * an optional `anchor_base` parameter, which should be used as a + prefix for the HTML IDs generated by this template. It should only + be necessary to provide one for duplicate endpoints. This template replaces the old {{*_http_api}} template. @@ -18,6 +21,7 @@ {{ $spec := .Params.spec}} {{ $api := .Params.api}} +{{ $anchor_base := .Params.anchor_base}} {{ $api_data := index .Site.Data.api .Params.spec .Params.api }} {{ $base_url := (index $api_data.servers 0).variables.basePath.default }} @@ -26,4 +30,4 @@ {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }} {{ $api_data = partial "json-schema/resolve-allof" $api_data }} -{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }} +{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }} From 3af77f0cb45fdd066826da83f5955461d6e3e310 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:47:09 +0200 Subject: [PATCH 37/60] Fix the table of content for room versions (#1884) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix ToC for room versions pages Like for the cs-module shortcode, use .RenderShortcodes instead of .Content for the rver-fragment shortcode, so the headings are detected by Hugo. Signed-off-by: Kévin Commaille * Change the way "this version" is detected in added-in and changed-in shortcodes Now that we use .RenderShortcodes in the rver-fragment shortcode, we cannot remove the output of these shortcodes dynamically because they are replaced by a temporary placeholder due to Hugo's internals. Instead, since the `this` parameter was only used for room version, we always use the `v` parameter and compare with the version provided in the page's front matter. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille * Add version front matter for v11 Signed-off-by: Kévin Commaille * Update changelogs/room_versions/newsfragments/1884.clarification --------- Signed-off-by: Kévin Commaille Co-authored-by: Travis Ralston --- .../room_versions/newsfragments/1884.clarification | 1 + content/rooms/fragments/v3-auth-rules.md | 2 +- content/rooms/fragments/v3-handling-redactions.md | 2 +- content/rooms/fragments/v4-event-ids.md | 2 +- content/rooms/fragments/v8-auth-rules.md | 4 ++-- content/rooms/v1.md | 1 + content/rooms/v10.md | 9 +++++---- content/rooms/v11.md | 7 ++++--- content/rooms/v2.md | 3 ++- content/rooms/v3.md | 11 +++++------ content/rooms/v4.md | 3 ++- content/rooms/v5.md | 1 + content/rooms/v6.md | 11 ++++++----- content/rooms/v7.md | 9 +++++---- content/rooms/v8.md | 7 ++++--- content/rooms/v9.md | 7 ++++--- layouts/shortcodes/added-in.html | 13 +++++++------ layouts/shortcodes/changed-in.html | 13 +++++++------ layouts/shortcodes/rver-fragment.html | 2 +- meta/documentation_style.rst | 3 --- 20 files changed, 60 insertions(+), 51 deletions(-) create mode 100644 changelogs/room_versions/newsfragments/1884.clarification diff --git a/changelogs/room_versions/newsfragments/1884.clarification b/changelogs/room_versions/newsfragments/1884.clarification new file mode 100644 index 00000000..af7c653e --- /dev/null +++ b/changelogs/room_versions/newsfragments/1884.clarification @@ -0,0 +1 @@ +Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/content/rooms/fragments/v3-auth-rules.md b/content/rooms/fragments/v3-auth-rules.md index 05b8065a..9fb56327 100644 --- a/content/rooms/fragments/v3-auth-rules.md +++ b/content/rooms/fragments/v3-auth-rules.md @@ -1,6 +1,6 @@ --- --- -{{< added-in this=true >}} In room versions 1 and 2, events need a +{{< added-in v=3 >}} In room versions 1 and 2, events need a signature from the domain of the `event_id` in order to be considered valid. This room version does not include an `event_id` over federation in the same respect, so does not need a signature from that server. diff --git a/content/rooms/fragments/v3-handling-redactions.md b/content/rooms/fragments/v3-handling-redactions.md index 5a9aa7c6..80d478bf 100644 --- a/content/rooms/fragments/v3-handling-redactions.md +++ b/content/rooms/fragments/v3-handling-redactions.md @@ -1,6 +1,6 @@ --- --- -{{% added-in this=true %}} In room versions 1 and 2, redactions were +{{% added-in v=3 %}} In room versions 1 and 2, redactions were explicitly part of the [authorization rules](/rooms/v1/#authorization-rules) under Rule 11. As of room version 3, these conditions no longer exist as represented by [this version's authorization rules](#authorization-rules). diff --git a/content/rooms/fragments/v4-event-ids.md b/content/rooms/fragments/v4-event-ids.md index 804d97ec..d6ad398f 100644 --- a/content/rooms/fragments/v4-event-ids.md +++ b/content/rooms/fragments/v4-event-ids.md @@ -1,6 +1,6 @@ --- --- -{{% added-in this=true %}} The event ID is the [reference +{{% added-in v=4 %}} The event ID is the [reference hash](/server-server-api#calculating-the-reference-hash-for-an-event) of the event encoded using a variation of [Unpadded Base64](/appendices#unpadded-base64) which replaces the 62nd and diff --git a/content/rooms/fragments/v8-auth-rules.md b/content/rooms/fragments/v8-auth-rules.md index 3571057e..8fe2654d 100644 --- a/content/rooms/fragments/v8-auth-rules.md +++ b/content/rooms/fragments/v8-auth-rules.md @@ -54,7 +54,7 @@ The rules are as follows: 4. If type is `m.room.member`: 1. If there is no `state_key` property, or no `membership` property in `content`, reject. - 2. {{< added-in this=true >}} + 2. {{< added-in v=8 >}} If `content` has a `join_authorised_via_users_server` property: 1. If the event is not validly signed by the homeserver of the user ID denoted by the key, reject. @@ -65,7 +65,7 @@ The rules are as follows: 3. If the `sender` is banned, reject. 4. If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. - 5. {{< added-in this=true >}} + 5. {{< added-in v=8 >}} If the `join_rule` is `restricted`: 1. If membership state is `join` or `invite`, allow. 2. If the `join_authorised_via_users_server` key in `content` diff --git a/content/rooms/v1.md b/content/rooms/v1.md index 04055e8c..1b950f11 100644 --- a/content/rooms/v1.md +++ b/content/rooms/v1.md @@ -2,6 +2,7 @@ title: Room Version 1 type: docs weight: 10 +version: 1 --- This room version is the first ever version for rooms, and contains the diff --git a/content/rooms/v10.md b/content/rooms/v10.md index 8ec4832a..ad56ce05 100644 --- a/content/rooms/v10.md +++ b/content/rooms/v10.md @@ -2,6 +2,7 @@ title: Room Version 10 type: docs weight: 100 +version: 10 --- This room version builds on [version 9](/rooms/v9) to enforce that power level @@ -140,7 +141,7 @@ The rules are as follows: 3. If the `sender` is banned, reject. 4. If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. - 5. {{< changed-in this="true" >}} + 5. {{< changed-in v=10 >}} If the `join_rule` is `restricted` or `knock_restricted`: 1. If membership state is `join` or `invite`, allow. 2. If the `join_authorised_via_users_server` key in `content` @@ -196,7 +197,7 @@ The rules are as follows: than the `sender`'s power level, allow. 3. Otherwise, reject. 7. If `membership` is `knock`: - 1. {{< changed-in this="true" >}} + 1. {{< changed-in v=10 >}} If the `join_rule` is anything other than `knock` or `knock_restricted`, reject. 2. If `sender` does not match `state_key`, reject. @@ -213,11 +214,11 @@ The rules are as follows: 8. If the event has a `state_key` that starts with an `@` and does not match the `sender`, reject. 9. If type is `m.room.power_levels`: - 1. {{< added-in this="true" >}} + 1. {{< added-in v=10 >}} If any of the properties `users_default`, `events_default`, `state_default`, `ban`, `redact`, `kick`, or `invite` in `content` are present and not an integer, reject. - 2. {{< added-in this="true" >}} + 2. {{< added-in v=10 >}} If either of the properties `events` or `notifications` in `content` are present and not an object with values that are integers, reject. diff --git a/content/rooms/v11.md b/content/rooms/v11.md index d21c76ba..5821eb06 100644 --- a/content/rooms/v11.md +++ b/content/rooms/v11.md @@ -2,6 +2,7 @@ title: Room Version 11 type: docs weight: 100 +version: 11 --- This room version builds on [version 10](/rooms/v10) while clarifying redaction @@ -11,7 +12,7 @@ rules. ### Redactions -{{< added-in this=true >}} The top-level `origin`, `membership`, and `prev_state` properties +{{< added-in v=11 >}} The top-level `origin`, `membership`, and `prev_state` properties are no longer protected from redaction. The [`m.room.create`](/client-server-api#mroomcreate) event now keeps the entire `content` property. The [`m.room.redaction`](/client-server-api#mroomredaction) event keeps the `redacts` property under `content`. The @@ -111,7 +112,7 @@ the [Handling redactions](#handling-redactions) section. The rules are as follows: -1. {{< changed-in this="true" >}} +1. {{< changed-in v=11 >}} If type is `m.room.create`: 1. If it has any `prev_events`, reject. 2. If the domain of the `room_id` does not match the domain of the @@ -141,7 +142,7 @@ The rules are as follows: 1. If the event is not validly signed by the homeserver of the user ID denoted by the key, reject. 3. If `membership` is `join`: - 1. {{< changed-in this="true" >}} + 1. {{< changed-in v=11 >}} If the only previous event is an `m.room.create` and the `state_key` is the sender, allow. 2. If the `sender` does not match `state_key`, reject. diff --git a/content/rooms/v2.md b/content/rooms/v2.md index 097f2554..f9980261 100644 --- a/content/rooms/v2.md +++ b/content/rooms/v2.md @@ -2,6 +2,7 @@ title: Room Version 2 type: docs weight: 20 +version: 2 --- This room version builds on [version 1](/rooms/v1) with an improved @@ -27,7 +28,7 @@ changing only the state resolution algorithm. ### State resolution -{{% added-in this=true %}} +{{% added-in v=2 %}} {{% rver-fragment name="v2-state-res" %}} diff --git a/content/rooms/v3.md b/content/rooms/v3.md index ad9ff698..bee12698 100644 --- a/content/rooms/v3.md +++ b/content/rooms/v3.md @@ -2,6 +2,7 @@ title: Room Version 3 type: docs weight: 30 +version: 3 --- This room version builds on [version 2](/rooms/v2) with an improved event @@ -39,8 +40,7 @@ all the remaining behaviour described by [room version 2](/rooms/v2). ### Handling redactions - -{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}} +{{% rver-fragment name="v3-handling-redactions" %}} ### Event IDs @@ -54,7 +54,7 @@ the use of a dedicated event ID, servers are required to track the hashes on an event to determine its ID. {{% /boxes/rationale %}} -{{% added-in this=true %}} The event ID is the [reference +{{% added-in v=3 %}} The event ID is the [reference hash](/server-server-api#calculating-the-reference-hash-for-an-event) of the event encoded using [Unpadded Base64](/appendices#unpadded-base64), prefixed with `$`. A @@ -90,7 +90,7 @@ The complete structure of a event in a v3 room is shown below. ### Authorization rules {{% boxes/note %}} -{{< added-in this=true >}} `m.room.redaction` events are subject to auth rules in +{{< added-in v=3 >}} `m.room.redaction` events are subject to auth rules in the same way as any other event. In practice, that means they will normally be allowed by the auth rules, unless the `m.room.power_levels` event sets a power level requirement for `m.room.redaction`events via the `events` or `events_default` properties. In @@ -101,8 +101,7 @@ be performed. Receiving servers must perform additional checks, as described in the [Handling Redactions](#handling-redactions) section. {{% /boxes/note %}} - -{{< rver-fragment name="v3-auth-rules" withVersioning=true >}} +{{% rver-fragment name="v3-auth-rules" %}} ## Unchanged from v2 diff --git a/content/rooms/v4.md b/content/rooms/v4.md index c329f342..bd5651e1 100644 --- a/content/rooms/v4.md +++ b/content/rooms/v4.md @@ -2,6 +2,7 @@ title: Room Version 4 type: docs weight: 40 +version: 4 --- This room version builds on [version 3](/rooms/v3) using a different @@ -46,7 +47,7 @@ being interpreted differently by some reverse proxy software, and generally made administration harder. {{% /boxes/rationale %}} -{{% rver-fragment name="v4-event-ids" withVersioning="true" %}} +{{% rver-fragment name="v4-event-ids" %}} ## Unchanged from v3 diff --git a/content/rooms/v5.md b/content/rooms/v5.md index 25147e9e..665b0568 100644 --- a/content/rooms/v5.md +++ b/content/rooms/v5.md @@ -2,6 +2,7 @@ title: Room Version 5 type: docs weight: 50 +version: 5 --- This room version builds on [version 4](/rooms/v4) while enforcing signing diff --git a/content/rooms/v6.md b/content/rooms/v6.md index 9761ffdb..a3f4a682 100644 --- a/content/rooms/v6.md +++ b/content/rooms/v6.md @@ -2,6 +2,7 @@ title: Room Version 6 type: docs weight: 60 +version: 6 --- This room version builds on [version 5](/rooms/v5) while changing various @@ -15,7 +16,7 @@ which implement the redaction algorithm locally should refer to the ### Redactions -{{< added-in this=true >}} All significant meaning for `m.room.aliases` +{{< added-in v=6 >}} All significant meaning for `m.room.aliases` has been removed from the redaction algorithm. The remaining rules are the same as past room versions. @@ -40,11 +41,11 @@ in [room version 5](/rooms/v5). ### Authorization rules -{{< added-in this=true >}} Rule 4, which related specifically to events +{{< added-in v=6 >}} Rule 4, which related specifically to events of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass authorization checks relating to state events. -{{< added-in this=true >}} Additionally, the authorization rules for events of +{{< added-in v=6 >}} Additionally, the authorization rules for events of type `m.room.power_levels` now include a `notifications` property under `content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked the `events` property. @@ -174,12 +175,12 @@ The rules are as follows: power level, reject. 2. If the new value is higher than the `sender`'s current power level, reject. - 4. {{< changed-in this="true" >}} + 4. {{< changed-in v=6 >}} For each entry being changed in, or removed from, the `events` or `notifications` properties: 1. If the current value is greater than the `sender`'s current power level, reject. - 5. {{< changed-in this="true" >}} + 5. {{< changed-in v=6 >}} For each entry being added to, or changed in, the `events` or `notifications` properties: 1. If the new value is greater than the `sender`'s current power diff --git a/content/rooms/v7.md b/content/rooms/v7.md index b5c0f28a..2af07c16 100644 --- a/content/rooms/v7.md +++ b/content/rooms/v7.md @@ -2,6 +2,7 @@ title: Room Version 7 type: docs weight: 70 +version: 7 --- This room version builds on [version 6](/rooms/v6) to introduce knocking @@ -32,7 +33,7 @@ as do the versions v6 is based upon. ### Authorization rules -{{< added-in this=true >}} For checks performed upon `m.room.member` events, a +{{< added-in v=7 >}} For checks performed upon `m.room.member` events, a new point for `membership=knock` is added. Events must be signed by the server denoted by the `sender` property. @@ -89,7 +90,7 @@ The rules are as follows: `state_key` is the creator, allow. 2. If the `sender` does not match `state_key`, reject. 3. If the `sender` is banned, reject. - 4. {{< changed-in this=true >}} + 4. {{< changed-in v=7 >}} If the `join_rule` is `invite` or `knock` then allow if membership state is `invite` or `join`. 5. If the `join_rule` is `public`, allow. @@ -121,7 +122,7 @@ The rules are as follows: the *invite level*, allow. 5. Otherwise, reject. 4. If `membership` is `leave`: - 1. {{< changed-in this=true >}} + 1. {{< changed-in v=7 >}} If the `sender` matches `state_key`, allow if and only if that user's current membership state is `invite`, `join`, or `knock`. @@ -141,7 +142,7 @@ The rules are as follows: the *ban level*, and the *target user*'s power level is less than the `sender`'s power level, allow. 3. Otherwise, reject. - 6. {{< added-in this=true >}} + 6. {{< added-in v=7 >}} If `membership` is `knock`: 1. If the `join_rule` is anything other than `knock`, reject. 2. If `sender` does not match `state_key`, reject. diff --git a/content/rooms/v8.md b/content/rooms/v8.md index ab4cd970..173073c5 100644 --- a/content/rooms/v8.md +++ b/content/rooms/v8.md @@ -2,6 +2,7 @@ title: Room Version 8 type: docs weight: 80 +version: 8 --- This room version builds on [version 7](/rooms/v7) to introduce a new @@ -27,7 +28,7 @@ Clients which implement the redaction algorithm locally should refer to the ### Redactions -{{% added-in this=true %}} `m.room.join_rules` events now keep `allow` in addition to other +{{% added-in v=8 %}} `m.room.join_rules` events now keep `allow` in addition to other keys in `content` when being redacted. {{% boxes/warning %}} @@ -83,11 +84,11 @@ room without invite. Otherwise, the room version inherits all properties of ### Authorization rules -{{< added-in this=true >}} For checks performed upon `m.room.member` events, new +{{< added-in v=8 >}} For checks performed upon `m.room.member` events, new points for handling `content.join_authorised_via_users_server` are added (Rule 4.2 and 4.3.5). -{{< rver-fragment name="v8-auth-rules" withVersioning=true >}} +{{% rver-fragment name="v8-auth-rules" %}} ### Redactions diff --git a/content/rooms/v9.md b/content/rooms/v9.md index cef269c6..5573b957 100644 --- a/content/rooms/v9.md +++ b/content/rooms/v9.md @@ -2,6 +2,7 @@ title: Room Version 9 type: docs weight: 90 +version: 9 --- This room version builds on [version 8](/rooms/v8) to add additional redaction @@ -17,7 +18,7 @@ Clients which implement the redaction algorithm locally should refer to the ### Redactions -{{< added-in this=true >}} [`m.room.member`](/client-server-api#mroommember) events +{{< added-in v=9 >}} [`m.room.member`](/client-server-api#mroommember) events now keep `join_authorised_via_users_server` in addition to other keys in `content` when being redacted. @@ -38,7 +39,7 @@ information. The full redaction algorithm follows. -{{% rver-fragment name="v9-redactions" withVersioning="true" %}} +{{% rver-fragment name="v9-redactions" %}} ## Server implementation components @@ -83,7 +84,7 @@ completeness. ### Authorization rules -{{< rver-fragment name="v8-auth-rules" >}} +{{% rver-fragment name="v8-auth-rules" %}} ### State resolution diff --git a/layouts/shortcodes/added-in.html b/layouts/shortcodes/added-in.html index 149be685..9f18809d 100644 --- a/layouts/shortcodes/added-in.html +++ b/layouts/shortcodes/added-in.html @@ -1,8 +1,9 @@ -{{ $ver := .Params.v }} -{{ $this := .Params.this }} +{{- $ver := .Params.v -}} -{{ if $this }} - [New in this version] -{{ else }} +{{- with page.Params.version -}} + {{- if eq $ver . -}} + [New in this version] + {{- end -}} +{{- else -}} [Added in v{{ $ver }}] -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} +{{- end -}} diff --git a/layouts/shortcodes/changed-in.html b/layouts/shortcodes/changed-in.html index 8da2559a..17c1c787 100644 --- a/layouts/shortcodes/changed-in.html +++ b/layouts/shortcodes/changed-in.html @@ -1,8 +1,9 @@ -{{ $ver := .Params.v }} -{{ $this := .Params.this }} +{{- $ver := .Params.v -}} -{{ if $this }} - [Changed in this version] -{{ else }} +{{- with page.Params.version -}} + {{- if eq $ver . -}} + [Changed in this version] + {{- end -}} +{{- else -}} [Changed in v{{ $ver }}] -{{ end }} {{/* Do not leave an empty line at the end of this file otherwise the inline behaviour breaks. */}} +{{- end -}} diff --git a/layouts/shortcodes/rver-fragment.html b/layouts/shortcodes/rver-fragment.html index a10be8b5..894e6f0b 100644 --- a/layouts/shortcodes/rver-fragment.html +++ b/layouts/shortcodes/rver-fragment.html @@ -19,7 +19,7 @@ {{ with .Site.GetPage "rooms/fragments" }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} - {{ $content := .Content }} + {{ $content := .RenderShortcodes }} {{ if not $withVersioning }} {{ $content = (replace $content "[New in this version]" "") }} {{ $content = (replace $content "[Changed in this version]" "") }} diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 89c462f8..6ed1b23a 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -91,9 +91,6 @@ current version is `v1.1` then annotate your changes with `v1.2`. * `{{% added-in v="1.2" %}}` or `{{% changed-in v="1.2" %}}` within Markdown documents. * `x-addedInMatrixVersion` and `x-changedInMatrixVersion` within OpenAPI. -In rare cases, `this=true` can be used on the Markdown syntax to adjust the wording. -This is most commonly used in room version specifications. - **Tip**: If you're trying to inline the Markdown version and getting unexpected results, try replacing the `%` symbols with `<` and `>`, changing how Hugo renders the shortcode. From e2cb3a739af068c30600371058b164643ecdf6a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 20 Jun 2024 18:20:16 +0200 Subject: [PATCH 38/60] Fix ToC of spec proposals (#1885) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix ToC of spec proposals Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1885.clarification | 1 + layouts/shortcodes/proposal-tables.html | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/1885.clarification diff --git a/changelogs/internal/newsfragments/1885.clarification b/changelogs/internal/newsfragments/1885.clarification new file mode 100644 index 00000000..af7c653e --- /dev/null +++ b/changelogs/internal/newsfragments/1885.clarification @@ -0,0 +1 @@ +Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/layouts/shortcodes/proposal-tables.html b/layouts/shortcodes/proposal-tables.html index f61f168b..06443909 100644 --- a/layouts/shortcodes/proposal-tables.html +++ b/layouts/shortcodes/proposal-tables.html @@ -33,7 +33,7 @@ {{ $states := .Site.Data.msc.proposals }} {{ range $states }} -

      {{ .title }}

      +### {{ .title }} {.proposal-table-title} {{ if .proposals }} From bed4ad589e0975f9d7f3f7010472afcb34a85e7e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:04:19 -0600 Subject: [PATCH 39/60] Queue Matrix 1.11 --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index 15003eee..b2856375 100644 --- a/config.toml +++ b/config.toml @@ -64,14 +64,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -# major = "1" -# minor = "10" -# release_date = "March 22, 2024" +major = "1" +minor = "11" +release_date = "June 20, 2024" # User interface configuration [params.ui] From 1fc8f8856fe47849f90344cfa91601c984627acb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:20:50 -0600 Subject: [PATCH 40/60] Matrix 1.11 --- .../newsfragments/1791.clarification | 1 - .../newsfragments/1819.clarification | 1 - .../appendices/newsfragments/1823.deprecation | 1 - .../newsfragments/1850.clarification | 1 - .../newsfragments/1810.clarification | 1 - .../newsfragments/1644.clarification | 1 - .../client_server/newsfragments/1755.feature | 1 - .../client_server/newsfragments/1757.feature | 1 - .../newsfragments/1776.clarification | 1 - .../newsfragments/1808.deprecation | 1 - .../client_server/newsfragments/1812.feature | 1 - .../newsfragments/1813.clarification | 1 - .../client_server/newsfragments/1816.feature | 1 - .../newsfragments/1819.clarification | 1 - .../client_server/newsfragments/1828.feature | 1 - .../newsfragments/1829.clarification | 1 - .../newsfragments/1832.clarification | 1 - .../newsfragments/1839.clarification | 1 - .../newsfragments/1841.clarification | 1 - .../newsfragments/1843.clarification | 1 - .../newsfragments/1846.clarification | 1 - .../client_server/newsfragments/1847.feature | 1 - .../newsfragments/1850.clarification | 1 - .../newsfragments/1852.clarification | 1 - .../newsfragments/1853.clarification | 1 - .../newsfragments/1854.clarification | 1 - .../newsfragments/1858.deprecation | 1 - .../newsfragments/1858.feature.1 | 1 - .../newsfragments/1858.feature.2 | 1 - .../client_server/newsfragments/1858.new.1 | 1 - .../client_server/newsfragments/1858.new.2 | 1 - .../client_server/newsfragments/1858.new.3 | 1 - .../client_server/newsfragments/1858.new.4 | 1 - .../client_server/newsfragments/1858.new.5 | 1 - .../newsfragments/1860.clarification | 1 - .../newsfragments/1861.clarification | 1 - .../newsfragments/1862.clarification | 1 - .../newsfragments/1863.clarification | 1 - .../newsfragments/1872.clarification | 1 - .../newsfragments/1808.deprecation | 1 - .../internal/newsfragments/1759.clarification | 1 - .../internal/newsfragments/1765.clarification | 1 - .../internal/newsfragments/1769.clarification | 1 - .../internal/newsfragments/1770.clarification | 1 - .../internal/newsfragments/1771.clarification | 1 - .../internal/newsfragments/1772.clarification | 1 - .../internal/newsfragments/1773.clarification | 1 - .../internal/newsfragments/1775.clarification | 1 - .../internal/newsfragments/1781.clarification | 1 - .../internal/newsfragments/1786.clarification | 1 - .../internal/newsfragments/1787.clarification | 1 - .../internal/newsfragments/1788.clarification | 1 - .../internal/newsfragments/1789.clarification | 1 - .../internal/newsfragments/1793.clarification | 1 - .../internal/newsfragments/1794.clarification | 1 - .../internal/newsfragments/1796.clarification | 1 - .../internal/newsfragments/1797.clarification | 1 - .../internal/newsfragments/1798.clarification | 1 - .../internal/newsfragments/1799.clarification | 1 - .../internal/newsfragments/1800.clarification | 1 - .../internal/newsfragments/1801.clarification | 1 - .../internal/newsfragments/1802.clarification | 1 - .../internal/newsfragments/1803.clarification | 1 - .../internal/newsfragments/1804.clarification | 1 - .../internal/newsfragments/1805.clarification | 1 - .../internal/newsfragments/1806.clarification | 1 - .../internal/newsfragments/1809.clarification | 1 - .../internal/newsfragments/1813.clarification | 1 - .../internal/newsfragments/1814.clarification | 1 - .../internal/newsfragments/1822.clarification | 1 - .../internal/newsfragments/1831.clarification | 1 - .../internal/newsfragments/1849.clarification | 1 - .../internal/newsfragments/1851.clarification | 1 - .../internal/newsfragments/1856.clarification | 1 - .../internal/newsfragments/1865.clarification | 1 - .../internal/newsfragments/1876.clarification | 1 - .../internal/newsfragments/1880.clarification | 1 - .../internal/newsfragments/1881.clarification | 1 - .../internal/newsfragments/1882.clarification | 1 - .../internal/newsfragments/1885.clarification | 1 - .../newsfragments/1824.clarification | 1 - .../newsfragments/1827.clarification | 1 - .../newsfragments/1848.clarification | 1 - .../newsfragments/1883.clarification | 1 - .../newsfragments/1884.clarification | 1 - .../newsfragments/1813.clarification | 1 - .../newsfragments/1818.clarification | 1 - .../newsfragments/1834.clarification | 1 - .../newsfragments/1840.clarification | 1 - .../newsfragments/1844.clarification | 1 - .../newsfragments/1858.deprecation | 1 - .../server_server/newsfragments/1858.feature | 1 - .../server_server/newsfragments/1858.new.1 | 1 - .../server_server/newsfragments/1858.new.2 | 1 - .../server_server/newsfragments/1869.feature | 1 - .../newsfragments/1877.clarification | 1 - content/changelog/v1.11.md | 170 ++++++++++++++++++ 97 files changed, 170 insertions(+), 96 deletions(-) delete mode 100644 changelogs/appendices/newsfragments/1791.clarification delete mode 100644 changelogs/appendices/newsfragments/1819.clarification delete mode 100644 changelogs/appendices/newsfragments/1823.deprecation delete mode 100644 changelogs/appendices/newsfragments/1850.clarification delete mode 100644 changelogs/application_service/newsfragments/1810.clarification delete mode 100644 changelogs/client_server/newsfragments/1644.clarification delete mode 100644 changelogs/client_server/newsfragments/1755.feature delete mode 100644 changelogs/client_server/newsfragments/1757.feature delete mode 100644 changelogs/client_server/newsfragments/1776.clarification delete mode 100644 changelogs/client_server/newsfragments/1808.deprecation delete mode 100644 changelogs/client_server/newsfragments/1812.feature delete mode 100644 changelogs/client_server/newsfragments/1813.clarification delete mode 100644 changelogs/client_server/newsfragments/1816.feature delete mode 100644 changelogs/client_server/newsfragments/1819.clarification delete mode 100644 changelogs/client_server/newsfragments/1828.feature delete mode 100644 changelogs/client_server/newsfragments/1829.clarification delete mode 100644 changelogs/client_server/newsfragments/1832.clarification delete mode 100644 changelogs/client_server/newsfragments/1839.clarification delete mode 100644 changelogs/client_server/newsfragments/1841.clarification delete mode 100644 changelogs/client_server/newsfragments/1843.clarification delete mode 100644 changelogs/client_server/newsfragments/1846.clarification delete mode 100644 changelogs/client_server/newsfragments/1847.feature delete mode 100644 changelogs/client_server/newsfragments/1850.clarification delete mode 100644 changelogs/client_server/newsfragments/1852.clarification delete mode 100644 changelogs/client_server/newsfragments/1853.clarification delete mode 100644 changelogs/client_server/newsfragments/1854.clarification delete mode 100644 changelogs/client_server/newsfragments/1858.deprecation delete mode 100644 changelogs/client_server/newsfragments/1858.feature.1 delete mode 100644 changelogs/client_server/newsfragments/1858.feature.2 delete mode 100644 changelogs/client_server/newsfragments/1858.new.1 delete mode 100644 changelogs/client_server/newsfragments/1858.new.2 delete mode 100644 changelogs/client_server/newsfragments/1858.new.3 delete mode 100644 changelogs/client_server/newsfragments/1858.new.4 delete mode 100644 changelogs/client_server/newsfragments/1858.new.5 delete mode 100644 changelogs/client_server/newsfragments/1860.clarification delete mode 100644 changelogs/client_server/newsfragments/1861.clarification delete mode 100644 changelogs/client_server/newsfragments/1862.clarification delete mode 100644 changelogs/client_server/newsfragments/1863.clarification delete mode 100644 changelogs/client_server/newsfragments/1872.clarification delete mode 100644 changelogs/identity_service/newsfragments/1808.deprecation delete mode 100644 changelogs/internal/newsfragments/1759.clarification delete mode 100644 changelogs/internal/newsfragments/1765.clarification delete mode 100644 changelogs/internal/newsfragments/1769.clarification delete mode 100644 changelogs/internal/newsfragments/1770.clarification delete mode 100644 changelogs/internal/newsfragments/1771.clarification delete mode 100644 changelogs/internal/newsfragments/1772.clarification delete mode 100644 changelogs/internal/newsfragments/1773.clarification delete mode 100644 changelogs/internal/newsfragments/1775.clarification delete mode 100644 changelogs/internal/newsfragments/1781.clarification delete mode 100644 changelogs/internal/newsfragments/1786.clarification delete mode 100644 changelogs/internal/newsfragments/1787.clarification delete mode 100644 changelogs/internal/newsfragments/1788.clarification delete mode 100644 changelogs/internal/newsfragments/1789.clarification delete mode 100644 changelogs/internal/newsfragments/1793.clarification delete mode 100644 changelogs/internal/newsfragments/1794.clarification delete mode 100644 changelogs/internal/newsfragments/1796.clarification delete mode 100644 changelogs/internal/newsfragments/1797.clarification delete mode 100644 changelogs/internal/newsfragments/1798.clarification delete mode 100644 changelogs/internal/newsfragments/1799.clarification delete mode 100644 changelogs/internal/newsfragments/1800.clarification delete mode 100644 changelogs/internal/newsfragments/1801.clarification delete mode 100644 changelogs/internal/newsfragments/1802.clarification delete mode 100644 changelogs/internal/newsfragments/1803.clarification delete mode 100644 changelogs/internal/newsfragments/1804.clarification delete mode 100644 changelogs/internal/newsfragments/1805.clarification delete mode 100644 changelogs/internal/newsfragments/1806.clarification delete mode 100644 changelogs/internal/newsfragments/1809.clarification delete mode 100644 changelogs/internal/newsfragments/1813.clarification delete mode 100644 changelogs/internal/newsfragments/1814.clarification delete mode 100644 changelogs/internal/newsfragments/1822.clarification delete mode 100644 changelogs/internal/newsfragments/1831.clarification delete mode 100644 changelogs/internal/newsfragments/1849.clarification delete mode 100644 changelogs/internal/newsfragments/1851.clarification delete mode 100644 changelogs/internal/newsfragments/1856.clarification delete mode 100644 changelogs/internal/newsfragments/1865.clarification delete mode 100644 changelogs/internal/newsfragments/1876.clarification delete mode 100644 changelogs/internal/newsfragments/1880.clarification delete mode 100644 changelogs/internal/newsfragments/1881.clarification delete mode 100644 changelogs/internal/newsfragments/1882.clarification delete mode 100644 changelogs/internal/newsfragments/1885.clarification delete mode 100644 changelogs/room_versions/newsfragments/1824.clarification delete mode 100644 changelogs/room_versions/newsfragments/1827.clarification delete mode 100644 changelogs/room_versions/newsfragments/1848.clarification delete mode 100644 changelogs/room_versions/newsfragments/1883.clarification delete mode 100644 changelogs/room_versions/newsfragments/1884.clarification delete mode 100644 changelogs/server_server/newsfragments/1813.clarification delete mode 100644 changelogs/server_server/newsfragments/1818.clarification delete mode 100644 changelogs/server_server/newsfragments/1834.clarification delete mode 100644 changelogs/server_server/newsfragments/1840.clarification delete mode 100644 changelogs/server_server/newsfragments/1844.clarification delete mode 100644 changelogs/server_server/newsfragments/1858.deprecation delete mode 100644 changelogs/server_server/newsfragments/1858.feature delete mode 100644 changelogs/server_server/newsfragments/1858.new.1 delete mode 100644 changelogs/server_server/newsfragments/1858.new.2 delete mode 100644 changelogs/server_server/newsfragments/1869.feature delete mode 100644 changelogs/server_server/newsfragments/1877.clarification create mode 100644 content/changelog/v1.11.md diff --git a/changelogs/appendices/newsfragments/1791.clarification b/changelogs/appendices/newsfragments/1791.clarification deleted file mode 100644 index 22f59c5a..00000000 --- a/changelogs/appendices/newsfragments/1791.clarification +++ /dev/null @@ -1 +0,0 @@ -Define 'Opaque Identifier Grammar'. diff --git a/changelogs/appendices/newsfragments/1819.clarification b/changelogs/appendices/newsfragments/1819.clarification deleted file mode 100644 index dafeb10f..00000000 --- a/changelogs/appendices/newsfragments/1819.clarification +++ /dev/null @@ -1 +0,0 @@ -Define common cryptographic key representation. diff --git a/changelogs/appendices/newsfragments/1823.deprecation b/changelogs/appendices/newsfragments/1823.deprecation deleted file mode 100644 index 968bdfe4..00000000 --- a/changelogs/appendices/newsfragments/1823.deprecation +++ /dev/null @@ -1 +0,0 @@ -Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1850.clarification b/changelogs/appendices/newsfragments/1850.clarification deleted file mode 100644 index cc200bdf..00000000 --- a/changelogs/appendices/newsfragments/1850.clarification +++ /dev/null @@ -1 +0,0 @@ -Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification deleted file mode 100644 index fd21375c..00000000 --- a/changelogs/application_service/newsfragments/1810.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that appservices should be notified of events relating to the `sender_localpart` user. diff --git a/changelogs/client_server/newsfragments/1644.clarification b/changelogs/client_server/newsfragments/1644.clarification deleted file mode 100644 index 279c4312..00000000 --- a/changelogs/client_server/newsfragments/1644.clarification +++ /dev/null @@ -1 +0,0 @@ -Add `/logout` and clarify the endpoints which do not take a JSON request body. diff --git a/changelogs/client_server/newsfragments/1755.feature b/changelogs/client_server/newsfragments/1755.feature deleted file mode 100644 index 65c5ba36..00000000 --- a/changelogs/client_server/newsfragments/1755.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). diff --git a/changelogs/client_server/newsfragments/1757.feature b/changelogs/client_server/newsfragments/1757.feature deleted file mode 100644 index f65d48ba..00000000 --- a/changelogs/client_server/newsfragments/1757.feature +++ /dev/null @@ -1 +0,0 @@ -Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1776.clarification b/changelogs/client_server/newsfragments/1776.clarification deleted file mode 100644 index 4d2def20..00000000 --- a/changelogs/client_server/newsfragments/1776.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. diff --git a/changelogs/client_server/newsfragments/1808.deprecation b/changelogs/client_server/newsfragments/1808.deprecation deleted file mode 100644 index ae9f620d..00000000 --- a/changelogs/client_server/newsfragments/1808.deprecation +++ /dev/null @@ -1 +0,0 @@ -Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/client_server/newsfragments/1812.feature b/changelogs/client_server/newsfragments/1812.feature deleted file mode 100644 index baa9aa7d..00000000 --- a/changelogs/client_server/newsfragments/1812.feature +++ /dev/null @@ -1 +0,0 @@ -Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). diff --git a/changelogs/client_server/newsfragments/1813.clarification b/changelogs/client_server/newsfragments/1813.clarification deleted file mode 100644 index fa76c2a1..00000000 --- a/changelogs/client_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Link to existing grammar where possible in types. diff --git a/changelogs/client_server/newsfragments/1816.feature b/changelogs/client_server/newsfragments/1816.feature deleted file mode 100644 index e1b97854..00000000 --- a/changelogs/client_server/newsfragments/1816.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1819.clarification b/changelogs/client_server/newsfragments/1819.clarification deleted file mode 100644 index f04c85d4..00000000 --- a/changelogs/client_server/newsfragments/1819.clarification +++ /dev/null @@ -1 +0,0 @@ -Rename "recovery key" to "backup decryption key". diff --git a/changelogs/client_server/newsfragments/1828.feature b/changelogs/client_server/newsfragments/1828.feature deleted file mode 100644 index 65d7420b..00000000 --- a/changelogs/client_server/newsfragments/1828.feature +++ /dev/null @@ -1 +0,0 @@ -Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). diff --git a/changelogs/client_server/newsfragments/1829.clarification b/changelogs/client_server/newsfragments/1829.clarification deleted file mode 100644 index 68ce6207..00000000 --- a/changelogs/client_server/newsfragments/1829.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). diff --git a/changelogs/client_server/newsfragments/1832.clarification b/changelogs/client_server/newsfragments/1832.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1832.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification deleted file mode 100644 index eea109b1..00000000 --- a/changelogs/client_server/newsfragments/1839.clarification +++ /dev/null @@ -1 +0,0 @@ -Specify the encoding to be used when generating QR codes for device verification. diff --git a/changelogs/client_server/newsfragments/1841.clarification b/changelogs/client_server/newsfragments/1841.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1841.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1843.clarification b/changelogs/client_server/newsfragments/1843.clarification deleted file mode 100644 index 7ccfe4a7..00000000 --- a/changelogs/client_server/newsfragments/1843.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification deleted file mode 100644 index ee5387a8..00000000 --- a/changelogs/client_server/newsfragments/1846.clarification +++ /dev/null @@ -1 +0,0 @@ -Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature deleted file mode 100644 index ab3dbc34..00000000 --- a/changelogs/client_server/newsfragments/1847.feature +++ /dev/null @@ -1 +0,0 @@ -Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). diff --git a/changelogs/client_server/newsfragments/1850.clarification b/changelogs/client_server/newsfragments/1850.clarification deleted file mode 100644 index cc200bdf..00000000 --- a/changelogs/client_server/newsfragments/1850.clarification +++ /dev/null @@ -1 +0,0 @@ -Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. diff --git a/changelogs/client_server/newsfragments/1852.clarification b/changelogs/client_server/newsfragments/1852.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1852.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1853.clarification b/changelogs/client_server/newsfragments/1853.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1853.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1854.clarification b/changelogs/client_server/newsfragments/1854.clarification deleted file mode 100644 index cb996bd6..00000000 --- a/changelogs/client_server/newsfragments/1854.clarification +++ /dev/null @@ -1 +0,0 @@ - Clarify that relations recursion should be capped at a certain depth. diff --git a/changelogs/client_server/newsfragments/1858.deprecation b/changelogs/client_server/newsfragments/1858.deprecation deleted file mode 100644 index 6e93dca5..00000000 --- a/changelogs/client_server/newsfragments/1858.deprecation +++ /dev/null @@ -1 +0,0 @@ -Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.1 b/changelogs/client_server/newsfragments/1858.feature.1 deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/client_server/newsfragments/1858.feature.1 +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.feature.2 b/changelogs/client_server/newsfragments/1858.feature.2 deleted file mode 100644 index 63dfbb78..00000000 --- a/changelogs/client_server/newsfragments/1858.feature.2 +++ /dev/null @@ -1 +0,0 @@ -Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.1 b/changelogs/client_server/newsfragments/1858.new.1 deleted file mode 100644 index 9d02447f..00000000 --- a/changelogs/client_server/newsfragments/1858.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.2 b/changelogs/client_server/newsfragments/1858.new.2 deleted file mode 100644 index 07e7763a..00000000 --- a/changelogs/client_server/newsfragments/1858.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.3 b/changelogs/client_server/newsfragments/1858.new.3 deleted file mode 100644 index 49b67f04..00000000 --- a/changelogs/client_server/newsfragments/1858.new.3 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.4 b/changelogs/client_server/newsfragments/1858.new.4 deleted file mode 100644 index dda53b33..00000000 --- a/changelogs/client_server/newsfragments/1858.new.4 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1858.new.5 b/changelogs/client_server/newsfragments/1858.new.5 deleted file mode 100644 index 021b4023..00000000 --- a/changelogs/client_server/newsfragments/1858.new.5 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1860.clarification b/changelogs/client_server/newsfragments/1860.clarification deleted file mode 100644 index ca6e4117..00000000 --- a/changelogs/client_server/newsfragments/1860.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing secrets, third-party invites and room tagging modules to feature profiles table. diff --git a/changelogs/client_server/newsfragments/1861.clarification b/changelogs/client_server/newsfragments/1861.clarification deleted file mode 100644 index ee5387a8..00000000 --- a/changelogs/client_server/newsfragments/1861.clarification +++ /dev/null @@ -1 +0,0 @@ -Use RFC 2119 keywords more consistently. diff --git a/changelogs/client_server/newsfragments/1862.clarification b/changelogs/client_server/newsfragments/1862.clarification deleted file mode 100644 index 021b117c..00000000 --- a/changelogs/client_server/newsfragments/1862.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify when server name is used and link to the definition. diff --git a/changelogs/client_server/newsfragments/1863.clarification b/changelogs/client_server/newsfragments/1863.clarification deleted file mode 100644 index 688288cf..00000000 --- a/changelogs/client_server/newsfragments/1863.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify where keys reside when checking an `m.room.encrypted` event. diff --git a/changelogs/client_server/newsfragments/1872.clarification b/changelogs/client_server/newsfragments/1872.clarification deleted file mode 100644 index 4bcea39e..00000000 --- a/changelogs/client_server/newsfragments/1872.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. diff --git a/changelogs/identity_service/newsfragments/1808.deprecation b/changelogs/identity_service/newsfragments/1808.deprecation deleted file mode 100644 index ae9f620d..00000000 --- a/changelogs/identity_service/newsfragments/1808.deprecation +++ /dev/null @@ -1 +0,0 @@ -Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. diff --git a/changelogs/internal/newsfragments/1759.clarification b/changelogs/internal/newsfragments/1759.clarification deleted file mode 100644 index a44c98df..00000000 --- a/changelogs/internal/newsfragments/1759.clarification +++ /dev/null @@ -1 +0,0 @@ -Update the spec release process and related documentation. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1765.clarification b/changelogs/internal/newsfragments/1765.clarification deleted file mode 100644 index c1b999bf..00000000 --- a/changelogs/internal/newsfragments/1765.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix npm release script for `@matrix-org/spec`. diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification deleted file mode 100644 index c092b8f7..00000000 --- a/changelogs/internal/newsfragments/1769.clarification +++ /dev/null @@ -1 +0,0 @@ -Formatting fixes in `CONTRIBUTING.rst`. diff --git a/changelogs/internal/newsfragments/1770.clarification b/changelogs/internal/newsfragments/1770.clarification deleted file mode 100644 index 0eb57682..00000000 --- a/changelogs/internal/newsfragments/1770.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification deleted file mode 100644 index 0eb57682..00000000 --- a/changelogs/internal/newsfragments/1771.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve rendering on mobile devices. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1772.clarification b/changelogs/internal/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/internal/newsfragments/1772.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the OpenAPI definition of the security schemes. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1773.clarification b/changelogs/internal/newsfragments/1773.clarification deleted file mode 100644 index 53d959d1..00000000 --- a/changelogs/internal/newsfragments/1773.clarification +++ /dev/null @@ -1 +0,0 @@ -Simplify uses of `resolve-refs` partial. diff --git a/changelogs/internal/newsfragments/1775.clarification b/changelogs/internal/newsfragments/1775.clarification deleted file mode 100644 index 649503a0..00000000 --- a/changelogs/internal/newsfragments/1775.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix Hugo warnings. diff --git a/changelogs/internal/newsfragments/1781.clarification b/changelogs/internal/newsfragments/1781.clarification deleted file mode 100644 index 8776d77b..00000000 --- a/changelogs/internal/newsfragments/1781.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix `github-labels.rst`. diff --git a/changelogs/internal/newsfragments/1786.clarification b/changelogs/internal/newsfragments/1786.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1786.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1787.clarification b/changelogs/internal/newsfragments/1787.clarification deleted file mode 100644 index 5d2d1378..00000000 --- a/changelogs/internal/newsfragments/1787.clarification +++ /dev/null @@ -1 +0,0 @@ -Solve `allOf` recursively in OpenAPI and JSON Schemas. diff --git a/changelogs/internal/newsfragments/1788.clarification b/changelogs/internal/newsfragments/1788.clarification deleted file mode 100644 index 649503a0..00000000 --- a/changelogs/internal/newsfragments/1788.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix Hugo warnings. diff --git a/changelogs/internal/newsfragments/1789.clarification b/changelogs/internal/newsfragments/1789.clarification deleted file mode 100644 index f90c8934..00000000 --- a/changelogs/internal/newsfragments/1789.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix property type resolution in `render-object-table` partial. diff --git a/changelogs/internal/newsfragments/1793.clarification b/changelogs/internal/newsfragments/1793.clarification deleted file mode 100644 index bc5abca9..00000000 --- a/changelogs/internal/newsfragments/1793.clarification +++ /dev/null @@ -1 +0,0 @@ -Factor out common definition of `Tag` type. diff --git a/changelogs/internal/newsfragments/1794.clarification b/changelogs/internal/newsfragments/1794.clarification deleted file mode 100644 index 3c38016a..00000000 --- a/changelogs/internal/newsfragments/1794.clarification +++ /dev/null @@ -1 +0,0 @@ -Update the version of Hugo used to render the spec to v0.124.1. diff --git a/changelogs/internal/newsfragments/1796.clarification b/changelogs/internal/newsfragments/1796.clarification deleted file mode 100644 index 6a489a01..00000000 --- a/changelogs/internal/newsfragments/1796.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for pattern formats for `patternProperties`. diff --git a/changelogs/internal/newsfragments/1797.clarification b/changelogs/internal/newsfragments/1797.clarification deleted file mode 100644 index d98e89f0..00000000 --- a/changelogs/internal/newsfragments/1797.clarification +++ /dev/null @@ -1 +0,0 @@ -Clean up unnecessary `allOf`s in OpenAPI definitions. diff --git a/changelogs/internal/newsfragments/1798.clarification b/changelogs/internal/newsfragments/1798.clarification deleted file mode 100644 index 5bd28a93..00000000 --- a/changelogs/internal/newsfragments/1798.clarification +++ /dev/null @@ -1 +0,0 @@ -Show information about "Additional Properties" in object tables. diff --git a/changelogs/internal/newsfragments/1799.clarification b/changelogs/internal/newsfragments/1799.clarification deleted file mode 100644 index d47e0183..00000000 --- a/changelogs/internal/newsfragments/1799.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix anchors for schemas under `oneOf`. diff --git a/changelogs/internal/newsfragments/1800.clarification b/changelogs/internal/newsfragments/1800.clarification deleted file mode 100644 index 7dfac999..00000000 --- a/changelogs/internal/newsfragments/1800.clarification +++ /dev/null @@ -1 +0,0 @@ -Use reference to `OneTimeKeys` schema in OpenAPI definitions. diff --git a/changelogs/internal/newsfragments/1801.clarification b/changelogs/internal/newsfragments/1801.clarification deleted file mode 100644 index 6d01cfb7..00000000 --- a/changelogs/internal/newsfragments/1801.clarification +++ /dev/null @@ -1 +0,0 @@ -Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. diff --git a/changelogs/internal/newsfragments/1802.clarification b/changelogs/internal/newsfragments/1802.clarification deleted file mode 100644 index 09aebc5d..00000000 --- a/changelogs/internal/newsfragments/1802.clarification +++ /dev/null @@ -1 +0,0 @@ -Add anchors in `definition` shortcode. diff --git a/changelogs/internal/newsfragments/1803.clarification b/changelogs/internal/newsfragments/1803.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1803.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification deleted file mode 100644 index c66e15e3..00000000 --- a/changelogs/internal/newsfragments/1804.clarification +++ /dev/null @@ -1 +0,0 @@ -Update dependencies. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1805.clarification b/changelogs/internal/newsfragments/1805.clarification deleted file mode 100644 index c1b09b62..00000000 --- a/changelogs/internal/newsfragments/1805.clarification +++ /dev/null @@ -1 +0,0 @@ -Set python version for the Towncrier CI job. diff --git a/changelogs/internal/newsfragments/1806.clarification b/changelogs/internal/newsfragments/1806.clarification deleted file mode 100644 index 88b875bb..00000000 --- a/changelogs/internal/newsfragments/1806.clarification +++ /dev/null @@ -1 +0,0 @@ -Replace `set-output` with environment files in CI. diff --git a/changelogs/internal/newsfragments/1809.clarification b/changelogs/internal/newsfragments/1809.clarification deleted file mode 100644 index e1124a53..00000000 --- a/changelogs/internal/newsfragments/1809.clarification +++ /dev/null @@ -1 +0,0 @@ -Render response headers. diff --git a/changelogs/internal/newsfragments/1813.clarification b/changelogs/internal/newsfragments/1813.clarification deleted file mode 100644 index af643e2e..00000000 --- a/changelogs/internal/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Use `patternProperties` in more places with supported formats. diff --git a/changelogs/internal/newsfragments/1814.clarification b/changelogs/internal/newsfragments/1814.clarification deleted file mode 100644 index a540ea7e..00000000 --- a/changelogs/internal/newsfragments/1814.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for rendering string formats. diff --git a/changelogs/internal/newsfragments/1822.clarification b/changelogs/internal/newsfragments/1822.clarification deleted file mode 100644 index 034deb48..00000000 --- a/changelogs/internal/newsfragments/1822.clarification +++ /dev/null @@ -1 +0,0 @@ -Refactor the OpenAPI definitions of the content repository endpoints. diff --git a/changelogs/internal/newsfragments/1831.clarification b/changelogs/internal/newsfragments/1831.clarification deleted file mode 100644 index 8ce17713..00000000 --- a/changelogs/internal/newsfragments/1831.clarification +++ /dev/null @@ -1 +0,0 @@ -Clean up pull request template. diff --git a/changelogs/internal/newsfragments/1849.clarification b/changelogs/internal/newsfragments/1849.clarification deleted file mode 100644 index fc7c5d88..00000000 --- a/changelogs/internal/newsfragments/1849.clarification +++ /dev/null @@ -1 +0,0 @@ -Do not add empty arrays to examples. diff --git a/changelogs/internal/newsfragments/1851.clarification b/changelogs/internal/newsfragments/1851.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/internal/newsfragments/1851.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/internal/newsfragments/1856.clarification b/changelogs/internal/newsfragments/1856.clarification deleted file mode 100644 index 838b8af5..00000000 --- a/changelogs/internal/newsfragments/1856.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix syntax errors in the spec release issue template. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1865.clarification b/changelogs/internal/newsfragments/1865.clarification deleted file mode 100644 index f50be96f..00000000 --- a/changelogs/internal/newsfragments/1865.clarification +++ /dev/null @@ -1 +0,0 @@ -Use environment variables for Netlify build job. diff --git a/changelogs/internal/newsfragments/1876.clarification b/changelogs/internal/newsfragments/1876.clarification deleted file mode 100644 index 9f840914..00000000 --- a/changelogs/internal/newsfragments/1876.clarification +++ /dev/null @@ -1 +0,0 @@ -Render added/changed in info on request and response content types. diff --git a/changelogs/internal/newsfragments/1880.clarification b/changelogs/internal/newsfragments/1880.clarification deleted file mode 100644 index 56090e20..00000000 --- a/changelogs/internal/newsfragments/1880.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix validation errors in generated HTML. diff --git a/changelogs/internal/newsfragments/1881.clarification b/changelogs/internal/newsfragments/1881.clarification deleted file mode 100644 index d698545f..00000000 --- a/changelogs/internal/newsfragments/1881.clarification +++ /dev/null @@ -1 +0,0 @@ -Ensure most generated HTML IDs are unique. diff --git a/changelogs/internal/newsfragments/1882.clarification b/changelogs/internal/newsfragments/1882.clarification deleted file mode 100644 index 99c0ca05..00000000 --- a/changelogs/internal/newsfragments/1882.clarification +++ /dev/null @@ -1 +0,0 @@ -Allow to specify a prefix for generated HTML IDs of API endpoints. diff --git a/changelogs/internal/newsfragments/1885.clarification b/changelogs/internal/newsfragments/1885.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/internal/newsfragments/1885.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/room_versions/newsfragments/1824.clarification b/changelogs/room_versions/newsfragments/1824.clarification deleted file mode 100644 index 6f830830..00000000 --- a/changelogs/room_versions/newsfragments/1824.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that redaction events are still subject to all applicable auth rules. diff --git a/changelogs/room_versions/newsfragments/1827.clarification b/changelogs/room_versions/newsfragments/1827.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/room_versions/newsfragments/1827.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/room_versions/newsfragments/1848.clarification b/changelogs/room_versions/newsfragments/1848.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/room_versions/newsfragments/1848.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/room_versions/newsfragments/1883.clarification b/changelogs/room_versions/newsfragments/1883.clarification deleted file mode 100644 index 0676c664..00000000 --- a/changelogs/room_versions/newsfragments/1883.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix the rendering of the event format for room versions 1 and 2. diff --git a/changelogs/room_versions/newsfragments/1884.clarification b/changelogs/room_versions/newsfragments/1884.clarification deleted file mode 100644 index af7c653e..00000000 --- a/changelogs/room_versions/newsfragments/1884.clarification +++ /dev/null @@ -1 +0,0 @@ -Generate the Table of Contents with Hugo rather than JavaScript. diff --git a/changelogs/server_server/newsfragments/1813.clarification b/changelogs/server_server/newsfragments/1813.clarification deleted file mode 100644 index fa76c2a1..00000000 --- a/changelogs/server_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Link to existing grammar where possible in types. diff --git a/changelogs/server_server/newsfragments/1818.clarification b/changelogs/server_server/newsfragments/1818.clarification deleted file mode 100644 index 8c50b6ac..00000000 --- a/changelogs/server_server/newsfragments/1818.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1834.clarification b/changelogs/server_server/newsfragments/1834.clarification deleted file mode 100644 index 80c2fa48..00000000 --- a/changelogs/server_server/newsfragments/1834.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1840.clarification b/changelogs/server_server/newsfragments/1840.clarification deleted file mode 100644 index 80c2fa48..00000000 --- a/changelogs/server_server/newsfragments/1840.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. diff --git a/changelogs/server_server/newsfragments/1844.clarification b/changelogs/server_server/newsfragments/1844.clarification deleted file mode 100644 index 81013eb6..00000000 --- a/changelogs/server_server/newsfragments/1844.clarification +++ /dev/null @@ -1 +0,0 @@ -Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.deprecation b/changelogs/server_server/newsfragments/1858.deprecation deleted file mode 100644 index fd3d2576..00000000 --- a/changelogs/server_server/newsfragments/1858.deprecation +++ /dev/null @@ -1 +0,0 @@ -Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.feature b/changelogs/server_server/newsfragments/1858.feature deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/server_server/newsfragments/1858.feature +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.1 b/changelogs/server_server/newsfragments/1858.new.1 deleted file mode 100644 index e50d5fd1..00000000 --- a/changelogs/server_server/newsfragments/1858.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1858.new.2 b/changelogs/server_server/newsfragments/1858.new.2 deleted file mode 100644 index 1da2a693..00000000 --- a/changelogs/server_server/newsfragments/1858.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1869.feature b/changelogs/server_server/newsfragments/1869.feature deleted file mode 100644 index 02b9b51e..00000000 --- a/changelogs/server_server/newsfragments/1869.feature +++ /dev/null @@ -1 +0,0 @@ -Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1877.clarification b/changelogs/server_server/newsfragments/1877.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/server_server/newsfragments/1877.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md new file mode 100644 index 00000000..f3a60b55 --- /dev/null +++ b/content/changelog/v1.11.md @@ -0,0 +1,170 @@ +--- +date: 2024-06-20T10:20:43-06:00 +--- + + +## v1.11 + +
      + + +
      Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
      Release dateJune 20, 2024
      + + + +### Client-Server API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) +- Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). ([#1755](https://github.com/matrix-org/matrix-spec/issues/1755)) +- Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). ([#1757](https://github.com/matrix-org/matrix-spec/issues/1757)) +- Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). ([#1812](https://github.com/matrix-org/matrix-spec/issues/1812)) +- Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). ([#1816](https://github.com/matrix-org/matrix-spec/issues/1816)) +- Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). ([#1828](https://github.com/matrix-org/matrix-spec/issues/1828)) +- Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). ([#1847](https://github.com/matrix-org/matrix-spec/issues/1847)) +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Spec Clarifications** + +- Add `/logout` and clarify the endpoints which do not take a JSON request body. ([#1644](https://github.com/matrix-org/matrix-spec/issues/1644)) +- Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. ([#1776](https://github.com/matrix-org/matrix-spec/issues/1776)) +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Rename "recovery key" to "backup decryption key". ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). ([#1829](https://github.com/matrix-org/matrix-spec/issues/1829)) +- Fix various typos throughout the specification. ([#1832](https://github.com/matrix-org/matrix-spec/issues/1832), [#1841](https://github.com/matrix-org/matrix-spec/issues/1841), [#1852](https://github.com/matrix-org/matrix-spec/issues/1852), [#1853](https://github.com/matrix-org/matrix-spec/issues/1853)) +- Specify the encoding to be used when generating QR codes for device verification. ([#1839](https://github.com/matrix-org/matrix-spec/issues/1839)) +- Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. ([#1843](https://github.com/matrix-org/matrix-spec/issues/1843)) +- Use RFC 2119 keywords more consistently. ([#1846](https://github.com/matrix-org/matrix-spec/issues/1846), [#1861](https://github.com/matrix-org/matrix-spec/issues/1861)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) +- Clarify that relations recursion should be capped at a certain depth. ([#1854](https://github.com/matrix-org/matrix-spec/issues/1854)) +- Add missing secrets, third-party invites and room tagging modules to feature profiles table. ([#1860](https://github.com/matrix-org/matrix-spec/issues/1860)) +- Clarify when server name is used and link to the definition. ([#1862](https://github.com/matrix-org/matrix-spec/issues/1862)) +- Clarify where keys reside when checking an `m.room.encrypted` event. ([#1863](https://github.com/matrix-org/matrix-spec/issues/1863)) +- Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872)) + + +### Server-Server API + +**Deprecations** + +- Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858), [#1869](https://github.com/matrix-org/matrix-spec/issues/1869)) + +**Spec Clarifications** + +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. ([#1818](https://github.com/matrix-org/matrix-spec/issues/1818)) +- Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. ([#1834](https://github.com/matrix-org/matrix-spec/issues/1834), [#1840](https://github.com/matrix-org/matrix-spec/issues/1840)) +- Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. ([#1844](https://github.com/matrix-org/matrix-spec/issues/1844)) +- Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877)) + + +### Application Service API + +**Spec Clarifications** + +- Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810)) + + +### Identity Service API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) + + +### Push Gateway API + +No significant changes. + + +### Room Versions + +**Spec Clarifications** + +- Clarify that redaction events are still subject to all applicable auth rules. ([#1824](https://github.com/matrix-org/matrix-spec/issues/1824)) +- Fix various typos throughout the specification. ([#1827](https://github.com/matrix-org/matrix-spec/issues/1827), [#1848](https://github.com/matrix-org/matrix-spec/issues/1848)) +- Fix the rendering of the event format for room versions 1 and 2. ([#1883](https://github.com/matrix-org/matrix-spec/issues/1883)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884)) + + +### Appendices + +**Deprecations** + +- Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). ([#1823](https://github.com/matrix-org/matrix-spec/issues/1823)) + +**Spec Clarifications** + +- Define 'Opaque Identifier Grammar'. ([#1791](https://github.com/matrix-org/matrix-spec/issues/1791)) +- Define common cryptographic key representation. ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) + + +### Internal Changes/Tooling + +**Spec Clarifications** + +- Update the spec release process and related documentation. ([#1759](https://github.com/matrix-org/matrix-spec/issues/1759)) +- Fix npm release script for `@matrix-org/spec`. ([#1765](https://github.com/matrix-org/matrix-spec/issues/1765)) +- Formatting fixes in `CONTRIBUTING.rst`. ([#1769](https://github.com/matrix-org/matrix-spec/issues/1769)) +- Improve rendering on mobile devices. ([#1770](https://github.com/matrix-org/matrix-spec/issues/1770), [#1771](https://github.com/matrix-org/matrix-spec/issues/1771)) +- Fix the OpenAPI definition of the security schemes. ([#1772](https://github.com/matrix-org/matrix-spec/issues/1772)) +- Simplify uses of `resolve-refs` partial. ([#1773](https://github.com/matrix-org/matrix-spec/issues/1773)) +- Fix Hugo warnings. ([#1775](https://github.com/matrix-org/matrix-spec/issues/1775), [#1788](https://github.com/matrix-org/matrix-spec/issues/1788)) +- Fix `github-labels.rst`. ([#1781](https://github.com/matrix-org/matrix-spec/issues/1781)) +- Update dependencies. ([#1786](https://github.com/matrix-org/matrix-spec/issues/1786), [#1803](https://github.com/matrix-org/matrix-spec/issues/1803), [#1804](https://github.com/matrix-org/matrix-spec/issues/1804)) +- Solve `allOf` recursively in OpenAPI and JSON Schemas. ([#1787](https://github.com/matrix-org/matrix-spec/issues/1787)) +- Fix property type resolution in `render-object-table` partial. ([#1789](https://github.com/matrix-org/matrix-spec/issues/1789)) +- Factor out common definition of `Tag` type. ([#1793](https://github.com/matrix-org/matrix-spec/issues/1793)) +- Update the version of Hugo used to render the spec to v0.124.1. ([#1794](https://github.com/matrix-org/matrix-spec/issues/1794)) +- Add support for pattern formats for `patternProperties`. ([#1796](https://github.com/matrix-org/matrix-spec/issues/1796)) +- Clean up unnecessary `allOf`s in OpenAPI definitions. ([#1797](https://github.com/matrix-org/matrix-spec/issues/1797)) +- Show information about "Additional Properties" in object tables. ([#1798](https://github.com/matrix-org/matrix-spec/issues/1798)) +- Fix anchors for schemas under `oneOf`. ([#1799](https://github.com/matrix-org/matrix-spec/issues/1799)) +- Use reference to `OneTimeKeys` schema in OpenAPI definitions. ([#1800](https://github.com/matrix-org/matrix-spec/issues/1800)) +- Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. ([#1801](https://github.com/matrix-org/matrix-spec/issues/1801)) +- Add anchors in `definition` shortcode. ([#1802](https://github.com/matrix-org/matrix-spec/issues/1802)) +- Set python version for the Towncrier CI job. ([#1805](https://github.com/matrix-org/matrix-spec/issues/1805)) +- Replace `set-output` with environment files in CI. ([#1806](https://github.com/matrix-org/matrix-spec/issues/1806)) +- Render response headers. ([#1809](https://github.com/matrix-org/matrix-spec/issues/1809)) +- Use `patternProperties` in more places with supported formats. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Add support for rendering string formats. ([#1814](https://github.com/matrix-org/matrix-spec/issues/1814)) +- Refactor the OpenAPI definitions of the content repository endpoints. ([#1822](https://github.com/matrix-org/matrix-spec/issues/1822)) +- Clean up pull request template. ([#1831](https://github.com/matrix-org/matrix-spec/issues/1831)) +- Do not add empty arrays to examples. ([#1849](https://github.com/matrix-org/matrix-spec/issues/1849)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1851](https://github.com/matrix-org/matrix-spec/issues/1851), [#1885](https://github.com/matrix-org/matrix-spec/issues/1885)) +- Fix syntax errors in the spec release issue template. ([#1856](https://github.com/matrix-org/matrix-spec/issues/1856)) +- Use environment variables for Netlify build job. ([#1865](https://github.com/matrix-org/matrix-spec/issues/1865)) +- Render added/changed in info on request and response content types. ([#1876](https://github.com/matrix-org/matrix-spec/issues/1876)) +- Fix validation errors in generated HTML. ([#1880](https://github.com/matrix-org/matrix-spec/issues/1880)) +- Ensure most generated HTML IDs are unique. ([#1881](https://github.com/matrix-org/matrix-spec/issues/1881)) +- Allow to specify a prefix for generated HTML IDs of API endpoints. ([#1882](https://github.com/matrix-org/matrix-spec/issues/1882)) From 9f2891d95cc35401ec835436006ccde4cfb95ea5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 20 Jun 2024 10:25:12 -0600 Subject: [PATCH 41/60] Return to unstable --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index b2856375..6b669a79 100644 --- a/config.toml +++ b/config.toml @@ -64,14 +64,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. current_version_url = "https://spec.matrix.org/latest" # The following is used when status = "stable", and is displayed in various UI elements on a released version # of the spec. CI will set these values here automatically when a release git tag (i.e `v1.5`) is created. -major = "1" -minor = "11" -release_date = "June 20, 2024" +# major = "1" +# minor = "11" +# release_date = "June 20, 2024" # User interface configuration [params.ui] From 7820771fddbcd6008313fb65cea88786cabfdc00 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 25 Jun 2024 16:40:21 +0200 Subject: [PATCH 42/60] Clarify that room avatars cannot be encrypted (#1871) Fixes: #562 Signed-off-by: Johannes Marbach --- .../newsfragments/1871.clarification | 1 + .../msgtype_infos/avatar_info.yaml | 28 +++++++++++++++++++ data/event-schemas/schema/m.room.avatar.yaml | 2 +- 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1871.clarification create mode 100644 data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml diff --git a/changelogs/client_server/newsfragments/1871.clarification b/changelogs/client_server/newsfragments/1871.clarification new file mode 100644 index 00000000..fec9054e --- /dev/null +++ b/changelogs/client_server/newsfragments/1871.clarification @@ -0,0 +1 @@ +Clarify that room avatars cannot be encrypted. diff --git a/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml b/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml new file mode 100644 index 00000000..c21dfb48 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/msgtype_infos/avatar_info.yaml @@ -0,0 +1,28 @@ +description: Metadata about an avatar image. +properties: + h: + description: |- + The intended display height of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + w: + description: |- + The intended display width of the image in pixels. This may + differ from the intrinsic dimensions of the image file. + type: integer + mimetype: + description: The mimetype of the image, e.g. `image/jpeg`. + type: string + size: + description: Size of the image in bytes. + type: integer + thumbnail_url: + description: |- + The URL (typically [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris)) to a thumbnail of the image. + type: string + thumbnail_info: + allOf: + - $ref: thumbnail_info.yaml + description: Metadata about the image referred to in `thumbnail_url`. +title: AvatarInfo +type: object diff --git a/data/event-schemas/schema/m.room.avatar.yaml b/data/event-schemas/schema/m.room.avatar.yaml index a4777af4..5c6c7140 100644 --- a/data/event-schemas/schema/m.room.avatar.yaml +++ b/data/event-schemas/schema/m.room.avatar.yaml @@ -7,7 +7,7 @@ properties: properties: info: allOf: - - $ref: core-event-schema/msgtype_infos/image_info.yaml + - $ref: core-event-schema/msgtype_infos/avatar_info.yaml description: Metadata about the image referred to in `url`. url: description: |- From 7eda6ad2992da2e41e867c19af3f8c508f1b1ed6 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 25 Jun 2024 16:55:46 +0200 Subject: [PATCH 43/60] Improve recommendation for how to form transaction IDs (#1888) Fixes: #1706 Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1888.clarification | 1 + content/client-server-api/_index.md | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1888.clarification diff --git a/changelogs/client_server/newsfragments/1888.clarification b/changelogs/client_server/newsfragments/1888.clarification new file mode 100644 index 00000000..7ede3094 --- /dev/null +++ b/changelogs/client_server/newsfragments/1888.clarification @@ -0,0 +1 @@ +Improve recommendation for how to form transaction IDs. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8b40fe99..2acf7777 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -251,9 +251,10 @@ the request idempotent. The transaction ID should **only** be used for this purpose. -From the client perspective, after the request has finished, the `{txnId}` -value should be changed by for the next request (how is not specified; a -monotonically increasing integer is recommended). +After the request has finished, clients should change the `{txnId}` value for +the next request. How this is achieved, is left as an implementation detail. +It is recommended that clients use either version 4 UUIDs or a concatenation +of the current timestamp and a monotonically increasing integer. The homeserver should identify a request as a retransmission if the transaction ID is the same as a previous request, and the path of the From d7299b5a32236f6c21f9678f276d68a3d93b9581 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 26 Jun 2024 17:53:28 +0200 Subject: [PATCH 44/60] Rename and sort the modules in the feature profiles table for easier skimming (#1855) * Rename modules to match section titles. * Sort the table by requiredness, then alphabetically by module name. --- .../newsfragments/1855.clarification | 1 + content/client-server-api/_index.md | 58 +++++++++---------- 2 files changed, 30 insertions(+), 29 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1855.clarification diff --git a/changelogs/client_server/newsfragments/1855.clarification b/changelogs/client_server/newsfragments/1855.clarification new file mode 100644 index 00000000..7b178cf9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1855.clarification @@ -0,0 +1 @@ +Rename and sort the modules in the feature profiles table for easier skimming. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2acf7777..9558d536 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2727,45 +2727,45 @@ that profile. | Module / Profile | Web | Mobile | Desktop | CLI | Embedded | |------------------------------------------------------------|-----------|----------|----------|----------|----------| -| [Instant Messaging](#instant-messaging) | Required | Required | Required | Required | Optional | -| [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | +| [Content Repository](#content-repository) | Required | Required | Required | Optional | Optional | | [Direct Messaging](#direct-messaging) | Required | Required | Required | Required | Optional | -| [Mentions](#user-and-room-mentions) | Required | Required | Required | Optional | Optional | +| [Ignoring Users](#ignoring-users) | Required | Required | Required | Optional | Optional | +| [Instant Messaging](#instant-messaging) | Required | Required | Required | Required | Optional | | [Presence](#presence) | Required | Required | Required | Required | Optional | | [Push Notifications](#push-notifications) | Optional | Required | Optional | Optional | Optional | | [Receipts](#receipts) | Required | Required | Required | Required | Optional | -| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | -| [Typing Notifications](#typing-notifications) | Required | Required | Required | Required | Optional | -| [VoIP](#voice-over-ip) | Required | Required | Required | Optional | Optional | -| [Ignoring Users](#ignoring-users) | Required | Required | Required | Optional | Optional | -| [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | -| [Content Repository](#content-repository) | Required | Required | Required | Optional | Optional | -| [Managing History Visibility](#room-history-visibility) | Required | Required | Required | Required | Optional | -| [Server Side Search](#server-side-search) | Optional | Optional | Optional | Optional | Optional | +| [Room History Visibility](#room-history-visibility) | Required | Required | Required | Required | Optional | | [Room Upgrades](#room-upgrades) | Required | Required | Required | Required | Optional | -| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | -| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | -| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | -| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Typing Notifications](#typing-notifications) | Required | Required | Required | Required | Optional | +| [User and Room Mentions](#user-and-room-mentions) | Required | Required | Required | Optional | Optional | +| [Voice over IP](#voice-over-ip) | Required | Required | Required | Optional | Optional | +| [Client Config](#client-config) | Optional | Optional | Optional | Optional | Optional | | [Device Management](#device-management) | Optional | Optional | Optional | Optional | Optional | | [End-to-End Encryption](#end-to-end-encryption) | Optional | Optional | Optional | Optional | Optional | -| [Guest Accounts](#guest-access) | Optional | Optional | Optional | Optional | Optional | -| [Room Previews](#room-previews) | Optional | Optional | Optional | Optional | Optional | -| [Client Config](#client-config) | Optional | Optional | Optional | Optional | Optional | -| [SSO Login](#sso-client-loginauthentication) | Optional | Optional | Optional | Optional | Optional | -| [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | -| [Stickers](#sticker-messages) | Optional | Optional | Optional | Optional | Optional | -| [Server ACLs](#server-access-control-lists-acls-for-rooms) | Optional | Optional | Optional | Optional | Optional | -| [Server Notices](#server-notices) | Optional | Optional | Optional | Optional | Optional | -| [Moderation policies](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | -| [Spaces](#spaces) | Optional | Optional | Optional | Optional | Optional | -| [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | -| [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | +| [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | +| [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | +| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | +| [Guest Access](#guest-access) | Optional | Optional | Optional | Optional | Optional | +| [Moderation Policy Lists](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | +| [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | -| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | -| [Third-party Invites](#third-party-invites) | Optional | Required | Optional | Optional | Optional | +| [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | +| [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | +| [Room Previews](#room-previews) | Optional | Optional | Optional | Optional | Optional | | [Room Tagging](#room-tagging) | Optional | Optional | Optional | Optional | Optional | +| [SSO Client Login/Authentication](#sso-client-loginauthentication) | Optional | Optional | Optional | Optional | Optional | +| [Secrets](#secrets) | Optional | Optional | Optional | Optional | Optional | +| [Send-to-Device Messaging](#send-to-device-messaging) | Optional | Optional | Optional | Optional | Optional | +| [Server Access Control Lists (ACLs)](#server-access-control-lists-acls-for-rooms) | Optional | Optional | Optional | Optional | Optional | +| [Server Administration](#server-administration) | Optional | Optional | Optional | Optional | Optional | +| [Server Notices](#server-notices) | Optional | Optional | Optional | Optional | Optional | +| [Server Side Search](#server-side-search) | Optional | Optional | Optional | Optional | Optional | +| [Spaces](#spaces) | Optional | Optional | Optional | Optional | Optional | +| [Sticker Messages](#sticker-messages) | Optional | Optional | Optional | Optional | Optional | +| [Third-party Networks](#third-party-networks) | Optional | Optional | Optional | Optional | Optional | +| [Threading](#threading) | Optional | Optional | Optional | Optional | Optional | *Please see each module for more details on what clients need to implement.* From d528ff684b6cd625852f68fd287adc53ea952853 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 28 Jun 2024 14:14:32 +0200 Subject: [PATCH 45/60] Fix minor typos in third-party networks module (#1892) --- changelogs/client_server/newsfragments/1892.clarification | 1 + data/api/application-service/definitions/protocol.yaml | 8 ++++---- data/api/application-service/definitions/user.yaml | 2 +- data/api/client-server/third_party_lookup.yaml | 4 ++-- 4 files changed, 8 insertions(+), 7 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1892.clarification diff --git a/changelogs/client_server/newsfragments/1892.clarification b/changelogs/client_server/newsfragments/1892.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/client_server/newsfragments/1892.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/application-service/definitions/protocol.yaml b/data/api/application-service/definitions/protocol.yaml index c442a1b1..ff6300db 100644 --- a/data/api/application-service/definitions/protocol.yaml +++ b/data/api/application-service/definitions/protocol.yaml @@ -42,9 +42,9 @@ properties: example: "mxc://example.org/aBcDeFgH" field_types: description: |- - The type definitions for the fields defined in the `user_fields` and - `location_fields`. Each entry in those arrays MUST have an entry here. The - `string` key for this object is field name itself. + The type definitions for the fields defined in `user_fields` and + `location_fields`. Each entry in those arrays MUST have an entry here. + The `string` key for this object is the field name itself. May be an empty object if no fields are defined. type: object @@ -60,7 +60,7 @@ properties: may apply additional validation or filtering. type: string placeholder: - description: An placeholder serving as a valid example of the field value. + description: A placeholder serving as a valid example of the field value. type: string required: ['regexp', 'placeholder'] example: { diff --git a/data/api/application-service/definitions/user.yaml b/data/api/application-service/definitions/user.yaml index 3178b56d..62cac033 100644 --- a/data/api/application-service/definitions/user.yaml +++ b/data/api/application-service/definitions/user.yaml @@ -15,7 +15,7 @@ # TODO: Change userid to user_id as a breaking change properties: userid: - description: A Matrix User ID represting a third-party user. + description: A Matrix User ID representing a third-party user. type: string example: "@_gitter_jim:matrix.org" protocol: diff --git a/data/api/client-server/third_party_lookup.yaml b/data/api/client-server/third_party_lookup.yaml index 1abcb771..97547a6f 100644 --- a/data/api/client-server/third_party_lookup.yaml +++ b/data/api/client-server/third_party_lookup.yaml @@ -158,7 +158,7 @@ paths: schema: $ref: ../application-service/definitions/user_batch.yaml "404": - description: The Matrix User ID was not found + description: The Matrix User ID was not found. content: application/json: schema: @@ -232,7 +232,7 @@ paths: schema: $ref: ../application-service/definitions/user_batch.yaml "404": - description: The Matrix User ID was not found + description: The Matrix User ID was not found. content: application/json: schema: From 7bbc6a0b38827fa401a2475d219ab25c9a5fbe29 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Tue, 2 Jul 2024 15:52:26 +0100 Subject: [PATCH 46/60] Fix markup syntax in v2 state res (#1896) Signed-off-by: Stuart Mumford --- changelogs/room_versions/newsfragments/1896.clarification.rst | 1 + content/rooms/fragments/v2-state-res.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/room_versions/newsfragments/1896.clarification.rst diff --git a/changelogs/room_versions/newsfragments/1896.clarification.rst b/changelogs/room_versions/newsfragments/1896.clarification.rst new file mode 100644 index 00000000..402a3711 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1896.clarification.rst @@ -0,0 +1 @@ +Fix a formatting issue in v2 state res. diff --git a/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index 731070a7..658f9e77 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -138,7 +138,7 @@ The *resolution* of a set of states is obtained as follows: 1. Select the set *X* of all *power events* that appear in the *full conflicted set*. For each such power event *P*, enlarge *X* by adding the events in the auth chain of *P* which also belong to the full - conflicted set. Sort $X$ into a list using the *reverse topological + conflicted set. Sort *X* into a list using the *reverse topological power ordering*. 2. Apply the *iterative auth checks algorithm*, starting from the *unconflicted state map*, to the list of events from the previous From 7d94efe136bb9516666a940ebef51b4b6180240c Mon Sep 17 00:00:00 2001 From: davidegirardi <16451191+davidegirardi@users.noreply.github.com> Date: Wed, 3 Jul 2024 16:00:01 +0200 Subject: [PATCH 47/60] Spell out secure secret storage and sharing (#1875) Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: Travis Ralston --- changelogs/client_server/newsfragments/1875.clarification | 1 + content/client-server-api/modules/secrets.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1875.clarification diff --git a/changelogs/client_server/newsfragments/1875.clarification b/changelogs/client_server/newsfragments/1875.clarification new file mode 100644 index 00000000..4e627ea0 --- /dev/null +++ b/changelogs/client_server/newsfragments/1875.clarification @@ -0,0 +1 @@ +Document the acronyms and alternate names for the "Secrets" section. diff --git a/content/client-server-api/modules/secrets.md b/content/client-server-api/modules/secrets.md index 541ca877..3e586bc4 100644 --- a/content/client-server-api/modules/secrets.md +++ b/content/client-server-api/modules/secrets.md @@ -15,6 +15,9 @@ secret when storing, fetching, requesting, or sharing the secret. Secrets are plain strings; structured data can be stored by encoding it as a string. +The mechanism described in this section is known as "secure secret storage and +sharing", "SSSS", or "4S". + #### Storage When secrets are stored on the server, they are stored in the user's From e53e6ea8764b95f0bdb738549fca6f9f3f901298 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 5 Jul 2024 12:54:42 +0200 Subject: [PATCH 48/60] Fix callback function for fallback login (#1899) --- changelogs/client_server/newsfragments/1899.clarification | 1 + content/client-server-api/_index.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1899.clarification diff --git a/changelogs/client_server/newsfragments/1899.clarification b/changelogs/client_server/newsfragments/1899.clarification new file mode 100644 index 00000000..6edeff05 --- /dev/null +++ b/changelogs/client_server/newsfragments/1899.clarification @@ -0,0 +1 @@ +Clarify that the fallback login page calls `window.matrixLogin.onLogin` instead of `window.onLogin`. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 9558d536..be9a2384 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1401,7 +1401,7 @@ fallback login API: This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function -`window.onLogin` when login has been successfully completed. +`window.matrixLogin.onLogin` when login has been successfully completed. {{% added-in v="1.1" %}} Non-credential parameters valid for the `/login` endpoint can be provided as query string parameters here. These are to be From 5abc31111f28ec8b25cd9d834c0d7889aa2c61e1 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 8 Jul 2024 13:51:27 +0200 Subject: [PATCH 49/60] Clarify arguments of window.matrixLogin.onLogin (#1905) --- changelogs/client_server/newsfragments/1905.clarification | 1 + content/client-server-api/_index.md | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1905.clarification diff --git a/changelogs/client_server/newsfragments/1905.clarification b/changelogs/client_server/newsfragments/1905.clarification new file mode 100644 index 00000000..341391db --- /dev/null +++ b/changelogs/client_server/newsfragments/1905.clarification @@ -0,0 +1 @@ +Clarify that `window.matrixLogin.onLogin` is called with the response body of `POST /_matrix/client/v3/login`. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index be9a2384..a9c813c4 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1401,7 +1401,10 @@ fallback login API: This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function -`window.matrixLogin.onLogin` when login has been successfully completed. +`window.matrixLogin.onLogin(response)` when login has been successfully +completed. The argument, `response`, is the JSON response body of +[`POST /_matrix/client/v3/login`](#post_matrixclientv3login) parsed +into a JavaScript object. {{% added-in v="1.1" %}} Non-credential parameters valid for the `/login` endpoint can be provided as query string parameters here. These are to be From 2261c03bcdefa375a23425d79711af6e456a3426 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 9 Jul 2024 19:36:55 +0300 Subject: [PATCH 50/60] Clarify "real name" in contributor requirements (#1886) This updates the sign-off requirements to match what most other matrix-org and element-hq repos already have. The change was first made in synapse: https://github.com/matrix-org/synapse/pull/3467 Signed-off-by: Tulir Asokan --- CONTRIBUTING.rst | 12 ++++++++---- changelogs/internal/newsfragments/1886.clarification | 1 + 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 changelogs/internal/newsfragments/1886.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index f93b44f4..a1228769 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -163,10 +163,14 @@ include the line in your commit or pull request comment:: Signed-off-by: Your Name -...using your real name; unfortunately pseudonyms and anonymous contributions -can't be accepted. Git makes this trivial - just use the -s flag when you do -``git commit``, having first set ``user.name`` and ``user.email`` git configs -(which you should have done anyway :) +We accept contributions under a legally identifiable name, such as +your name on government documentation or common-law names (names +claimed by legitimate usage or repute). Unfortunately, we cannot +accept anonymous contributions at this time. + +Git allows you to add this signoff automatically when using the ``-s`` +flag to ``git commit``, which uses the name and email set in your +``user.name`` and ``user.email`` git configs. Private sign off ~~~~~~~~~~~~~~~~ diff --git a/changelogs/internal/newsfragments/1886.clarification b/changelogs/internal/newsfragments/1886.clarification new file mode 100644 index 00000000..4a21158c --- /dev/null +++ b/changelogs/internal/newsfragments/1886.clarification @@ -0,0 +1 @@ +Clarified "real name" in contributor requirements to match other matrix-org projects. From e4589bbc8a0e30187e7519e60b97e5867d8706ee Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 03:35:57 +0200 Subject: [PATCH 51/60] Clarify that dont_notify and coalesce MUST be gracefully ignored (#1890) --- .../client_server/newsfragments/1890.clarification | 1 + content/client-server-api/modules/push.md | 10 ++++++---- 2 files changed, 7 insertions(+), 4 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1890.clarification diff --git a/changelogs/client_server/newsfragments/1890.clarification b/changelogs/client_server/newsfragments/1890.clarification new file mode 100644 index 00000000..1e97a8e5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1890.clarification @@ -0,0 +1 @@ +Clarify that the deprecated `dont_notify` and `coalesce` push rule actions MUST be ignored, not rejected. diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 2d828a01..0b8e132e 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -184,11 +184,13 @@ they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. `{ "set_tweak": "sound", "value": "default" }`. -{{% boxes/note %}} +###### Historical Actions + Older versions of the Matrix specification included the `dont_notify` and -`coalesce` actions. These should both be considered no-ops (ignored, not -rejected) if received from a client. -{{% /boxes/note %}} +`coalesce` actions. Clients and homeservers MUST ignore these actions, for +instance, by stripping them from actions arrays they encounter. This means, +for example, that a rule with `["dont_notify"]` actions MUST be equivalent +to a rule with an empty actions array. ##### Conditions From b1349dd06ff477e45dc4fa4559d25e95d7f9b534 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 05:44:26 +0200 Subject: [PATCH 52/60] Remove the deprecated name attribute on HTML anchor elements (#1870) * Remove the deprecated name attribute on HTML anchor elements Fixes: #1790 Signed-off-by: Johannes Marbach * Add changelog * Update content/client-server-api/modules/instant_messaging.md Co-authored-by: Travis Ralston * Update content/client-server-api/modules/instant_messaging.md Co-authored-by: Travis Ralston * Update changelogs/client_server/newsfragments/1870.deprecation * Rename 1870.deprecation to 1870.removal --------- Signed-off-by: Johannes Marbach Co-authored-by: Travis Ralston Co-authored-by: Hubert Chathi --- changelogs/client_server/newsfragments/1870.removal | 1 + content/client-server-api/modules/instant_messaging.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1870.removal diff --git a/changelogs/client_server/newsfragments/1870.removal b/changelogs/client_server/newsfragments/1870.removal new file mode 100644 index 00000000..e7eddce8 --- /dev/null +++ b/changelogs/client_server/newsfragments/1870.removal @@ -0,0 +1 @@ +Remove the deprecated name attribute on HTML anchor elements as per [MSC4159](https://github.com/matrix-org/matrix-spec-proposals/pull/4159). diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index e35a1cdf..de388e9e 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -74,7 +74,7 @@ the tag. | Tag | Permitted Attributes | |--------|--------------------------------------------------------------------------------------------------------------------------------------------| | `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)), `data-mx-maths` (see [mathematical messages](#mathematical-messages)) | -| `a` | `name`, `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | +| `a` | `target`, `href` (provided the value is not relative and has a scheme matching one of: `https`, `http`, `ftp`, `mailto`, `magnet`) | | `img` | `width`, `height`, `alt`, `title`, `src` (provided it is a [Matrix Content (`mxc://`) URI](#matrix-content-mxc-uris)) | | `ol` | `start` | | `code` | `class` (only classes which start with `language-` for syntax highlighting) | From 40d5e48716c410b29c49ebd2e0c9ef1b9b57ca5f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 10 Jul 2024 18:13:37 +0200 Subject: [PATCH 53/60] Add missing references in capabilities table (#1897) * Add missing references in capabilities table Fixes: #1548 Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- .../newsfragments/1897.clarification | 1 + data/api/client-server/capabilities.yaml | 31 +++++++++++++------ 2 files changed, 23 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1897.clarification diff --git a/changelogs/client_server/newsfragments/1897.clarification b/changelogs/client_server/newsfragments/1897.clarification new file mode 100644 index 00000000..7bc903ba --- /dev/null +++ b/changelogs/client_server/newsfragments/1897.clarification @@ -0,0 +1 @@ +Add missing references to `m.set_displayname`, `m.set_avatar_url` and `m.3pid_changes` in capabilities table. diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 99f07962..fc5b47e2 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -46,16 +46,8 @@ paths: type: object properties: m.change_password: - type: object + $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change their password. - title: ChangePasswordCapability - properties: - enabled: - type: boolean - description: True if the user can change their password, false otherwise. - example: false - required: - - enabled m.room_versions: type: object description: The room versions the server supports. @@ -78,6 +70,16 @@ paths: required: - default - available + m.set_displayname: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change their display name. + m.set_avatar_url: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change their avatar. + m.3pid_changes: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can change 3PID associations + on their account. examples: response: value: { @@ -125,3 +127,14 @@ components: $ref: definitions/security.yaml#/accessTokenQuery accessTokenBearer: $ref: definitions/security.yaml#/accessTokenBearer + schemas: + booleanCapability: + type: object + title: BooleanCapability + properties: + enabled: + type: boolean + description: True if the user can perform the action, false otherwise. + example: false + required: + - enabled From cbe8092d8a629d3fbb5ce82fc071ef8dabfbeb86 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Mon, 15 Jul 2024 15:38:57 +0200 Subject: [PATCH 54/60] Spec for MSC2867 (Marking rooms as unread) (#1895) Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- .../client_server/newsfragments/1895.feature | 1 + content/client-server-api/_index.md | 2 +- .../client-server-api/modules/read_markers.md | 50 +++++++++++++++++-- .../examples/m.marked_unread.yaml | 7 +++ .../event-schemas/schema/m.marked_unread.yaml | 25 ++++++++++ 5 files changed, 80 insertions(+), 5 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1895.feature create mode 100644 data/event-schemas/examples/m.marked_unread.yaml create mode 100644 data/event-schemas/schema/m.marked_unread.yaml diff --git a/changelogs/client_server/newsfragments/1895.feature b/changelogs/client_server/newsfragments/1895.feature new file mode 100644 index 00000000..5e806a7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1895.feature @@ -0,0 +1 @@ +Add support for marking rooms as unread as per [MSC2867](https://github.com/matrix-org/matrix-spec-proposals/pull/2867). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index a9c813c4..7689ff13 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2749,7 +2749,7 @@ that profile. | [Event Annotations and reactions](#event-annotations-and-reactions) | Optional | Optional | Optional | Optional | Optional | | [Event Context](#event-context) | Optional | Optional | Optional | Optional | Optional | | [Event Replacements](#event-replacements) | Optional | Optional | Optional | Optional | Optional | -| [Fully read markers](#fully-read-markers) | Optional | Optional | Optional | Optional | Optional | +| [Read and Unread Markers](#read-and-unread-markers) | Optional | Optional | Optional | Optional | Optional | | [Guest Access](#guest-access) | Optional | Optional | Optional | Optional | Optional | | [Moderation Policy Lists](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | | [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index aa0baf47..55e73dd5 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -1,5 +1,6 @@ +### Read and unread markers -### Fully read markers +#### Fully read markers The history for a given room may be split into three sections: messages the user has read (or indicated they aren't interested in them), @@ -8,7 +9,7 @@ user hasn't seen yet. The "fully read marker" (also known as a "read marker") marks the last event of the first section, whereas the user's read receipt marks the last event of the second section. -#### Events +##### Events The user's fully read marker is kept as an event in the room's [account data](#client-config). The event may be read to determine the user's @@ -22,7 +23,7 @@ should be considered to be the user's read receipt location. {{% event event="m.fully_read" %}} -#### Client behaviour +##### Client behaviour The client cannot update fully read markers by directly modifying the `m.fully_read` account data event. Instead, the client must make use of @@ -41,7 +42,7 @@ might wish to save an extra HTTP call. Providing `m.read` and/or {{% http-api spec="client-server" api="read_markers" %}} -#### Server behaviour +##### Server behaviour The server MUST prevent clients from setting `m.fully_read` directly in room account data. The server must additionally ensure that it treats @@ -53,3 +54,44 @@ Upon updating the `m.fully_read` event due to a request to `/read_markers`, the server MUST send the updated account data event through to the client via the event stream (eg: `/sync`), provided any applicable filters are also satisfied. + +#### Unread markers + +Clients may use "unread markers" to allow users to label rooms for later +attention irrespective of [read receipts](#receipts) or +[fully read markers](#fully-read-markers). + +##### Events + +The user's unread marker in a room is kept under an `m.marked_unread` +event in the room's [account data](#client-config). The event may be read +to determine the user's current unread marker state in the room. Just +like other account data events, the event will be pushed down the event +stream when updated. + +{{% event event="m.marked_unread" %}} + +##### Client behaviour + +Clients MUST update unread markers by directly modifying the `m.marked_unread` +room account data event. When marking a room as unread, clients SHOULD NOT change +the `m.fully_read` marker, so that the user's read position in the room is +retained. + +When the `unread` field is `true`, clients SHOULD visually annotate the room +to indicate that it is unread. Exactly how this is achieved is left as an +implementation detail. It is RECOMMENDED that clients use a treatment similar +to how they represent rooms with unread notifications. + +Clients SHOULD reset the unread marker by setting `unread` to `false` when +opening a room to display its timeline. + +Clients that offer functionality to mark a room as _read_ by sending a read +receipt for the last event, SHOULD reset the unread marker simultaneously. + +If the `m.marked_unread` event does not exist on the user's account data, +clients MUST behave as if `unread` was `false`. + +##### Server behaviour + +Servers have no additional requirements placed on them by this submodule. diff --git a/data/event-schemas/examples/m.marked_unread.yaml b/data/event-schemas/examples/m.marked_unread.yaml new file mode 100644 index 00000000..b9937196 --- /dev/null +++ b/data/event-schemas/examples/m.marked_unread.yaml @@ -0,0 +1,7 @@ +{ + "$ref": "core/event.json", + "type": "m.marked_unread", + "content": { + "unread": true + } +} diff --git a/data/event-schemas/schema/m.marked_unread.yaml b/data/event-schemas/schema/m.marked_unread.yaml new file mode 100644 index 00000000..56b3ba62 --- /dev/null +++ b/data/event-schemas/schema/m.marked_unread.yaml @@ -0,0 +1,25 @@ +{ + "type": "object", + "title": "Unread Marker Event", + "description": "The current state of the user's unread marker in a room. This event appears in the user's room account data for the room the marker is applicable for.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "content": { + "type": "object", + "properties": { + "unread": { + "type": "boolean", + "description": "Whether the room is marked unread or not." + } + }, + "required": ["unread"] + }, + "type": { + "type": "string", + "enum": ["m.marked_unread"] + } + }, + "required": ["type", "content"] +} From c8eb7f552678b7522ad5f65fb0b3651b68e3f82f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 17 Jul 2024 00:15:44 +0200 Subject: [PATCH 55/60] Document the removal changelog category (#1907) * Document the removal changelog category Signed-off-by: Johannes Marbach * Add changelog --------- Signed-off-by: Johannes Marbach --- CONTRIBUTING.rst | 2 ++ changelogs/internal/newsfragments/1907.clarification | 1 + 2 files changed, 3 insertions(+) create mode 100644 changelogs/internal/newsfragments/1907.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a1228769..def7ced2 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -99,6 +99,8 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: * ``deprecation`` - Used when deprecating something. +* ``removal`` - Used when removing something that was unused or previously deprecated. + All news fragments must have a brief summary explaining the change in the contents of the file. The summary must end in a full stop to be in line with the style guide and formatting must be done using Markdown. diff --git a/changelogs/internal/newsfragments/1907.clarification b/changelogs/internal/newsfragments/1907.clarification new file mode 100644 index 00000000..9185f533 --- /dev/null +++ b/changelogs/internal/newsfragments/1907.clarification @@ -0,0 +1 @@ +Document the `removal` changelog category. From 149d5d2a959de088f9b3f13c329b0c8ecc17a14c Mon Sep 17 00:00:00 2001 From: Matthias Ahouansou Date: Wed, 17 Jul 2024 14:26:28 +0000 Subject: [PATCH 56/60] remove confusing description of restricted rooms with no valid conditions (#1903) --- changelogs/client_server/newsfragments/1903.clarification | 1 + content/client-server-api/_index.md | 3 --- 2 files changed, 1 insertion(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1903.clarification diff --git a/changelogs/client_server/newsfragments/1903.clarification b/changelogs/client_server/newsfragments/1903.clarification new file mode 100644 index 00000000..3ec46ef2 --- /dev/null +++ b/changelogs/client_server/newsfragments/1903.clarification @@ -0,0 +1 @@ +Remove confusing description of restricted rooms with no valid conditions. diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 7689ff13..ba013735 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2574,9 +2574,6 @@ join is happening over federation, the remote server will check the conditions before accepting the join. See the [Server-Server Spec](/server-server-api/#restricted-rooms) for more information. -If the room is `restricted` but no valid conditions are presented then the -room is effectively invite only. - The user does not need to maintain the conditions in order to stay a member of the room: the conditions are only checked/evaluated during the join process. From d9c447e194180df5efa75ab25803d317d7df5f7f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Fri, 19 Jul 2024 12:13:10 +0200 Subject: [PATCH 57/60] Document m.get_login_token capability (#1908) --- .../newsfragments/1908.clarification | 1 + content/client-server-api/_index.md | 21 +++++++++++++++++++ data/api/client-server/capabilities.yaml | 4 ++++ data/api/client-server/login_token.yaml | 6 +++--- 4 files changed, 29 insertions(+), 3 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1908.clarification diff --git a/changelogs/client_server/newsfragments/1908.clarification b/changelogs/client_server/newsfragments/1908.clarification new file mode 100644 index 00000000..d9dc2e8c --- /dev/null +++ b/changelogs/client_server/newsfragments/1908.clarification @@ -0,0 +1 @@ +Document the `m.get_login_token` capability as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index ba013735..1a6f1c6e 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1654,6 +1654,27 @@ An example of the capability API's response for this capability is: } ``` +### `m.get_login_token` capability + +This capability has a single flag, `enabled`, to denote whether the user +is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) +to generate single-use, time-limited tokens to log unauthenticated clients +into their account. + +When not listed, clients SHOULD assume the user is unable to generate tokens. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.get_login_token": { + "enabled": false + } + } +} +``` + ## Filtering Filters can be created on the server and can be passed as a parameter to diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index fc5b47e2..3ae26b22 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -80,6 +80,10 @@ paths: $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change 3PID associations on their account. + m.get_login_token: + $ref: '#/components/schemas/booleanCapability' + description: Capability to indicate if the user can generate tokens to log further + clients into their account. examples: response: value: { diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml index 19fa350e..f14e1a0a 100644 --- a/data/api/client-server/login_token.yaml +++ b/data/api/client-server/login_token.yaml @@ -33,7 +33,7 @@ paths: Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes this feature if the server is not offering it. Authenticated clients can check for support on - a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + a per-user basis with the [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability, while unauthenticated clients can detect server support by looking for an `m.login.token` login flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). @@ -98,8 +98,8 @@ paths: The request was malformed, or the user does not have an ability to generate tokens for their devices, as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). - Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` - [capability](/client-server-api/#capabilities-negotiation). + Clients should verify whether the user has an ability to call this endpoint with the + [`m.get_login_token`](/client-server-api/#mget_login_token-capability) capability. content: application/json: schema: From 2017515ca96c82feb1c4b84a56d31c9c896363c0 Mon Sep 17 00:00:00 2001 From: Josh Simmons Date: Thu, 25 Jul 2024 16:41:12 -0700 Subject: [PATCH 58/60] update DCO, no legal name needed (#1914) * update DCO, no legal name needed * add a changelog entry, if needed * add necessary fullstop for style guide --------- Co-authored-by: Josh Simmons --- CONTRIBUTING.rst | 19 +------------------ .../internal/newsfragments/1914.clarification | 1 + 2 files changed, 2 insertions(+), 18 deletions(-) create mode 100644 changelogs/internal/newsfragments/1914.clarification diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index def7ced2..eb3c30f6 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -165,23 +165,6 @@ include the line in your commit or pull request comment:: Signed-off-by: Your Name -We accept contributions under a legally identifiable name, such as -your name on government documentation or common-law names (names -claimed by legitimate usage or repute). Unfortunately, we cannot -accept anonymous contributions at this time. - Git allows you to add this signoff automatically when using the ``-s`` flag to ``git commit``, which uses the name and email set in your -``user.name`` and ``user.email`` git configs. - -Private sign off -~~~~~~~~~~~~~~~~ - -If you would like to provide your legal name privately to the Matrix.org -Foundation (instead of in a public commit or comment), you can do so by emailing -your legal name and a link to the pull request to dco@matrix.org. It helps to -include "sign off" or similar in the subject line. You will then be instructed -further. - -Once private sign off is complete, doing so for future contributions will not -be required. +``user.name`` and ``user.email`` git configs. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1914.clarification b/changelogs/internal/newsfragments/1914.clarification new file mode 100644 index 00000000..bbf1f102 --- /dev/null +++ b/changelogs/internal/newsfragments/1914.clarification @@ -0,0 +1 @@ +The Matrix.org Foundation no longer requires "real" or "legally identifiable" names in order to contribute to projects. From 5d91b628c9482bbea96155f77813d0e3f29b8a55 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 30 Jul 2024 19:37:29 +0200 Subject: [PATCH 59/60] Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint (#1910) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1910.clarification | 1 + data/api/client-server/profile.yaml | 3 +-- 2 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1910.clarification diff --git a/changelogs/client_server/newsfragments/1910.clarification b/changelogs/client_server/newsfragments/1910.clarification new file mode 100644 index 00000000..3664eaf6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1910.clarification @@ -0,0 +1 @@ +Don't mention that `GET /_matrix/client/v3/profile/{userId}` can return additional properties because this is true for almost every endpoint. diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index e00bdd96..1a55084c 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -195,8 +195,7 @@ paths: description: |- Get the combined profile information for this user. This API may be used to fetch the user's own profile information or other users; either - locally or on remote homeservers. This API may return keys which are not - limited to `displayname` or `avatar_url`. + locally or on remote homeservers. operationId: getUserProfile parameters: - in: path From 9bac118aec7a95740610147013753b3de687bd1a Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Tue, 30 Jul 2024 19:37:49 +0200 Subject: [PATCH 60/60] Clarify that the `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type (#1909) Signed-off-by: Johannes Marbach --- changelogs/client_server/newsfragments/1909.clarification | 1 + data/api/client-server/definitions/user_identifier.yaml | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1909.clarification diff --git a/changelogs/client_server/newsfragments/1909.clarification b/changelogs/client_server/newsfragments/1909.clarification new file mode 100644 index 00000000..da6575cd --- /dev/null +++ b/changelogs/client_server/newsfragments/1909.clarification @@ -0,0 +1 @@ +The `User identifier` object in `POST /_matrix/client/v3/login` contains additional properties that depend on the identification type. diff --git a/data/api/client-server/definitions/user_identifier.yaml b/data/api/client-server/definitions/user_identifier.yaml index 7e6eca9c..add848fd 100644 --- a/data/api/client-server/definitions/user_identifier.yaml +++ b/data/api/client-server/definitions/user_identifier.yaml @@ -18,7 +18,10 @@ type: object properties: type: type: string - description: The type of identification. See [Identifier types](/client-server-api/#identifier-types) for supported values and additional property descriptions. + description: |- + The type of identification. See [Identifier types](/client-server-api/#identifier-types) + for supported values and additional property descriptions. required: - type -additionalProperties: true +additionalProperties: + description: Keys dependent on the identification type.