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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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/14] 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