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/.github/workflows/main.yml b/.github/workflows/main.yml index 09a184a7..fe0c77a4 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -177,7 +177,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: changelog-artifact - path: content/changelog/vUNSTABLE.md + path: content/changelog/unstable.md build-spec: name: "📖 Build the spec" @@ -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/.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/.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/CONTRIBUTING.rst b/CONTRIBUTING.rst index f93b44f4..eb3c30f6 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. @@ -163,19 +165,6 @@ 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 :) - -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. +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. \ No newline at end of file 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/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 350e39cd..c2ec03c6 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -40,15 +40,17 @@ $table-bg: $secondary-lightest-background; $td-enable-google-fonts: false; /* - * Replace the default font with Inter. - * - * The $font-family-sans-serif definition here overrides the default value set by docsy: - * https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68 - * and adds "Inter" to the front. - * - * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html. + * The $font-family-sans-serif definition here overrides the default value set by docsy + * (https://github.com/matrix-org/docsy/blob/66a4e61d2d34edc7196b9df83a7d09cd4af14b47/assets/scss/_variables.scss#L68) */ -$font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; +$font-family-sans-serif: + // Add "Inter" to the front, making it the default. The font itself is loaded via stylesheet + // links in layouts/partials/hooks/head-end.html. + "Inter", + -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", + // Insert fonts suited for mathematical symbols on different platforms before "Arial" + "STIX Two Math", "Cambria Math", "Noto Sans Math", "Dejavu Sans", + Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; // Disable smooth scrolling as it makes TOC highlighting jump during the transition. $enable-smooth-scroll: false; 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/1928.clarification b/changelogs/appendices/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/appendices/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/application_service/newsfragments/1772.clarification b/changelogs/application_service/newsfragments/1772.clarification deleted file mode 100644 index b2aafa0d..00000000 --- a/changelogs/application_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/application_service/newsfragments/1810.clarification b/changelogs/application_service/newsfragments/1810.clarification deleted file mode 100644 index 66dab495..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/application_service/newsfragments/1928.clarification b/changelogs/application_service/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/application_service/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.clarification deleted file mode 100644 index 65c5ba36..00000000 --- a/changelogs/client_server/newsfragments/1755.clarification +++ /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 3471c1b9..00000000 --- a/changelogs/client_server/newsfragments/1757.feature +++ /dev/null @@ -1 +0,0 @@ -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 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/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.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/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 af643e2e..00000000 --- a/changelogs/client_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Use `patternProperties` in more places with supported formats. diff --git a/changelogs/client_server/newsfragments/1816.clarification b/changelogs/client_server/newsfragments/1816.clarification deleted file mode 100644 index e1b97854..00000000 --- a/changelogs/client_server/newsfragments/1816.clarification +++ /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/1822.clarification b/changelogs/client_server/newsfragments/1822.clarification deleted file mode 100644 index 034deb48..00000000 --- a/changelogs/client_server/newsfragments/1822.clarification +++ /dev/null @@ -1 +0,0 @@ -Refactor the OpenAPI definitions of the content repository endpoints. 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/1842.removal b/changelogs/client_server/newsfragments/1842.removal new file mode 100644 index 00000000..cd9124c9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1842.removal @@ -0,0 +1 @@ +Remove references to device-specific push rules. diff --git a/changelogs/client_server/newsfragments/1846.clarification b/changelogs/client_server/newsfragments/1846.clarification deleted file mode 100644 index 6f57eb35..00000000 --- a/changelogs/client_server/newsfragments/1846.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that per-request UIA for /login/get_token is an RFC 2119 MUST requirement. diff --git a/changelogs/client_server/newsfragments/1847.feature b/changelogs/client_server/newsfragments/1847.feature deleted file mode 100644 index 25d1914b..00000000 --- a/changelogs/client_server/newsfragments/1847.feature +++ /dev/null @@ -1 +0,0 @@ -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/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/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/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/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/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/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/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/changelogs/client_server/newsfragments/1832.clarification b/changelogs/client_server/newsfragments/1892.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1832.clarification rename to changelogs/client_server/newsfragments/1892.clarification 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/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/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/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/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/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/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/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/changelogs/client_server/newsfragments/1916.clarification b/changelogs/client_server/newsfragments/1916.clarification new file mode 100644 index 00000000..936c3111 --- /dev/null +++ b/changelogs/client_server/newsfragments/1916.clarification @@ -0,0 +1 @@ +Improve wording of the unauthenticated media deprecation box. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1920.clarification b/changelogs/client_server/newsfragments/1920.clarification new file mode 100644 index 00000000..007bba3d --- /dev/null +++ b/changelogs/client_server/newsfragments/1920.clarification @@ -0,0 +1 @@ +Additional properties in `.well-known/matrix/client` don't have to be objects. diff --git a/changelogs/client_server/newsfragments/1928.clarification b/changelogs/client_server/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/client_server/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1933.deprecation b/changelogs/client_server/newsfragments/1933.deprecation new file mode 100644 index 00000000..b65ebdc7 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.deprecation @@ -0,0 +1 @@ +Deprecate the `server_name` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/changelogs/client_server/newsfragments/1933.feature b/changelogs/client_server/newsfragments/1933.feature new file mode 100644 index 00000000..030b5a00 --- /dev/null +++ b/changelogs/client_server/newsfragments/1933.feature @@ -0,0 +1 @@ +Add `via` query parameter on `/_matrix/client/v3/join/{roomIdOrAlias}` and `/_matrix/client/v3/knock/{roomIdOrAlias}` as per [MSC4156](https://github.com/matrix-org/matrix-spec-proposals/pull/4156). diff --git a/changelogs/client_server/newsfragments/1934.feature b/changelogs/client_server/newsfragments/1934.feature new file mode 100644 index 00000000..75b55688 --- /dev/null +++ b/changelogs/client_server/newsfragments/1934.feature @@ -0,0 +1 @@ +Add account locking as per [MSC3939](https://github.com/matrix-org/matrix-spec-proposals/pull/3939). diff --git a/changelogs/client_server/newsfragments/1935.clarification b/changelogs/client_server/newsfragments/1935.clarification new file mode 100644 index 00000000..de90b5da --- /dev/null +++ b/changelogs/client_server/newsfragments/1935.clarification @@ -0,0 +1 @@ +Specify `Content-Type` and `Content-Disposition` usage in the media repo, as per [MSC2701](https://github.com/matrix-org/matrix-spec-proposals/pull/2701) and [MSC2702](https://github.com/matrix-org/matrix-spec-proposals/pull/2702). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1941.feature b/changelogs/client_server/newsfragments/1941.feature new file mode 100644 index 00000000..5e806a7f --- /dev/null +++ b/changelogs/client_server/newsfragments/1941.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/changelogs/client_server/newsfragments/1945.clarification b/changelogs/client_server/newsfragments/1945.clarification new file mode 100644 index 00000000..651ea6d3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1945.clarification @@ -0,0 +1 @@ +Additional keys in `GET /capabilities` don't have to be objects. diff --git a/changelogs/client_server/newsfragments/1959.feature b/changelogs/client_server/newsfragments/1959.feature new file mode 100644 index 00000000..0fdd25f1 --- /dev/null +++ b/changelogs/client_server/newsfragments/1959.feature @@ -0,0 +1 @@ +Guest accounts can now download/thumbnail media from the new authenticated endpoints, as per [MSC4189](https://github.com/matrix-org/matrix-spec-proposals/pull/4189). \ No newline at end of file diff --git a/changelogs/header.md b/changelogs/header.md index 21b35106..a8fd04ba 100644 --- a/changelogs/header.md +++ b/changelogs/header.md @@ -6,11 +6,10 @@ Variables: DATE = Replaced by the date (eg: April 01, 2021) --> -## VERSION - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/VERSION
Release dateDATE
Checklistchecklist.md
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/1928.clarification b/changelogs/identity_service/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/identity_service/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. 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 ebf8030d..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 e5fb516f..00000000 --- a/changelogs/internal/newsfragments/1770.clarification +++ /dev/null @@ -1 +0,0 @@ -Reduce whitespace on mobile viewports diff --git a/changelogs/internal/newsfragments/1771.clarification b/changelogs/internal/newsfragments/1771.clarification deleted file mode 100644 index b1941e18..00000000 --- a/changelogs/internal/newsfragments/1771.clarification +++ /dev/null @@ -1 +0,0 @@ -Arrange rows in `.basic-info` tables vertically when horizontal space is constrained. 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 4fb58650..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 1810c632..00000000 --- a/changelogs/internal/newsfragments/1786.clarification +++ /dev/null @@ -1 +0,0 @@ -Upgrade jsonschema and python-jsonpath CI scripts dependencies. 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.misc b/changelogs/internal/newsfragments/1793.misc deleted file mode 100644 index bc5abca9..00000000 --- a/changelogs/internal/newsfragments/1793.misc +++ /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 dbfaa8c9..00000000 --- a/changelogs/internal/newsfragments/1803.clarification +++ /dev/null @@ -1 +0,0 @@ -Update most CI actions. diff --git a/changelogs/internal/newsfragments/1804.clarification b/changelogs/internal/newsfragments/1804.clarification deleted file mode 100644 index 39249cb8..00000000 --- a/changelogs/internal/newsfragments/1804.clarification +++ /dev/null @@ -1 +0,0 @@ -Update typos CI action. 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/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/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/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/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. 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. 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. diff --git a/changelogs/internal/newsfragments/1919.clarification b/changelogs/internal/newsfragments/1919.clarification new file mode 100644 index 00000000..478404e9 --- /dev/null +++ b/changelogs/internal/newsfragments/1919.clarification @@ -0,0 +1 @@ +Use dedicated fonts for better support of mathematical symbols. diff --git a/changelogs/internal/newsfragments/1928.clarification b/changelogs/internal/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/internal/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/internal/newsfragments/1937.clarification b/changelogs/internal/newsfragments/1937.clarification new file mode 100644 index 00000000..f54b5bf6 --- /dev/null +++ b/changelogs/internal/newsfragments/1937.clarification @@ -0,0 +1 @@ +Provide markdown checklists for changelogs under `/changelog/$VERSION/checklist.md`. diff --git a/changelogs/internal/newsfragments/1940.clarification b/changelogs/internal/newsfragments/1940.clarification new file mode 100644 index 00000000..15885433 --- /dev/null +++ b/changelogs/internal/newsfragments/1940.clarification @@ -0,0 +1 @@ +Add the `deprecated` field to properties of OpenAPI definitions and JSON Schemas. diff --git a/changelogs/internal/newsfragments/1954.clarification b/changelogs/internal/newsfragments/1954.clarification new file mode 100644 index 00000000..c0b1bdb4 --- /dev/null +++ b/changelogs/internal/newsfragments/1954.clarification @@ -0,0 +1 @@ +Exclude markdown checklists from alternate output formats. diff --git a/changelogs/internal/newsfragments/1956.clarification b/changelogs/internal/newsfragments/1956.clarification new file mode 100644 index 00000000..6b6213fc --- /dev/null +++ b/changelogs/internal/newsfragments/1956.clarification @@ -0,0 +1 @@ +Use relative permalink to redirect to latest changelog. diff --git a/changelogs/push_gateway/newsfragments/1928.clarification b/changelogs/push_gateway/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/push_gateway/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. 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 c122052d..00000000 --- a/changelogs/room_versions/newsfragments/1827.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix minor spelling mistake of object being spelt "obiect". 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/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/changelogs/room_versions/newsfragments/1928.clarification b/changelogs/room_versions/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/room_versions/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. 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 deleted file mode 100644 index af643e2e..00000000 --- a/changelogs/server_server/newsfragments/1813.clarification +++ /dev/null @@ -1 +0,0 @@ -Use `patternProperties` in more places with supported formats. 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 fa927cca..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 `join_authorised_via_users_server` was present in the `content` field of the request. diff --git a/changelogs/server_server/newsfragments/1918.clarification b/changelogs/server_server/newsfragments/1918.clarification new file mode 100644 index 00000000..ff9274d4 --- /dev/null +++ b/changelogs/server_server/newsfragments/1918.clarification @@ -0,0 +1 @@ +Remove `origin` field from PDU example because it doesn't exist in the schema anymore. diff --git a/changelogs/server_server/newsfragments/1928.clarification b/changelogs/server_server/newsfragments/1928.clarification new file mode 100644 index 00000000..e959ef1f --- /dev/null +++ b/changelogs/server_server/newsfragments/1928.clarification @@ -0,0 +1 @@ +Document that the spec uses RFC 2119. Contributed by @HarHarLinks. diff --git a/changelogs/server_server/newsfragments/1930.clarification b/changelogs/server_server/newsfragments/1930.clarification new file mode 100644 index 00000000..facff83c --- /dev/null +++ b/changelogs/server_server/newsfragments/1930.clarification @@ -0,0 +1 @@ +Fix required fields in `/_matrix/key/v2/server` response schema. diff --git a/changelogs/server_server/newsfragments/1946.clarification b/changelogs/server_server/newsfragments/1946.clarification new file mode 100644 index 00000000..baf02987 --- /dev/null +++ b/changelogs/server_server/newsfragments/1946.clarification @@ -0,0 +1 @@ + Use "server name" instead of "DNS name" to avoid confusion with the "DNS name" component of "server names" as defined in the appendices. \ No newline at end of file diff --git a/changelogs/template.md.jinja b/changelogs/template.md.jinja index 38de4b92..cc456efd 100644 --- a/changelogs/template.md.jinja +++ b/changelogs/template.md.jinja @@ -1,7 +1,7 @@ {% for section_name, section in sections.items() %} {% if section_name %} -### {{section_name}} +## {{section_name}} {% endif %} {% if section %} diff --git a/config.toml b/config.toml index a4245d0b..ebead0e2 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 @@ -66,8 +70,8 @@ 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" +# minor = "11" +# release_date = "June 20, 2024" # User interface configuration [params.ui] @@ -130,7 +134,16 @@ 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 + +# custom output formats + +[outputFormats] + [outputFormats.Checklist] + mediaType = "text/markdown" + isPlainText = true + baseName = "checklist" + notAlternative = true diff --git a/content/_index.md b/content/_index.md index a8c53809..ba49dc3a 100644 --- a/content/_index.md +++ b/content/_index.md @@ -99,6 +99,20 @@ services - be that for instant messages, VoIP call setups, or any other objects that need to be reliably and persistently pushed from A to B in an interoperable and federated manner. +### Requirement levels + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" across all parts of the +specification are to be interpreted as described in +[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +Some entire sections of the specification might be optional depending on the +circumstances. For example, the +[modules of the client-server API](/client-server-api/#modules) +apply depending on the use case. The requirement level expressed by the above +key words appearing in such a section is only relevant if the section itself is +applicable. + ### Spec Change Proposals To propose a change to the Matrix Spec, see the explanations at 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/changelog/_index.md b/content/changelog/_index.md new file mode 100644 index 00000000..ccb55f6f --- /dev/null +++ b/content/changelog/_index.md @@ -0,0 +1,7 @@ +--- +title: Changelog +type: docs +weight: 1000 +--- + +{{% changelog/changelogs %}} diff --git a/content/changelog/index.md b/content/changelog/historical.md similarity index 82% rename from content/changelog/index.md rename to content/changelog/historical.md index 560cb43b..72f1d9a2 100644 --- a/content/changelog/index.md +++ b/content/changelog/historical.md @@ -1,18 +1,15 @@ --- -title: Changelog +title: Historical versions type: docs -weight: 1000 +outputs: + - html --- -{{% changelog/changelog-description %}} +Before version 1.1, versioning was applied at the level of individual API specifications. +This section includes links to these versions of the APIs. -{{% changelog/changelogs %}} +## Client-Server API -

Historical versions

- -Before version 1.1, versioning was applied at the level of individual API specifications. This section includes links to these versions of the APIs. - -* **Client-Server API** - [r0.6.1](https://matrix.org/docs/spec/client_server/r0.6.1.html) - [r0.6.0](https://matrix.org/docs/spec/client_server/r0.6.0.html) - [r0.5.0](https://matrix.org/docs/spec/client_server/r0.5.0.html) @@ -26,22 +23,26 @@ Before version 1.1, versioning was applied at the level of individual API specif The last draft before the spec was formally released in version r0.0.0. -* **Server-Server API** +## Server-Server API + - [r0.1.4](https://matrix.org/docs/spec/server_server/r0.1.4.html) - [r0.1.3](https://matrix.org/docs/spec/server_server/r0.1.3.html) - [r0.1.2](https://matrix.org/docs/spec/server_server/r0.1.2.html) - [r0.1.1](https://matrix.org/docs/spec/server_server/r0.1.1.html) - [r0.1.0](https://matrix.org/docs/spec/server_server/r0.1.0.html) -* **Application Service API** +## Application Service API + - [r0.1.1](https://matrix.org/docs/spec/application_service/r0.1.1.html) - [r0.1.0](https://matrix.org/docs/spec/application_service/r0.1.0.html) -* **Identity Service API** +## Identity Service API + - [r0.3.0](https://matrix.org/docs/spec/identity_service/r0.3.0.html) - [r0.2.1](https://matrix.org/docs/spec/identity_service/r0.2.1.html) - [r0.2.0](https://matrix.org/docs/spec/identity_service/r0.2.0.html) - [r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html) -* **Push Gateway API** +## Push Gateway API + - [r0.1.0](https://matrix.org/docs/spec/push_gateway/r0.1.0.html) diff --git a/content/changelog/v1.1.md b/content/changelog/v1.1.md index 8cf43878..91a79581 100644 --- a/content/changelog/v1.1.md +++ b/content/changelog/v1.1.md @@ -1,4 +1,10 @@ --- +title: v1.1 Changelog +linkTitle: v1.1 +type: docs +outputs: + - html + - checklist date: 2021-11-09T00:00:00+0000 --- -## v1.1 - +
Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.1
Release dateNovember 09, 2021
Checklistchecklist.md
-### Client-Server API +## Client-Server API Breaking Changes @@ -110,7 +115,7 @@ Variables: - Fix documentation errors around `threepid_creds`. ([#3471](https://github.com/matrix-org/matrix-doc/issues/3471)) -### Server-Server API +## Server-Server API New Endpoints @@ -136,7 +141,7 @@ Variables: - Tweak the example PDU diagram to better demonstrate situations with multiple `prev_events`. ([#3340](https://github.com/matrix-org/matrix-doc/issues/3340)) -### Application Service API +## Application Service API Spec Clarifications @@ -145,7 +150,7 @@ Variables: - Fix various typos throughout the specification. ([#2888](https://github.com/matrix-org/matrix-doc/issues/2888)) -### Identity Service API +## Identity Service API New Endpoints @@ -168,7 +173,7 @@ Variables: - Describe how [MSC2844](https://github.com/matrix-org/matrix-doc/pull/2844) affects the `/versions` endpoint. ([#3459](https://github.com/matrix-org/matrix-doc/issues/3459)) -### Push Gateway API +## Push Gateway API Spec Clarifications diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md index 16b3217d..38fb0501 100644 --- a/content/changelog/v1.10.md +++ b/content/changelog/v1.10.md @@ -1,4 +1,10 @@ --- +title: v1.10 Changelog +linkTitle: v1.10 +type: docs +outputs: + - html + - checklist date: 2024-03-22T09:59:45-06:00 --- -## v1.10 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.10
Release dateMarch 22, 2024
Checklistchecklist.md
-### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -50,7 +55,7 @@ Variables: - Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763)) -### Server-Server API +## Server-Server API **Spec Clarifications** @@ -59,36 +64,36 @@ Variables: - Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741)) -### Application Service API +## Application Service API **Spec Clarifications** - Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744)) -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions **Spec Clarifications** - For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling **Spec Clarifications** diff --git a/content/changelog/v1.11.md b/content/changelog/v1.11.md new file mode 100644 index 00000000..cb20f57b --- /dev/null +++ b/content/changelog/v1.11.md @@ -0,0 +1,175 @@ +--- +title: v1.11 Changelog +linkTitle: v1.11 +type: docs +outputs: + - html + - checklist +date: 2024-06-20T10:20:43-06:00 +--- + + + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
Release dateJune 20, 2024
Checklistchecklist.md
+ + + +## 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)) diff --git a/content/changelog/v1.2.md b/content/changelog/v1.2.md index 22deb1ac..5f06e8a7 100644 --- a/content/changelog/v1.2.md +++ b/content/changelog/v1.2.md @@ -1,4 +1,10 @@ --- +title: v1.2 Changelog +linkTitle: v1.2 +type: docs +outputs: + - html + - checklist date: 2022-02-02T00:00:00+0000 --- -## v1.2 - +
Git commithttps://github.com/matrix-org/matrix-doc/tree/v1.2
Release dateFebruary 02, 2022
Checklistchecklist.md
-### Client-Server API +## Client-Server API Breaking Changes @@ -65,7 +70,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Server-Server API +## Server-Server API New Endpoints @@ -88,7 +93,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Application Service API +## Application Service API Spec Clarifications @@ -99,7 +104,7 @@ Variables: - Correct the documentation for the response value for `GET /_matrix/app/v1/thirdparty/protocol/{protocol}`. ([#3675](https://github.com/matrix-org/matrix-doc/issues/3675)) -### Identity Service API +## Identity Service API Backwards Compatible Changes @@ -114,7 +119,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Push Gateway API +## Push Gateway API Spec Clarifications @@ -123,7 +128,7 @@ Variables: - Fix the rendering of the responses for various API endpoints. ([#3674](https://github.com/matrix-org/matrix-doc/issues/3674)) -### Room Versions +## Room Versions Backwards Compatible Changes @@ -144,7 +149,7 @@ Variables: - Fix auth rules to allow membership of `knock` -> `leave` in v7, v8, and v9. ([#3694](https://github.com/matrix-org/matrix-doc/issues/3694)) -### Appendices +## Appendices Backwards Compatible Changes diff --git a/content/changelog/v1.3.md b/content/changelog/v1.3.md index bc05b1cc..46e7f0d4 100644 --- a/content/changelog/v1.3.md +++ b/content/changelog/v1.3.md @@ -1,4 +1,10 @@ --- +title: v1.3 Changelog +linkTitle: v1.3 +type: docs +outputs: + - html + - checklist date: 2022-06-15T00:00:00+0100 --- -## v1.3 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.3
Release dateJune 15, 2022
Checklistchecklist.md
-### Client-Server API +## Client-Server API Deprecations @@ -55,7 +60,7 @@ Variables: - Fix membership state transitions to denote that `invite->knock` and `external->leave` are valid transitions. ([#3730](https://github.com/matrix-org/matrix-spec-proposals/issues/3730)) -### Server-Server API +## Server-Server API Backwards Compatible Changes @@ -79,7 +84,7 @@ Variables: - Clarify that the `content` for `X-Matrix` signature validation is the parsed JSON body. ([#3727](https://github.com/matrix-org/matrix-spec-proposals/issues/3727)) -### Application Service API +## Application Service API Backwards Compatible Changes @@ -88,19 +93,19 @@ Variables: - Add timestamp massaging as per [MSC3316](https://github.com/matrix-org/matrix-spec-proposals/pull/3316). ([#1094](https://github.com/matrix-org/matrix-spec/issues/1094)) -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Backwards Compatible Changes @@ -124,7 +129,7 @@ No significant changes. - For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737)) -### Appendices +## Appendices No significant changes. diff --git a/content/changelog/v1.4.md b/content/changelog/v1.4.md index 7d22c00e..6515e570 100644 --- a/content/changelog/v1.4.md +++ b/content/changelog/v1.4.md @@ -1,4 +1,10 @@ --- +title: v1.4 Changelog +linkTitle: v1.4 +type: docs +outputs: + - html + - checklist date: 2022-09-29T00:00:00+0100 --- -## v1.4 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.4
Release dateSeptember 29, 2022
Checklistchecklist.md
-### Client-Server API +## Client-Server API Removed Endpoints @@ -58,7 +63,7 @@ Variables: - Clarify enum values by separating possible values with commas. ([#1240](https://github.com/matrix-org/matrix-spec/issues/1240)) -### Server-Server API +## Server-Server API Backwards Compatible Changes @@ -75,7 +80,7 @@ Variables: - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185)) -### Application Service API +## Application Service API Breaking Changes @@ -90,7 +95,7 @@ Variables: - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -100,7 +105,7 @@ Variables: - Update "API Standards" section to clarify how JSON is used. ([#1185](https://github.com/matrix-org/matrix-spec/issues/1185)) -### Push Gateway API +## Push Gateway API Spec Clarifications @@ -109,7 +114,7 @@ Variables: - Add HTML anchors for object definitions in the formatted specification. ([#1174](https://github.com/matrix-org/matrix-spec/issues/1174)) -### Room Versions +## Room Versions Spec Clarifications @@ -120,13 +125,13 @@ Variables: - For room versions 7 through 10: Clarify that `invite->knock` is actually a legal transition. ([#1175](https://github.com/matrix-org/matrix-spec/issues/1175)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Backwards Compatible Changes diff --git a/content/changelog/v1.5.md b/content/changelog/v1.5.md index 258aabfa..cc099ebe 100644 --- a/content/changelog/v1.5.md +++ b/content/changelog/v1.5.md @@ -1,4 +1,10 @@ --- +title: v1.5 Changelog +linkTitle: v1.5 +type: docs +outputs: + - html + - checklist date: 2022-11-17T08:22:11-07:00 --- -## v1.5 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.5
Release dateNovember 17, 2022
Checklistchecklist.md
-### Client-Server API +## Client-Server API Backwards Compatible Changes @@ -45,7 +50,7 @@ Variables: - Add example read receipt to `GET /_matrix/client/v3/sync` response example. ([#1341](https://github.com/matrix-org/matrix-spec/issues/1341)) -### Server-Server API +## Server-Server API Spec Clarifications @@ -54,7 +59,7 @@ Variables: - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Application Service API +## Application Service API Spec Clarifications @@ -63,7 +68,7 @@ Variables: - Clarify that application services can only register an interest in local users, as per [MSC3905](https://github.com/matrix-org/matrix-spec-proposals/issues/3905). ([#1305](https://github.com/matrix-org/matrix-spec/issues/1305)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -72,13 +77,13 @@ Variables: - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Spec Clarifications @@ -89,13 +94,13 @@ No significant changes. - Fix a number of broken links in the specification. ([#1330](https://github.com/matrix-org/matrix-spec/issues/1330)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Backwards Compatible Changes diff --git a/content/changelog/v1.6.md b/content/changelog/v1.6.md index 07574ff3..d0e14a0a 100644 --- a/content/changelog/v1.6.md +++ b/content/changelog/v1.6.md @@ -1,4 +1,10 @@ --- +title: v1.6 Changelog +linkTitle: v1.6 +type: docs +outputs: + - html + - checklist date: 2023-02-14T08:25:40-07:00 --- -## v1.6 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.6
Release dateFebruary 14, 2023
Checklistchecklist.md
-### Client-Server API +## Client-Server API Backwards Compatible Changes @@ -45,7 +50,7 @@ Variables: - Improve distinction between tags and their attributes in the rich text section. Contributed by Nico. ([#1433](https://github.com/matrix-org/matrix-spec/issues/1433)) -### Server-Server API +## Server-Server API Breaking Changes @@ -73,7 +78,7 @@ Variables: - Fix `edu_type` in EDU examples. ([#1383](https://github.com/matrix-org/matrix-spec/issues/1383)) -### Application Service API +## Application Service API Backwards Compatible Changes @@ -82,7 +87,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Identity Service API +## Identity Service API Backwards Compatible Changes @@ -91,7 +96,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Push Gateway API +## Push Gateway API Backwards Compatible Changes @@ -100,7 +105,7 @@ Variables: - Add information on standard error responses for unknown endpoints/methods, as per [MSC3743](https://github.com/matrix-org/matrix-spec-proposals/pull/3743). ([#1347](https://github.com/matrix-org/matrix-spec/issues/1347)) -### Room Versions +## Room Versions Backwards Compatible Changes @@ -116,13 +121,13 @@ Variables: - Fix various typos throughout the specification. ([#1423](https://github.com/matrix-org/matrix-spec/issues/1423)) -### Appendices +## Appendices No significant changes. -### Internal Changes/Tooling +## Internal Changes/Tooling Spec Clarifications diff --git a/content/changelog/v1.7.md b/content/changelog/v1.7.md index 61ade090..8cbe1985 100644 --- a/content/changelog/v1.7.md +++ b/content/changelog/v1.7.md @@ -1,4 +1,10 @@ --- +title: v1.7 Changelog +linkTitle: v1.7 +type: docs +outputs: + - html + - checklist date: 2023-05-25T09:47:21-06:00 --- -## v1.7 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.7
Release dateMay 25, 2023
Checklistchecklist.md
-### Client-Server API +## Client-Server API New Endpoints @@ -63,7 +68,7 @@ Variables: - Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535)) -### Server-Server API +## Server-Server API Spec Clarifications @@ -75,7 +80,7 @@ Variables: - Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536)) -### Application Service API +## Application Service API New Endpoints @@ -97,7 +102,7 @@ Variables: - Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447)) -### Identity Service API +## Identity Service API Spec Clarifications @@ -106,13 +111,13 @@ Variables: - Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions Spec Clarifications @@ -121,7 +126,7 @@ No significant changes. - Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) -### Appendices +## Appendices Spec Clarifications @@ -132,7 +137,7 @@ No significant changes. - Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) -### Internal Changes/Tooling +## Internal Changes/Tooling Spec Clarifications diff --git a/content/changelog/v1.8.md b/content/changelog/v1.8.md index 0d25f6a2..2ff0e7a4 100644 --- a/content/changelog/v1.8.md +++ b/content/changelog/v1.8.md @@ -1,4 +1,10 @@ --- +title: v1.8 Changelog +linkTitle: v1.8 +type: docs +outputs: + - html + - checklist date: 2023-08-23T09:23:53-06:00 --- -## v1.8 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.8
Release dateAugust 23, 2023
Checklistchecklist.md
-### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -36,7 +41,7 @@ Variables: - Fix various typos throughout the specification. ([#1597](https://github.com/matrix-org/matrix-spec/issues/1597)) -### Server-Server API +## Server-Server API **Deprecations** @@ -58,26 +63,26 @@ Variables: - Switch to ordered list for server name resolution steps. ([#1623](https://github.com/matrix-org/matrix-spec/issues/1623)) -### Application Service API +## Application Service API **Spec Clarifications** - Fix type of custom `fields` in thirdparty lookup queries. ([#1584](https://github.com/matrix-org/matrix-spec/issues/1584)) -### Identity Service API +## Identity Service API **Spec Clarifications** - Make sure examples types match schema in definitions. ([#1563](https://github.com/matrix-org/matrix-spec/issues/1563)) -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions **Backwards Compatible Changes** @@ -88,7 +93,7 @@ No significant changes. - Update the redaction rules in room version 11, as per [MSC2176](https://github.com/matrix-org/matrix-spec-proposals/pull/2176) and [MSC3821](https://github.com/matrix-org/matrix-spec-proposals/pull/3821). ([#1604](https://github.com/matrix-org/matrix-spec/issues/1604)) -### Appendices +## Appendices **Backwards Compatible Changes** @@ -99,7 +104,7 @@ No significant changes. - Clarify spec re canonical JSON to handle negative-zero; also, give an example of negative-zero and a large power of ten. ([#1573](https://github.com/matrix-org/matrix-spec/issues/1573)) -### Internal Changes/Tooling +## Internal Changes/Tooling **Backwards Compatible Changes** diff --git a/content/changelog/v1.9.md b/content/changelog/v1.9.md index 46a79f37..6679dd98 100644 --- a/content/changelog/v1.9.md +++ b/content/changelog/v1.9.md @@ -1,4 +1,10 @@ --- +title: v1.9 Changelog +linkTitle: v1.9 +type: docs +outputs: + - html + - checklist date: 2023-11-29T10:04:26-07:00 --- -## v1.9 - +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.9
Release dateNovember 29, 2023
Checklistchecklist.md
-### Client-Server API +## Client-Server API **Backwards Compatible Changes** @@ -38,7 +43,7 @@ Variables: - Clarify that thread roots are not considered within the thread. ([#1677](https://github.com/matrix-org/matrix-spec/issues/1677)) -### Server-Server API +## Server-Server API **Spec Clarifications** @@ -47,27 +52,27 @@ Variables: - Clarify that federation requests for non-local users are invalid. ([#1672](https://github.com/matrix-org/matrix-spec/issues/1672)) -### Application Service API +## Application Service API No significant changes. -### Identity Service API +## Identity Service API No significant changes. -### Push Gateway API +## Push Gateway API No significant changes. -### Room Versions +## Room Versions No significant changes. -### Appendices +## Appendices **Spec Clarifications** @@ -75,7 +80,7 @@ No significant changes. - Fix various typos throughout the specification. ([#1652](https://github.com/matrix-org/matrix-spec/issues/1652)) -### Internal Changes/Tooling +## Internal Changes/Tooling **Backwards Compatible Changes** diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 71f92bec..e9efe8ec 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -22,17 +22,23 @@ 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) -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. @@ -94,6 +100,9 @@ section](#soft-logout) for more information. `M_MISSING_TOKEN` No access token was specified for the request. +`M_USER_LOCKED` +The account has been [locked](#account-locking) and cannot be used at this time. + `M_BAD_JSON` Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys. @@ -227,7 +236,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 @@ -245,9 +254,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 @@ -349,9 +359,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 @@ -509,6 +519,10 @@ token available. If it does not have a refresh token available, or refreshing fails with `soft_logout: true`, the client can acquire a new access token by specifying the device ID it is already using to the login API. +{{% changed-in v="1.12" %}} A client that receives such a response together +with an `M_USER_LOCKED` error code, cannot obtain a new access token until +the account has been [unlocked](#account-locking). + ### User-Interactive Authentication API #### Overview @@ -1394,7 +1408,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.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 @@ -1415,6 +1432,55 @@ number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% /boxes/warning %}} +#### Account locking + +{{% added-in v="1.12" %}} + +Server administrators may apply locks to prevent users from usefully +using their accounts, for instance, due to safety or security concerns. +In contrast to account deactivation, locking is a non-destructive action +that can be reversed. This specification describes the behaviour of clients +and servers when an account is locked. It deliberately leaves the methods +for locking and unlocking accounts as a server implementation detail. + +When an account is locked, servers MUST return a `401 Unauthorized` error +response with an `M_USER_LOCKED` error code and [`soft_logout`](#soft-logout) +set to `true` on all but the following Client-Server APIs: + +- [`POST /logout`](#post_matrixclientv3logout) +- [`POST /logout/all`](#post_matrixclientv3logoutall) + +Servers MAY additionally include details of why the lock was applied in +the `error` field. + +``` +HTTP/1.1 401 Unauthorized +Content-Type: application/json +``` + +```json +{ + "errcode": "M_USER_LOCKED", + "error": "This account has been locked", + "soft_logout": true +} +``` + +Servers SHOULD NOT invalidate access tokens on locked accounts unless the +client requests a logout (using the above endpoints). This ensures that +users can retain their sessions without having to log back in if the account +becomes unlocked. + +Upon receiving an `M_USER_LOCKED` error, clients SHOULD retain session +information including encryption state and inform the user that their account +has been locked. While the lock is applied, clients SHOULD hide the normal UI +from the user, preventing general use of their account. Clients SHOULD, however, +continue to make rate-limited requests to [`/sync`](#get_matrixclientv3sync) +and other APIs to detect when the lock has been lifted. + +To enable users to appeal to a lock clients MAY use +[server contact discovery](#getwell-knownmatrixsupport). + ### Adding Account Administrative Contact Information A homeserver may keep some contact information for administrative use. @@ -1644,6 +1710,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 @@ -1842,16 +1929,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 @@ -2565,9 +2651,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. @@ -2721,42 +2804,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 | +| [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 | | [Reference Relations](#reference-relations) | Optional | Optional | 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.* @@ -2805,42 +2891,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/content/client-server-api/modules/content_repo.md b/content/client-server-api/modules/content_repo.md index cef70b3d..17715504 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -23,19 +23,68 @@ 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" >}} A number of endpoints under the /_matrix/media hierarchy +have been deprecated and replaced with new endpoints which require authentication. +The deprecated endpoints are marked in the section below. +{{% /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" %}} @@ -119,3 +168,50 @@ Homeservers have additional content-specific concerns: - Clients or remote homeservers may try to upload malicious files targeting vulnerabilities in either the homeserver thumbnailing or the client decoders. + +##### Serving inline content + +Clients with insecure configurations may be vulnerable to Cross-Site Scripting +attacks when served media with a `Content-Disposition` of `inline`. Clients +SHOULD NOT be hosted on the same domain as the media endpoints for the homeserver +to mitigate most of this risk. Servers SHOULD restrict `Content-Type` headers to +one of the following values when serving content with `Content-Disposition: inline`: + +* `text/css` +* `text/plain` +* `text/csv` +* `application/json` +* `application/ld+json` +* `image/jpeg` +* `image/gif` +* `image/png` +* `image/apng` +* `image/webp` +* `image/avif` +* `video/mp4` +* `video/webm` +* `video/ogg` +* `video/quicktime` +* `audio/mp4` +* `audio/webm` +* `audio/aac` +* `audio/mpeg` +* `audio/ogg` +* `audio/wave` +* `audio/wav` +* `audio/x-wav` +* `audio/x-pn-wav` +* `audio/flac` +* `audio/x-flac` + +These types are unlikely to cause Cross-Site Scripting issues when a `Content-Type` +header is provided, as clients will only try to render the data using that content +type. For example, if a HTML file is uploaded with a `Content-Type` of `image/png`, +clients will just assume that the image is corrupted, and won't render it as a +HTML page. Therefore, there is no risk in trusting the user-defined content type, +as long as the `Content-Disposition` is calculated based on that type. + +Clients SHOULD NOT rely on servers returning `inline` rather than `attachment` +on `/download`. Server implementations might decide out of an abundance of +caution that all downloads are responded to with `attachment`, regardless of +content type - clients should not be surprised by this behaviour. 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..49b053f6 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 @@ -1343,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 @@ -1421,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" %}} @@ -1530,9 +1536,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 diff --git a/content/client-server-api/modules/guest_access.md b/content/client-server-api/modules/guest_access.md index 873908bb..86ac031a 100644 --- a/content/client-server-api/modules/guest_access.md +++ b/content/client-server-api/modules/guest_access.md @@ -33,7 +33,7 @@ rather than allowing all homeservers to enforce the rules on each other. #### Client behaviour The following API endpoints are allowed to be accessed by guest accounts -for retrieving events: +for retrieving events and associated media: * [GET /rooms/{roomId}/state](#get_matrixclientv3roomsroomidstate) * [GET /rooms/{roomId}/context/{eventId}](#get_matrixclientv3roomsroomidcontexteventid) @@ -44,6 +44,9 @@ for retrieving events: * [GET /rooms/{roomId}/initialSync](#get_matrixclientv3roomsroomidinitialsync) * [GET /sync](#get_matrixclientv3sync) * [GET /events](#get_matrixclientv3events) as used for room previews. +* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}](#get_matrixclientv1mediadownloadservernamemediaid) +* {{< added-in v="1.12" >}} [GET /media/download/{serverName}/{mediaId}/{fileName}](#get_matrixclientv1mediadownloadservernamemediaidfilename) +* {{< added-in v="1.12" >}} [GET /media/thumbnail/{serverName}/{mediaId}](#get_matrixclientv1mediathumbnailservernamemediaid) The following API endpoints are allowed to be accessed by guest accounts for sending events: 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) | diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index c674bac9..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 @@ -521,7 +523,7 @@ Definition: } ``` - **`.m.rule.is_user_mention`** + **`.m.rule.is_user_mention`** {{< added-in v="1.7" >}} @@ -555,7 +557,7 @@ Definition: } ``` - **`.m.rule.contains_display_name`** + **`.m.rule.contains_display_name`** {{% changed-in v="1.7" %}} @@ -590,7 +592,7 @@ Definition: } ``` - **`.m.rule.is_room_mention`** + **`.m.rule.is_room_mention`** {{< added-in v="1.7" >}} @@ -624,7 +626,7 @@ Definition: } ``` - **`.m.rule.roomnotif`** + **`.m.rule.roomnotif`** {{% changed-in v="1.7" %}} @@ -662,7 +664,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 +698,7 @@ Definition: } ``` -**`.m.rule.reaction`** +**`.m.rule.reaction`** {{% added-in v="1.7" %}} @@ -776,7 +778,7 @@ Definition: ##### Default Content Rules - **`.m.rule.contains_user_name`** + **`.m.rule.contains_user_name`** {{% changed-in v="1.7" %}} diff --git a/content/client-server-api/modules/read_markers.md b/content/client-server-api/modules/read_markers.md index aa0baf47..830a441f 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,46 @@ 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 + +{{% added-in v="1.12" %}} + +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/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/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 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`. 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/content/rooms/fragments/v2-state-res.md b/content/rooms/fragments/v2-state-res.md index 731070a7..725cd08f 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -50,7 +50,7 @@ chain for each state *S**i*, that is the union of the auth chains for each event in *S**i*, and then taking every event that doesn't appear in every auth chain. If *C**i* is the full auth chain of *S**i*, then the auth difference is - ∪ *C**i* −  ∩ *C**i*. +∪ *C**i* − ∩ *C**i*. **Full conflicted set.** The *full conflicted set* is the union of the conflicted state set and @@ -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 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/content/server-server-api.md b/content/server-server-api.md index e92d871c..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 ``. @@ -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 @@ -1189,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/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/authed-content-repo.yaml b/data/api/client-server/authed-content-repo.yaml new file mode 100644 index 00000000..53416cf3 --- /dev/null +++ b/data/api/client-server/authed-content-repo.yaml @@ -0,0 +1,586 @@ +# 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: + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true + schema: + type: string + example: "inline; filename=\"filename.jpg\"" + 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: + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true + schema: + type: string + example: "inline; filename=\"filename.jpg\"" + 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-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" + Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. + description: The content type of the thumbnail. + required: true + 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 SHOULD impose a maximum value for this parameter. The + content repository MAY 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. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true + schema: + type: string + diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 99f07962..523c6091 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -43,19 +43,13 @@ paths: The custom capabilities the server supports, using the Java package naming convention. additionalProperties: - type: object + description: |- + Application-dependent keys using the + [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar). 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 +72,20 @@ 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. + 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: { @@ -125,3 +133,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 diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index e6d55b51..f50850bd 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: | @@ -217,7 +220,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' @@ -232,9 +248,29 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: The name of the file that was previously uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and SHOULD contain a file name. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + + If the upload was made with a `filename`, this header MUST + contain the same `filename`. Otherwise, `filename` is excluded + from the header. If the media being downloaded is remote, the + remote server's `filename` in the `Content-Disposition` header + is used as the `filename` instead. When the header is not + supplied, or does not supply a `filename`, the local download + response does not include a `filename`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -254,11 +290,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' @@ -280,11 +329,21 @@ paths: Content-Type: $ref: '#/components/headers/downloadContentType' Content-Disposition: - description: |- - The `fileName` requested or the name of the file that was previously - uploaded, if set. + x-changedInMatrixVersion: + "1.12": This header became required. + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be one of `inline` or `attachment`, + and MUST contain the file name requested in the path. + + If the `Content-Type` is allowed in the [restrictions for serving + inline content](/client-server-api/#serving-inline-content), + servers SHOULD use `inline`, otherwise they SHOULD use + `attachment`. + required: true schema: type: string + example: "inline; filename=\"filename.jpg\"" content: application/octet-stream: schema: @@ -304,10 +363,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' @@ -362,7 +434,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 @@ -370,8 +442,24 @@ paths: "200": description: A thumbnail of the requested content. headers: + Content-Disposition: + x-addedInMatrixVersion: "1.12" + description: | + The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) + of the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`). + + Servers should note the [Content-Type restrictions for serving inline content](/client-server-api/#serving-inline-content), + as these limitations imply which formats should be used for thumbnail generation. + required: true + schema: + type: string + example: "inline; filename=\"thumbnail.png\"" Content-Type: + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`. description: The content type of the thumbnail. + required: true schema: type: string enum: @@ -455,8 +543,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 +618,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. @@ -587,7 +685,15 @@ components: contentType: in: header name: Content-Type - description: The content type of the file being uploaded + description: | + **Optional.** The content type of the file being uploaded. + + Clients SHOULD always supply this header. + + Defaults to `application/octet-stream` if it is not set. + x-changedInMatrixVersion: + "1.12": | + This header became explicitly optional with a default value. example: application/pdf schema: type: string @@ -625,7 +731,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: @@ -639,8 +745,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 @@ -663,8 +769,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: @@ -729,7 +836,29 @@ components: format: uri headers: downloadContentType: - description: The content type of the file that was previously uploaded. + description: | + The content type of the file that was previously uploaded. + + The server MUST return a `Content-Type` which is either exactly the same + as the original upload, or reasonably close. The bounds of "reasonable" + are: + + * Adding a charset to `text/*` content types. + * Detecting HTML and using `text/html` instead of `text/plain`. + * Using `application/octet-stream` when the server determines the + content type is obviously wrong. For example, an encrypted file being + claimed as `image/png`. + * Returning `application/octet-stream` when the media has an + unknown/unprovided `Content-Type`. For example, being uploaded before + the server tracked content types or when the remote server is + non-compliantly omitting the header entirely. + + Actions not in the spirit of the above are not considered "reasonable". + x-changedInMatrixVersion: + "1.12": | + This header became required in order to support `Content-Disposition`, + and the behaviour to compute its value was clarified. + required: true schema: type: string 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/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 diff --git a/data/api/client-server/definitions/push_ruleset.yaml b/data/api/client-server/definitions/push_ruleset.yaml index bbd07f7c..0a2148e0 100644 --- a/data/api/client-server/definitions/push_ruleset.yaml +++ b/data/api/client-server/definitions/push_ruleset.yaml @@ -33,3 +33,190 @@ properties: $ref: push_rule.yaml type: array type: object +example: { + "content": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "default": true, + "enabled": true, + "pattern": "alice", + "rule_id": ".m.rule.contains_user_name" + } + ], + "override": [ + { + "actions": [], + "conditions": [], + "default": true, + "enabled": false, + "rule_id": ".m.rule.master" + }, + { + "actions": [], + "conditions": [ + { + "key": "content.msgtype", + "kind": "event_match", + "pattern": "m.notice" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.suppress_notices" + } + ], + "room": [], + "sender": [], + "underride": [ + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.call" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ], + "conditions": [ + { + "kind": "contains_display_name" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.contains_display_name" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "kind": "room_member_count", + "is": "2" + }, + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.room_one_to_one" + }, + { + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.invite_for_me" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.member_event" + }, + { + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ], + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.message" + } + ], + "default": true, + "enabled": true, + "rule_id": ".m.rule.message" + } + ] +} 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/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. diff --git a/data/api/client-server/definitions/wellknown/full.yaml b/data/api/client-server/definitions/wellknown/full.yaml index 8d8f4038..eaa9294a 100644 --- a/data/api/client-server/definitions/wellknown/full.yaml +++ b/data/api/client-server/definitions/wellknown/full.yaml @@ -22,7 +22,6 @@ properties: "m.identity_server": $ref: "identity_server.yaml" additionalProperties: - type: object description: Application-dependent keys using Java package naming convention. required: - m.homeserver diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index afd19fa8..dda0d867 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -139,6 +139,32 @@ paths: type: string - in: query name: server_name + deprecated: true + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to join the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to join the room through. One of the servers must be participating in the room. diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index 1eb6cde7..085aa74f 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -50,6 +50,32 @@ paths: type: string - in: query name: server_name + deprecated: true + x-changedInMatrixVersion: + "1.12": |- + This parameter has been deprecated in favour of `via` and will be removed in + a future version of the spec. + + Clients SHOULD use `via` when the homeserver they're talking to supports it. + To do this, they MAY either detect server support through the supported spec + versions in [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) + or always include both parameters with identical values. + + Homeservers MUST ignore all `server_name` parameters if any `via` parameters + are supplied. + description: |- + The servers to attempt to knock on the room through. One of the servers + must be participating in the room. + example: + - matrix.org + - elsewhere.ca + schema: + type: array + items: + type: string + - in: query + name: via + x-addedInMatrixVersion: "1.12" description: |- The servers to attempt to knock on the room through. One of the servers must be participating in the room. diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index b37d1742..385eb33b 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -119,15 +119,18 @@ paths: $ref: definitions/user_identifier.yaml user: type: string + deprecated: true description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. medium: type: string + deprecated: true description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. address: type: string + deprecated: true description: Third-party identifier for the user. Deprecated in favour of `identifier`. password: @@ -194,6 +197,7 @@ paths: x-addedInMatrixVersion: "1.3" home_server: type: string + deprecated: true description: |- The server_name of the homeserver on which the account has been registered. 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: diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 751548ba..1f74c972 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -223,8 +223,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 diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index d85e3d85..fd56f46e 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -20,10 +20,8 @@ paths: get: summary: Retrieve all push rulesets. description: |- - Retrieve all push rulesets for this user. Clients can "drill-down" on - the rulesets by suffixing a `scope` to this path e.g. - `/pushrules/global/`. This will return a subset of this data under the - specified key e.g. the `global` key. + Retrieve all push rulesets for this user. Currently the only push ruleset + defined is `global`. operationId: getPushRules security: - accessTokenQuery: [] @@ -44,200 +42,27 @@ paths: title: Ruleset allOf: - $ref: definitions/push_ruleset.yaml - examples: - response: - value: { - "global": { - "content": [ - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "default": true, - "enabled": true, - "pattern": "alice", - "rule_id": ".m.rule.contains_user_name" - } - ], - "override": [ - { - "actions": [], - "conditions": [], - "default": true, - "enabled": false, - "rule_id": ".m.rule.master" - }, - { - "actions": [], - "conditions": [ - { - "key": "content.msgtype", - "kind": "event_match", - "pattern": "m.notice" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.suppress_notices" - } - ], - "room": [], - "sender": [], - "underride": [ - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "ring" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.call.invite" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.call" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight" - } - ], - "conditions": [ - { - "kind": "contains_display_name" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.contains_display_name" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "kind": "room_member_count", - "is": "2" - }, - { - "kind": "event_match", - "key": "type", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.room_one_to_one" - }, - { - "actions": [ - "notify", - { - "set_tweak": "sound", - "value": "default" - }, - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - }, - { - "key": "content.membership", - "kind": "event_match", - "pattern": "invite" - }, - { - "key": "state_key", - "kind": "event_match", - "pattern": "@alice:example.com" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.invite_for_me" - }, - { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.member" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.member_event" - }, - { - "actions": [ - "notify", - { - "set_tweak": "highlight", - "value": false - } - ], - "conditions": [ - { - "key": "type", - "kind": "event_match", - "pattern": "m.room.message" - } - ], - "default": true, - "enabled": true, - "rule_id": ".m.rule.message" - } - ] - } - } tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}": + /pushrules/global/: + get: + summary: Retrieve all push rules. + description: |- + Retrieve all push rules for this user. + operationId: getPushRulesGlobal + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: All the push rules for this user. + content: + application/json: + schema: + $ref: definitions/push_ruleset.yaml + tags: + - Push notifications + "/pushrules/global/{kind}/{ruleId}": get: summary: Retrieve a push rule. description: Retrieve a single specified push rule. @@ -246,13 +71,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -318,13 +136,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -395,13 +206,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -523,7 +327,7 @@ paths: $ref: definitions/errors/rate_limited.yaml tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}/enabled": + "/pushrules/global/{kind}/{ruleId}/enabled": get: summary: Get whether a push rule is enabled description: This endpoint gets whether the specified push rule is enabled. @@ -532,15 +336,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: |- - Either `global` or `device/` to specify global - rules or device rules for the given `profile_tag`. - example: global - schema: - type: string - in: path name: kind required: true @@ -604,13 +399,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true @@ -674,7 +462,7 @@ paths: } tags: - Push notifications - "/pushrules/{scope}/{kind}/{ruleId}/actions": + "/pushrules/global/{kind}/{ruleId}/actions": get: summary: The actions for a push rule description: This endpoint get the actions for the specified push rule. @@ -683,15 +471,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: |- - Either `global` or `device/` to specify global - rules or device rules for the given `profile_tag`. - example: global - schema: - type: string - in: path name: kind required: true @@ -764,13 +543,6 @@ paths: - accessTokenQuery: [] - accessTokenBearer: [] parameters: - - in: path - name: scope - required: true - description: "`global` to specify global rules." - example: global - schema: - type: string - in: path name: kind required: true diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index afd30459..1dd314b8 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -169,6 +169,7 @@ paths: x-addedInMatrixVersion: "1.3" home_server: type: string + deprecated: true description: |- The server_name of the homeserver on which the account has been registered. @@ -387,6 +388,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 +594,7 @@ paths: parameter because the homeserver is expected to sign the request to the identity server instead. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: deactivateAccount 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: 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: diff --git a/data/api/server-server/content_repository.yaml b/data/api/server-server/content_repository.yaml new file mode 100644 index 00000000..66439b79 --- /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 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` + 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 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` + 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 SHOULD impose a maximum value for this parameter. The + content repository MAY 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 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/keys.yaml b/data/api/server-server/definitions/keys.yaml index efb76f26..c3f71083 100644 --- a/data/api/server-server/definitions/keys.yaml +++ b/data/api/server-server/definitions/keys.yaml @@ -19,7 +19,7 @@ example: properties: server_name: type: string - description: DNS name of the homeserver. + description: The homeserver's [server name](/appendices/#server-name). example: "example.org" verify_keys: type: object @@ -98,4 +98,4 @@ properties: publishes a key which is valid for a significant amount of time without a way for the homeserver owner to revoke it. example: 1052262000000 -required: ["server_name", "verify_keys"] +required: ["server_name", "verify_keys", "signatures", "valid_until_ts"] 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/data/api/server-server/examples/unsigned_pdu_base.json b/data/api/server-server/examples/unsigned_pdu_base.json index 4826ccef..079ee1ea 100644 --- a/data/api/server-server/examples/unsigned_pdu_base.json +++ b/data/api/server-server/examples/unsigned_pdu_base.json @@ -1,7 +1,6 @@ { "room_id": "!UcYsUzyxTGDxLBEvLy:example.org", "sender": "@alice:example.com", - "origin": "example.com", "origin_server_ts": 1404838188000, "depth": 12, "auth_events": [ diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index a56315d1..a361836c 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -341,7 +341,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). auth_chain: type: array description: |- diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 7804a6f6..31f8098c 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -162,7 +162,7 @@ paths: properties: origin: type: string - description: The resident server's DNS name. + description: The resident server's [server name](/appendices/#server-name). members_omitted: type: boolean description: "`true` if `m.room.member` events have been omitted from `state`." @@ -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" diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index ed9e6302..791deb0a 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -26,7 +26,7 @@ paths: parameters: - in: path name: serverName - description: The server's DNS name to query + description: The [server name](/appendices/#server-name) to query required: true example: matrix.org schema: diff --git a/data/api/server-server/query.yaml b/data/api/server-server/query.yaml index a50a3c52..0e80df60 100644 --- a/data/api/server-server/query.yaml +++ b/data/api/server-server/query.yaml @@ -45,7 +45,8 @@ paths: description: |- Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias. Homeservers should only query room aliases - that belong to the target server (identified by the DNS Name in the alias). + that belong to the target server (identified by the [server name](/appendices/#server-name) + in the alias). Servers may wish to cache the response to this query to avoid requesting the information too often. @@ -111,7 +112,8 @@ paths: description: |- Performs a query to get profile information, such as a display name or avatar, for a given user. Homeservers should only query profiles for users that belong - to the target server (identified by the DNS Name in the user ID). + to the target server (identified by the [server name](/appendices/#server-name) + in the user ID). Servers may wish to cache the response to this query to avoid requesting the information too often. 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/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.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"] +} 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: |- diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml index 95e05ff7..f608a6e2 100644 --- a/data/event-schemas/schema/m.room.encrypted.yaml +++ b/data/event-schemas/schema/m.room.encrypted.yaml @@ -41,6 +41,7 @@ properties: Olm event. For more details, see [Messaging Algorithms](/client-server-api/#messaging-algorithms). sender_key: type: string + deprecated: true x-changedInMatrixVersion: "1.3": |- Previously this field was required, however given it offers no additional @@ -56,6 +57,7 @@ properties: for more information. device_id: type: string + deprecated: true x-changedInMatrixVersion: "1.3": |- Previously this field was required for Megolm messages, however given it diff --git a/layouts/_default/single.checklist.md b/layouts/_default/single.checklist.md new file mode 100644 index 00000000..f885a316 --- /dev/null +++ b/layouts/_default/single.checklist.md @@ -0,0 +1,4 @@ +{{ .RawContent + | replaceRE "\n- " "\n- [ ] " + | replaceRE "\n?" "" + | replaceRE "Checklist.*\n" "" }} 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/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/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 }} 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-content-type.html b/layouts/partials/openapi/render-content-type.html index 036522de..a7c90e1a 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,28 +1,30 @@ {{/* - 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) }} - - + + + + - {{ range $idx, $content_type := $content_types }} + {{ range $mime, $body := $content_types }} - - + + {{ end }}
Content-TypeDescription
Content-TypeDescription
{{ $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-object-table.html b/layouts/partials/openapi/render-object-table.html index d2b09acb..656f556a 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -31,9 +31,11 @@ {{ . }} {{ end }} - Name - Type - Description + + Name + Type + Description + {{ range $property_name, $property := $properties }} @@ -68,7 +70,7 @@ {{ if reflect.IsMap .additionalProperties }} - <Other properties> + <Other properties> {{ partial "partials/property-type" .additionalProperties | safeHTML }} {{ partial "partials/property-description" (dict "property" .additionalProperties) }} @@ -90,8 +92,10 @@ resolve-additional-types.) {{ . }} {{ end }} - Type - Description + + Type + Description + {{ $property := . }} @@ -113,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` @@ -154,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`. */}} @@ -170,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 .) }} diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html index 8c6fce0e..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,14 +22,19 @@ {{ $method := .method }} {{ $endpoint := .endpoint }} {{ $operation_data := .operation_data }} -{{ $anchor := anchorize $endpoint }} + +{{ $anchor := "" }} +{{ if .anchor_base }} + {{ $anchor = printf "%s_" .anchor_base }} +{{ end }} +{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
-

+

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

@@ -46,7 +53,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") }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5fa0c255..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 }} @@ -50,13 +51,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 0ffc4884..084e9481 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -20,8 +20,10 @@
- - + + + + {{ range $code, $response := $responses }} @@ -37,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 }} @@ -95,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 }} @@ -121,13 +124,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 }} 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/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/changelog/changelog-description.html b/layouts/shortcodes/changelog/changelog-description.html deleted file mode 100644 index 3c719725..00000000 --- a/layouts/shortcodes/changelog/changelog-description.html +++ /dev/null @@ -1,19 +0,0 @@ -{{/* - - This template is used to provide different content for the unstable spec - version and for a versioned release. - -*/}} - -{{ $status := .Site.Params.version.status }} - -{{ if eq $status "unstable"}} - -

    This is the unstable version of the Matrix specification.

    -

    This changelog lists changes made since the last release of the specification.

    - -{{ else }} - -

    This is version v{{ .Site.Params.version.major }}.{{ .Site.Params.version.minor }} of the Matrix specification.

    - -{{ end }} diff --git a/layouts/shortcodes/changelog/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index 78b5932f..96a82860 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -1,10 +1,8 @@ {{/* - This template is used to render all of the changelog sections under - "content/changelogs" + This template is used to redirect the changelog section under + "content/changelogs" to the latest version's changelog page. */}} -{{ with .Page.Resources.Match "*.md" }} -{{ range ((sort . "Params.date" "desc")) }} -{{ .Content }} -{{ end }} +{{ with index .Page.RegularPages.ByDate.Reverse 0 }} + {{ 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/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 }} ``` + + 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) }} 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 }}
    StatusDescription
    StatusDescription
    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. 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. diff --git a/scripts/generate-changelog.sh b/scripts/generate-changelog.sh index 45132619..9447dac5 100755 --- a/scripts/generate-changelog.sh +++ b/scripts/generate-changelog.sh @@ -16,24 +16,38 @@ rm -f rendered.md # Generate changelog towncrier --yes +if [ "$VERSION" = "vUNSTABLE" ]; then + TITLE="Changes since last release" + LINKTITLE="Unstable" + FILENAME="unstable.md" +else + TITLE="$VERSION Changelog" + LINKTITLE="$VERSION" + FILENAME="$VERSION.md" +fi + { # Prepare the header # We include the generation date in the front matter so that we can use it # to sort the changelogs at build time. cat < ../content/changelog/$VERSION.md +} > ../content/changelog/$FILENAME # Cleanup rm -v rendered.md 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") {