diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index e46834b9..bbe12160 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -1,6 +1,6 @@ --- -name: [SCT] Release checklist -about: Used by the Spec Core Team to create a new release. +name: '[SCT] Release checklist' +about: 'Used by the Spec Core Team to create a new release.' title: 'Matrix 1.X' labels: 'release-blocker' assignees: '' @@ -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..cb14a0c1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -193,7 +193,7 @@ jobs: - name: "➕ Setup Hugo" uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0 with: - hugo-version: '0.113.0' + hugo-version: '0.117.0' extended: true - name: "📥 Source checkout" uses: actions/checkout@v4 diff --git a/.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/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/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/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/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/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/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/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/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/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/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/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/config.toml b/config.toml index a4245d0b..6b669a79 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,7 @@ sidebar_menu_compact = true [module] [module.hugoVersion] extended = true - min = "0.113.0" + min = "0.117.0" [[module.imports]] path = "github.com/matrix-org/docsy" disable = false diff --git a/content/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/v1.11.md b/content/changelog/v1.11.md new file mode 100644 index 00000000..f3a60b55 --- /dev/null +++ b/content/changelog/v1.11.md @@ -0,0 +1,170 @@ +--- +date: 2024-06-20T10:20:43-06:00 +--- + + +## v1.11 + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.11
Release dateJune 20, 2024
+ + + +### Client-Server API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) +- Use of the `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/preview_url`](/client-server-api/#get_matrixclientv1mediapreview_url) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). ([#1755](https://github.com/matrix-org/matrix-spec/issues/1755)) +- Add optional `animated` query string option to `GET /thumbnail`, as per [MSC2705](https://github.com/matrix-org/matrix-spec-proposals/pull/2705). ([#1757](https://github.com/matrix-org/matrix-spec/issues/1757)) +- Specify terms of services at registration, as per [MSC1692](https://github.com/matrix-org/matrix-spec-proposals/pull/1692). ([#1812](https://github.com/matrix-org/matrix-spec/issues/1812)) +- Add support for mathematical messages, as per [MSC2191](https://github.com/matrix-org/matrix-spec-proposals/pull/2191). ([#1816](https://github.com/matrix-org/matrix-spec/issues/1816)) +- Do not require UIA when first uploading cross-signing keys, as per [MSC3967](https://github.com/matrix-org/matrix-spec-proposals/pull/3967). ([#1828](https://github.com/matrix-org/matrix-spec/issues/1828)) +- Add the new `unsigned.membership` property to events, as per [MSC4115](https://github.com/matrix-org/matrix-spec-proposals/pull/4115). ([#1847](https://github.com/matrix-org/matrix-spec/issues/1847)) +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- Some media endpoints are now consistently under `/_matrix/client/{version}/media/*` instead of `/_matrix/media/*`, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Spec Clarifications** + +- Add `/logout` and clarify the endpoints which do not take a JSON request body. ([#1644](https://github.com/matrix-org/matrix-spec/issues/1644)) +- Clarify that the `type` of the `POST /login` request must be one of the types returned by the `GET /login` response. ([#1776](https://github.com/matrix-org/matrix-spec/issues/1776)) +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Rename "recovery key" to "backup decryption key". ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Clarify that the device's Ed25519 signing key should be used in QR code verification (as opposed to the device's Curve25519 identity key). ([#1829](https://github.com/matrix-org/matrix-spec/issues/1829)) +- Fix various typos throughout the specification. ([#1832](https://github.com/matrix-org/matrix-spec/issues/1832), [#1841](https://github.com/matrix-org/matrix-spec/issues/1841), [#1852](https://github.com/matrix-org/matrix-spec/issues/1852), [#1853](https://github.com/matrix-org/matrix-spec/issues/1853)) +- Specify the encoding to be used when generating QR codes for device verification. ([#1839](https://github.com/matrix-org/matrix-spec/issues/1839)) +- Clarify that an access token is optional on the `POST /account/password` and `POST /account/deactivate` endpoints. ([#1843](https://github.com/matrix-org/matrix-spec/issues/1843)) +- Use RFC 2119 keywords more consistently. ([#1846](https://github.com/matrix-org/matrix-spec/issues/1846), [#1861](https://github.com/matrix-org/matrix-spec/issues/1861)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) +- Clarify that relations recursion should be capped at a certain depth. ([#1854](https://github.com/matrix-org/matrix-spec/issues/1854)) +- Add missing secrets, third-party invites and room tagging modules to feature profiles table. ([#1860](https://github.com/matrix-org/matrix-spec/issues/1860)) +- Clarify when server name is used and link to the definition. ([#1862](https://github.com/matrix-org/matrix-spec/issues/1862)) +- Clarify where keys reside when checking an `m.room.encrypted` event. ([#1863](https://github.com/matrix-org/matrix-spec/issues/1863)) +- Clarify that `/media/v3/upload/{serverName}/{mediaId}` requires authentication. ([#1872](https://github.com/matrix-org/matrix-spec/issues/1872)) + + +### Server-Server API + +**Deprecations** + +- Use of the Client-Server API `/_matrix/media/*` endpoints is now deprecated. New, authenticated, endpoints are available instead. ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**New Endpoints** + +- [`GET /_matrix/federation/v1/media/download/{mediaId}`](/server-server-api/#get_matrixfederationv1mediadownloadmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) +- [`GET /_matrix/federation/v1/media/thumbnail/{mediaId}`](/server-server-api/#get_matrixfederationv1mediathumbnailmediaid) ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858)) + +**Backwards Compatible Changes** + +- Media downloads and thumbnails are now authenticated, as per [MSC3916](https://github.com/matrix-org/matrix-spec-proposals/pull/3916). ([#1858](https://github.com/matrix-org/matrix-spec/issues/1858), [#1869](https://github.com/matrix-org/matrix-spec/issues/1869)) + +**Spec Clarifications** + +- Link to existing grammar where possible in types. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Clarify that whitespace around commas is allowed in the `X-Matrix` `Authorization` header value params list. ([#1818](https://github.com/matrix-org/matrix-spec/issues/1818)) +- Clarify that the `event` field of the `/v2/send_join` response is only required when the event is signed by the resident server. ([#1834](https://github.com/matrix-org/matrix-spec/issues/1834), [#1840](https://github.com/matrix-org/matrix-spec/issues/1840)) +- Replace references to RFC 7235 and RFC 7230 that are obsoleted by RFC 9110. ([#1844](https://github.com/matrix-org/matrix-spec/issues/1844)) +- Fix various typos throughout the specification. ([#1877](https://github.com/matrix-org/matrix-spec/issues/1877)) + + +### Application Service API + +**Spec Clarifications** + +- Clarify that appservices should be notified of events relating to the `sender_localpart` user. ([#1810](https://github.com/matrix-org/matrix-spec/issues/1810)) + + +### Identity Service API + +**Deprecations** + +- Authentication using a query string is now deprecated, as per [MSC4126](https://github.com/matrix-org/matrix-spec-proposals/issues/4126). The `Authorization` header should be used instead. ([#1808](https://github.com/matrix-org/matrix-spec/issues/1808)) + + +### Push Gateway API + +No significant changes. + + +### Room Versions + +**Spec Clarifications** + +- Clarify that redaction events are still subject to all applicable auth rules. ([#1824](https://github.com/matrix-org/matrix-spec/issues/1824)) +- Fix various typos throughout the specification. ([#1827](https://github.com/matrix-org/matrix-spec/issues/1827), [#1848](https://github.com/matrix-org/matrix-spec/issues/1848)) +- Fix the rendering of the event format for room versions 1 and 2. ([#1883](https://github.com/matrix-org/matrix-spec/issues/1883)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1884](https://github.com/matrix-org/matrix-spec/issues/1884)) + + +### Appendices + +**Deprecations** + +- Deprecate linking to events in rooms identified by alias, as per [MSC4132](https://github.com/matrix-org/matrix-spec-proposals/pull/4132). ([#1823](https://github.com/matrix-org/matrix-spec/issues/1823)) + +**Spec Clarifications** + +- Define 'Opaque Identifier Grammar'. ([#1791](https://github.com/matrix-org/matrix-spec/issues/1791)) +- Define common cryptographic key representation. ([#1819](https://github.com/matrix-org/matrix-spec/issues/1819)) +- Move size limits for user, room and event IDs into the appendix and clarify that the length is to be measured in bytes. ([#1850](https://github.com/matrix-org/matrix-spec/issues/1850)) + + +### Internal Changes/Tooling + +**Spec Clarifications** + +- Update the spec release process and related documentation. ([#1759](https://github.com/matrix-org/matrix-spec/issues/1759)) +- Fix npm release script for `@matrix-org/spec`. ([#1765](https://github.com/matrix-org/matrix-spec/issues/1765)) +- Formatting fixes in `CONTRIBUTING.rst`. ([#1769](https://github.com/matrix-org/matrix-spec/issues/1769)) +- Improve rendering on mobile devices. ([#1770](https://github.com/matrix-org/matrix-spec/issues/1770), [#1771](https://github.com/matrix-org/matrix-spec/issues/1771)) +- Fix the OpenAPI definition of the security schemes. ([#1772](https://github.com/matrix-org/matrix-spec/issues/1772)) +- Simplify uses of `resolve-refs` partial. ([#1773](https://github.com/matrix-org/matrix-spec/issues/1773)) +- Fix Hugo warnings. ([#1775](https://github.com/matrix-org/matrix-spec/issues/1775), [#1788](https://github.com/matrix-org/matrix-spec/issues/1788)) +- Fix `github-labels.rst`. ([#1781](https://github.com/matrix-org/matrix-spec/issues/1781)) +- Update dependencies. ([#1786](https://github.com/matrix-org/matrix-spec/issues/1786), [#1803](https://github.com/matrix-org/matrix-spec/issues/1803), [#1804](https://github.com/matrix-org/matrix-spec/issues/1804)) +- Solve `allOf` recursively in OpenAPI and JSON Schemas. ([#1787](https://github.com/matrix-org/matrix-spec/issues/1787)) +- Fix property type resolution in `render-object-table` partial. ([#1789](https://github.com/matrix-org/matrix-spec/issues/1789)) +- Factor out common definition of `Tag` type. ([#1793](https://github.com/matrix-org/matrix-spec/issues/1793)) +- Update the version of Hugo used to render the spec to v0.124.1. ([#1794](https://github.com/matrix-org/matrix-spec/issues/1794)) +- Add support for pattern formats for `patternProperties`. ([#1796](https://github.com/matrix-org/matrix-spec/issues/1796)) +- Clean up unnecessary `allOf`s in OpenAPI definitions. ([#1797](https://github.com/matrix-org/matrix-spec/issues/1797)) +- Show information about "Additional Properties" in object tables. ([#1798](https://github.com/matrix-org/matrix-spec/issues/1798)) +- Fix anchors for schemas under `oneOf`. ([#1799](https://github.com/matrix-org/matrix-spec/issues/1799)) +- Use reference to `OneTimeKeys` schema in OpenAPI definitions. ([#1800](https://github.com/matrix-org/matrix-spec/issues/1800)) +- Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. ([#1801](https://github.com/matrix-org/matrix-spec/issues/1801)) +- Add anchors in `definition` shortcode. ([#1802](https://github.com/matrix-org/matrix-spec/issues/1802)) +- Set python version for the Towncrier CI job. ([#1805](https://github.com/matrix-org/matrix-spec/issues/1805)) +- Replace `set-output` with environment files in CI. ([#1806](https://github.com/matrix-org/matrix-spec/issues/1806)) +- Render response headers. ([#1809](https://github.com/matrix-org/matrix-spec/issues/1809)) +- Use `patternProperties` in more places with supported formats. ([#1813](https://github.com/matrix-org/matrix-spec/issues/1813)) +- Add support for rendering string formats. ([#1814](https://github.com/matrix-org/matrix-spec/issues/1814)) +- Refactor the OpenAPI definitions of the content repository endpoints. ([#1822](https://github.com/matrix-org/matrix-spec/issues/1822)) +- Clean up pull request template. ([#1831](https://github.com/matrix-org/matrix-spec/issues/1831)) +- Do not add empty arrays to examples. ([#1849](https://github.com/matrix-org/matrix-spec/issues/1849)) +- Generate the Table of Contents with Hugo rather than JavaScript. ([#1851](https://github.com/matrix-org/matrix-spec/issues/1851), [#1885](https://github.com/matrix-org/matrix-spec/issues/1885)) +- Fix syntax errors in the spec release issue template. ([#1856](https://github.com/matrix-org/matrix-spec/issues/1856)) +- Use environment variables for Netlify build job. ([#1865](https://github.com/matrix-org/matrix-spec/issues/1865)) +- Render added/changed in info on request and response content types. ([#1876](https://github.com/matrix-org/matrix-spec/issues/1876)) +- Fix validation errors in generated HTML. ([#1880](https://github.com/matrix-org/matrix-spec/issues/1880)) +- Ensure most generated HTML IDs are unique. ([#1881](https://github.com/matrix-org/matrix-spec/issues/1881)) +- Allow to specify a prefix for generated HTML IDs of API endpoints. ([#1882](https://github.com/matrix-org/matrix-spec/issues/1882)) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index b0ce7289..1a6f1c6e 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. @@ -227,7 +233,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 +251,10 @@ the request idempotent. The transaction ID should **only** be used for this purpose. -From the client perspective, after the request has finished, the `{txnId}` -value should be changed by for the next request (how is not specified; a -monotonically increasing integer is recommended). +After the request has finished, clients should change the `{txnId}` value for +the next request. How this is achieved, is left as an implementation detail. +It is recommended that clients use either version 4 UUIDs or a concatenation +of the current timestamp and a monotonically increasing integer. The homeserver should identify a request as a retransmission if the transaction ID is the same as a previous request, and the path of the @@ -349,9 +356,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 @@ -1394,7 +1401,10 @@ fallback login API: This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function -`window.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 @@ -1644,6 +1654,27 @@ An example of the capability API's response for this capability is: } ``` +### `m.get_login_token` capability + +This capability has a single flag, `enabled`, to denote whether the user +is able to use [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) +to generate single-use, time-limited tokens to log unauthenticated clients +into their account. + +When not listed, clients SHOULD assume the user is unable to generate tokens. + +An example of the capability API's response for this capability is: + +```json +{ + "capabilities": { + "m.get_login_token": { + "enabled": false + } + } +} +``` + ## Filtering Filters can be created on the server and can be passed as a parameter to @@ -1842,16 +1873,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 @@ -2316,7 +2346,7 @@ following endpoint. This endpoint is particularly useful if the client has lost context on the aggregation for a parent event and needs to rebuild/verify it. -When using the `recurse` parameter, note that there no way for a client to +When using the `recurse` parameter, note that there is no way for a client to control how far the server recurses. If the client decides that the server's recursion level is insufficient, it could, for example, perform the recursion itself, or disable whatever feature requires more recursion. @@ -2565,9 +2595,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 +2748,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 +2835,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..a0138156 100644 --- a/content/client-server-api/modules/content_repo.md +++ b/content/client-server-api/modules/content_repo.md @@ -23,19 +23,67 @@ When serving content, the server SHOULD provide a interacting with the media repository. {{% /boxes/added-in-paragraph %}} +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} The unauthenticated download endpoints have been +deprecated in favour of newer, authenticated, ones. This change includes updating +the paths of all media endpoints from `/_matrix/media/*` to `/_matrix/client/{version}/media/*`, +with the exception of the `/upload` and `/create` endpoints. The upload/create +endpoints are expected to undergo a similar transition in a later version of the +specification. +{{% /boxes/added-in-paragraph %}} + #### Matrix Content (`mxc://`) URIs Content locations are represented as Matrix Content (`mxc://`) URIs. They look like: - mxc:/// +``` +mxc:/// - : The name of the homeserver where this content originated, e.g. matrix.org - : An opaque ID which identifies the content. + : The name of the homeserver where this content originated, e.g. matrix.org + : An opaque ID which identifies the content. +``` -#### Client behaviour +#### Client behaviour {id="content-repo-client-behaviour"} -Clients can upload and download content using the following HTTP APIs. +Clients can access the content repository using the following endpoints. + +{{% boxes/added-in-paragraph %}} +{{< changed-in v="1.11" >}} Clients SHOULD NOT use the deprecated media endpoints +described below. Instead, they SHOULD use the new endpoints which require authentication. +{{% /boxes/added-in-paragraph %}} + +{{% boxes/warning %}} +By Matrix 1.12, servers SHOULD "freeze" the deprecated, unauthenticated, endpoints +to prevent newly-uploaded media from being downloaded. This SHOULD mean that any +media uploaded *before* the freeze remains accessible via the deprecated endpoints, +and any media uploaded *after* (or *during*) the freeze SHOULD only be accessible +through the new, authenticated, endpoints. For remote media, "newly-uploaded" is +determined by the date the cache was populated. This may mean the media is older +than the freeze, but because the server had to re-download it, it is now considered +"new". + +Clients SHOULD update to support the authenticated endpoints before servers freeze +unauthenticated access. + +Servers SHOULD consider their local ecosystem impact before enacting a freeze. +This could mean ensuring their users' typical clients support the new endpoints +when available, or updating bridges to start using media proxies. + +In addition to the above, servers SHOULD exclude [IdP icons used in the `m.login.sso` flow](/client-server-api/#definition-mloginsso-flow-schema) +from the freeze. See the `m.login.sso` flow schema for details. + +An *example* timeline for a server may be: + +* Matrix 1.11 release: Clients begin supporting authenticated media. +* Matrix 1.12 release: Servers freeze unauthenticated media access. + * Media uploaded prior to this point still works with the deprecated endpoints. + * Newly uploaded (or cached) media *only* works on the authenticated endpoints. + +Matrix 1.12 is expected to be released in the July-September 2024 calendar quarter. +{{% /boxes/warning %}} + +{{% http-api spec="client-server" api="authed-content-repo" %}} {{% http-api spec="client-server" api="content-repo" %}} diff --git a/content/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/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..55e73dd5 100644 --- a/content/client-server-api/modules/read_markers.md +++ b/content/client-server-api/modules/read_markers.md @@ -1,5 +1,6 @@ +### Read and unread markers -### Fully read markers +#### Fully read markers The history for a given room may be split into three sections: messages the user has read (or indicated they aren't interested in them), @@ -8,7 +9,7 @@ user hasn't seen yet. The "fully read marker" (also known as a "read marker") marks the last event of the first section, whereas the user's read receipt marks the last event of the second section. -#### Events +##### Events The user's fully read marker is kept as an event in the room's [account data](#client-config). The event may be read to determine the user's @@ -22,7 +23,7 @@ should be considered to be the user's read receipt location. {{% event event="m.fully_read" %}} -#### Client behaviour +##### Client behaviour The client cannot update fully read markers by directly modifying the `m.fully_read` account data event. Instead, the client must make use of @@ -41,7 +42,7 @@ might wish to save an extra HTTP call. Providing `m.read` and/or {{% http-api spec="client-server" api="read_markers" %}} -#### Server behaviour +##### Server behaviour The server MUST prevent clients from setting `m.fully_read` directly in room account data. The server must additionally ensure that it treats @@ -53,3 +54,44 @@ Upon updating the `m.fully_read` event due to a request to `/read_markers`, the server MUST send the updated account data event through to the client via the event stream (eg: `/sync`), provided any applicable filters are also satisfied. + +#### Unread markers + +Clients may use "unread markers" to allow users to label rooms for later +attention irrespective of [read receipts](#receipts) or +[fully read markers](#fully-read-markers). + +##### Events + +The user's unread marker in a room is kept under an `m.marked_unread` +event in the room's [account data](#client-config). The event may be read +to determine the user's current unread marker state in the room. Just +like other account data events, the event will be pushed down the event +stream when updated. + +{{% event event="m.marked_unread" %}} + +##### Client behaviour + +Clients MUST update unread markers by directly modifying the `m.marked_unread` +room account data event. When marking a room as unread, clients SHOULD NOT change +the `m.fully_read` marker, so that the user's read position in the room is +retained. + +When the `unread` field is `true`, clients SHOULD visually annotate the room +to indicate that it is unread. Exactly how this is achieved is left as an +implementation detail. It is RECOMMENDED that clients use a treatment similar +to how they represent rooms with unread notifications. + +Clients SHOULD reset the unread marker by setting `unread` to `false` when +opening a room to display its timeline. + +Clients that offer functionality to mark a room as _read_ by sending a read +receipt for the last event, SHOULD reset the unread marker simultaneously. + +If the `m.marked_unread` event does not exist on the user's account data, +clients MUST behave as if `unread` was `false`. + +##### Server behaviour + +Servers have no additional requirements placed on them by this submodule. diff --git a/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..658f9e77 100644 --- a/content/rooms/fragments/v2-state-res.md +++ b/content/rooms/fragments/v2-state-res.md @@ -138,7 +138,7 @@ The *resolution* of a set of states is obtained as follows: 1. Select the set *X* of all *power events* that appear in the *full conflicted set*. For each such power event *P*, enlarge *X* by adding the events in the auth chain of *P* which also belong to the full - conflicted set. Sort $X$ into a list using the *reverse topological + conflicted set. Sort *X* into a list using the *reverse topological power ordering*. 2. Apply the *iterative auth checks algorithm*, starting from the *unconflicted state map*, to the list of events from the previous 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 782edb3e..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 @@ -72,7 +73,7 @@ The `redacts` property of `m.room.redaction` events is moved from a top-level event property to a property under the event `content`. For backwards-compatibility with older clients, servers should add a `redacts` property -to the top level of `m.room.redaction` events in when serving such events over the +to the top level of `m.room.redaction` events when serving such events over the Client-Server API. For improved compatibility with newer clients, servers should add a `redacts` property @@ -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..43cb5881 --- /dev/null +++ b/data/api/client-server/authed-content-repo.yaml @@ -0,0 +1,518 @@ +# Copyright 2016 OpenMarket Ltd +# Copyright 2019-2024 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server (Authenticated) Content Repository API + version: 1.0.0 +paths: + "/media/download/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository. + description: |- + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: The name of the file that was previously uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/download/{serverName}/{mediaId}/{fileName}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download content from the content repository overriding the file name. + description: |- + This will download content from the content repository (same as + the previous endpoint) but replaces the target file name with the one + provided by the caller. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentOverrideNameAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: path + name: fileName + required: true + description: A filename to give in the `Content-Disposition` header. + example: filename.jpg + schema: + type: string + - $ref: '#/components/parameters/timeout_ms' + responses: + "200": + description: The content that was previously uploaded. + headers: + Content-Type: + $ref: '#/components/headers/downloadContentType' + Content-Disposition: + description: |- + The `fileName` requested or the name of the file that was previously + uploaded, if set. + schema: + type: string + content: + application/octet-stream: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the uploaded file." + "307": + $ref: '#/components/responses/downloadRedirect' + "308": + $ref: '#/components/responses/downloadRedirect' + "429": + $ref: '#/components/responses/rateLimited' + "502": + $ref: '#/components/responses/downloadTooLarge' + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + "/media/thumbnail/{serverName}/{mediaId}": + get: + x-addedInMatrixVersion: "1.11" + summary: Download a thumbnail of content from the content repository + description: |- + Download a thumbnail of content from the content repository. + See the [Thumbnails](/client-server-api/#thumbnails) section for more information. + + {{% boxes/note %}} + Clients SHOULD NOT generate or use URLs which supply the access token in + the query string. These URLs may be copied by users verbatim and provided + in a chat message to another user, disclosing the sender's access token. + {{% /boxes/note %}} + + Clients MAY be redirected using the 307/308 responses below to download + the request object. This is typical when the homeserver uses a Content + Delivery Network (CDN). + operationId: getContentThumbnailAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - $ref: '#/components/parameters/serverName' + - $ref: '#/components/parameters/mediaId' + - in: query + name: width + required: true + description: |- + The *desired* width of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: height + required: true + description: |- + The *desired* height of the thumbnail. The actual thumbnail may be + larger than the size specified. + example: 64 + schema: + type: integer + - in: query + name: method + description: |- + The desired resizing method. See the [Thumbnails](/client-server-api/#thumbnails) + section for more information. + example: scale + schema: + type: string + enum: + - crop + - scale + - $ref: '#/components/parameters/timeout_ms' + - in: query + name: animated + x-addedInMatrixVersion: "1.11" + required: false + description: | + Indicates preference for an animated thumbnail from the server, if possible. Animated + thumbnails typically use the content types `image/gif`, `image/png` (with APNG format), + `image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg` + content types. + + When `true`, the server SHOULD return an animated thumbnail if possible and supported. + When `false`, the server MUST NOT return an animated thumbnail. For example, returning a + static `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT + return an animated thumbnail. + + Servers SHOULD prefer to return `image/webp` thumbnails when supporting animation. + + When `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the + server SHOULD behave as though `animated` is `false`. + example: false + schema: + type: boolean + responses: + "200": + description: A thumbnail of the requested content. + headers: + Content-Type: + description: The content type of the thumbnail. + schema: + type: string + enum: + - image/jpeg + - image/png + - image/apng + - image/gif + - image/webp + content: + image/jpeg: + schema: + # This is a workaround for us not being able to say the response is required. + description: "**Required.** The bytes for the thumbnail." + image/png: + schema: + x-changedInMatrixVersion: + "1.11": The PNG may be of the APNG variety if animation is supported and requested. + description: | + **Required.** The bytes for the thumbnail. The thumbnail MAY use an animated + format if `animated=true`. + image/apng: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/gif: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + image/webp: + schema: + x-addedInMatrixVersion: "1.11" + description: "**Required.** The bytes for the *animated* thumbnail." + "307": + $ref: '#/components/responses/thumbnailRedirect' + "308": + $ref: '#/components/responses/thumbnailRedirect' + "400": + description: |- + The request does not make sense to the server, or the server cannot thumbnail + the content. For example, the client requested non-integer dimensions or asked + for negatively-sized images. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_UNKNOWN", + "error": "Cannot generate thumbnails for the requested content" + } + "413": + description: The local content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "429": + $ref: '#/components/responses/rateLimited' + "502": + description: The remote content is too large for the server to thumbnail. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_TOO_LARGE", + "error": "Content is too large to thumbnail" + } + "504": + $ref: '#/components/responses/notYetUploaded' + tags: + - Media + /media/preview_url: + get: + x-addedInMatrixVersion: "1.11" + summary: Get information about a URL for a client + description: |- + Get information about a URL for the client. Typically this is called when a + client sees a URL in a message and wants to render a preview for the user. + + {{% boxes/note %}} + Clients should consider avoiding this endpoint for URLs posted in encrypted + rooms. Encrypted rooms often contain more sensitive information the users + do not want to share with the homeserver, and this can mean that the URLs + being shared should also not be shared with the homeserver. + {{% /boxes/note %}} + operationId: getUrlPreviewAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + parameters: + - in: query + name: url + description: The URL to get a preview of. + required: true + example: https://matrix.org + schema: + type: string + format: uri + - in: query + name: ts + description: |- + The preferred point in time to return a preview for. The server may + return a newer version if it does not have the requested version + available. + example: 1510610716656 + schema: + type: integer + format: int64 + responses: + "200": + description: |- + The OpenGraph data for the URL, which may be empty. Some values are + replaced with matrix equivalents if they are provided in the response. + The differences from the OpenGraph protocol are described here. + content: + application/json: + schema: + type: object + properties: + matrix:image:size: + type: integer + format: int64 + description: The byte-size of the image. Omitted if there is no image attached. + og:image: + type: string + format: uri + description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to + the image. Omitted if there is no image. + examples: + response: + value: { + "og:title": "Matrix Blog Post", + "og:description": "This is a really cool blog post from matrix.org", + "og:image": "mxc://example.com/ascERGshawAWawugaAcauga", + "og:image:type": "image/png", + "og:image:height": 48, + "og:image:width": 48, + "matrix:image:size": 102400 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media + /media/config: + get: + x-addedInMatrixVersion: "1.11" + summary: Get the configuration for the content repository. + description: |- + This endpoint allows clients to retrieve the configuration of the content + repository, such as upload limitations. + Clients SHOULD use this as a guide when using content repository endpoints. + All values are intentionally left optional. Clients SHOULD follow + the advice given in the field description when the field is not available. + + {{% boxes/note %}} + Both clients and server administrators should be aware that proxies + between the client and the server may affect the apparent behaviour of content + repository APIs, for example, proxies may enforce a lower upload size limit + than is advertised by the server on this endpoint. + {{% /boxes/note %}} + operationId: getConfigAuthed + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: The public content repository configuration for the matrix server. + content: + application/json: + schema: + type: object + properties: + m.upload.size: + type: integer + format: int64 + description: |- + The maximum size an upload can be in bytes. + Clients SHOULD use this as a guide when uploading content. + If not listed or null, the size limit should be treated as unknown. + examples: + response: + value: { + "m.upload.size": 50000000 + } + "429": + $ref: '#/components/responses/rateLimited' + tags: + - Media +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + accessTokenQuery: + $ref: definitions/security.yaml#/accessTokenQuery + accessTokenBearer: + $ref: definitions/security.yaml#/accessTokenBearer + parameters: + serverName: + in: path + name: serverName + required: true + description: | + The server name from the `mxc://` URI (the authority component). + example: matrix.org + schema: + type: string + format: mx-server-name + mediaId: + in: path + name: mediaId + required: true + description: | + The media ID from the `mxc://` URI (the path component). + example: ascERGshawAWawugaAcauga + schema: + type: string + timeout_ms: + in: query + name: timeout_ms + x-addedInMatrixVersion: "1.7" + description: | + The maximum number of milliseconds that the client is willing to wait to + start receiving data, in the case that the content has not yet been + uploaded. The default value is 20000 (20 seconds). The content + repository 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. + schema: + type: string + diff --git a/data/api/client-server/capabilities.yaml b/data/api/client-server/capabilities.yaml index 99f07962..3ae26b22 100644 --- a/data/api/client-server/capabilities.yaml +++ b/data/api/client-server/capabilities.yaml @@ -46,16 +46,8 @@ paths: type: object properties: m.change_password: - type: object + $ref: '#/components/schemas/booleanCapability' description: Capability to indicate if the user can change their password. - title: ChangePasswordCapability - properties: - enabled: - type: boolean - description: True if the user can change their password, false otherwise. - example: false - required: - - enabled m.room_versions: type: object description: The room versions the server supports. @@ -78,6 +70,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 +131,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..92ca6caa 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' @@ -254,11 +270,24 @@ paths: - Media "/media/v3/download/{serverName}/{mediaId}/{fileName}": get: + deprecated: true summary: Download content from the content repository overriding the file name description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename) + (requires authentication). + {{% /boxes/note %}} + This will download content from the content repository (same as the previous endpoint) but replace the target file name with the one provided by the caller. + + {{% boxes/warning %}} + {{< changed-in v="1.11" >}} This endpoint MAY return `404 M_NOT_FOUND` + for media which exists, but is after the server froze unauthenticated + media access. See [Client Behaviour](/client-server-api/#content-repo-client-behaviour) for more + information. + {{% /boxes/warning %}} operationId: getContentOverrideName parameters: - $ref: '#/components/parameters/serverName' @@ -304,10 +333,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 +404,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 @@ -455,8 +497,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 +572,13 @@ paths: - Media /media/v3/config: get: + deprecated: true summary: Get the configuration for the content repository. description: |- + {{% boxes/note %}} + Replaced by [`GET /_matrix/client/v1/media/config`](/client-server-api/#get_matrixclientv1mediaconfig). + {{% /boxes/note %}} + This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. @@ -625,7 +677,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 +691,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 +715,9 @@ components: bytes: content: application/octet-stream: - example: - description: The content to be uploaded. + schema: + description: The content to be uploaded. + example: required: true responses: uploadTooLarge: diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index 0f3a46be..8f499d23 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -19,11 +19,26 @@ paths: /keys/device_signing/upload: post: x-addedInMatrixVersion: "1.1" + x-changedInMatrixVersion: + "1.11": UIA is not always required for this endpoint. summary: Upload cross-signing keys. description: |- Publishes cross-signing keys for the user. This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + User-Interactive Authentication MUST be performed, except in these cases: + - there is no existing cross-signing master key uploaded to the homeserver, OR + - there is an existing cross-signing master key and it exactly matches the + cross-signing master key provided in the request body. If there are any additional + keys provided in the request (self-signing key, user-signing key) they MUST also + match the existing keys stored on the server. In other words, the request contains + no new keys. + + This allows clients to freely upload one set of keys, but not modify/overwrite keys if + they already exist. Allowing clients to upload the same set of keys more than once + makes this endpoint idempotent in the case where the response is lost over the network, + which would otherwise cause a UIA challenge upon retry. operationId: uploadCrossSigningKeys security: - accessTokenQuery: [] diff --git a/data/api/client-server/definitions/client_event_without_room_id.yaml b/data/api/client-server/definitions/client_event_without_room_id.yaml index d78dcc68..b12611a2 100644 --- a/data/api/client-server/definitions/client_event_without_room_id.yaml +++ b/data/api/client-server/definitions/client_event_without_room_id.yaml @@ -90,6 +90,7 @@ properties: "origin_server_ts": 1632491098485, "unsigned": { "age": 1257, + "membership": "leave" } } transaction_id: @@ -112,3 +113,23 @@ properties: this. title: EventContent type: object + membership: + description: | + The room membership of the user making the request, at the time of the event. + + This property is the value of the `membership` property of the + requesting user's [`m.room.member`](/client-server-api#mroommember) + state at the point of the event, including any changes caused by the + event. If the user had yet to join the room at the time of the event + (i.e, they have no `m.room.member` state), this property is set to + `leave`. + + Homeservers SHOULD populate this property + wherever practical, but they MAY omit it if necessary (for example, + if calculating the value is expensive, servers might choose to only + implement it in encrypted rooms). The property is *not* normally populated + in events pushed to application services via the application service transaction API + (where there is no clear definition of "requesting user"). + type: string + example: join + x-addedInMatrixVersion: "1.11" diff --git a/data/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/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/login_token.yaml b/data/api/client-server/login_token.yaml index a8ab1248..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). @@ -45,7 +45,7 @@ paths: intend to log in multiple devices must generate a token for each. With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt - for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + for verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt the user for verification to ensure explicit consent is gained for each additional client. Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum @@ -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 e00bdd96..1a55084c 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -195,8 +195,7 @@ paths: description: |- Get the combined profile information for this user. This API may be used to fetch the user's own profile information or other users; either - locally or on remote homeservers. This API may return keys which are not - limited to `displayname` or `avatar_url`. + locally or on remote homeservers. operationId: getUserProfile parameters: - in: path diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index afd30459..84aef5b1 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -387,6 +387,7 @@ paths: access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: changePassword @@ -592,6 +593,7 @@ paths: parameter because the homeserver is expected to sign the request to the identity server instead. security: + - {} - accessTokenQuery: [] - accessTokenBearer: [] operationId: deactivateAccount diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index b033e88f..c4b0228c 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -312,14 +312,13 @@ components: Whether to additionally include events which only relate indirectly to the given event, i.e. events related to the given event via two or more direct relationships. - If set to `false`, only events which have direct a relation with the given + If set to `false`, only events which have a direct relation with the given event will be included. - If set to `true`, all events which relate to the given event, or relate to - 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/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/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 7804a6f6..465207e9 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -207,9 +207,9 @@ paths: title: SignedMembershipEvent x-addedInMatrixVersion: "1.2" description: |- - Required if the `content` of the event in the request contained the `join_authorised_via_users_server` - field. The signed copy of the membership event sent to other servers by the resident server, - including the resident server's signature. + The membership event sent to other servers by the resident server including a signature + from the resident server. Required if the room is [restricted](/client-server-api/#restricted-rooms) + and the joining user is authorised by one of the conditions. servers_in_room: type: array x-addedInMatrixVersion: "1.6" diff --git a/data/event-schemas/examples/core/room_event.json b/data/event-schemas/examples/core/room_event.json index 521225cc..9bd62e28 100644 --- a/data/event-schemas/examples/core/room_event.json +++ b/data/event-schemas/examples/core/room_event.json @@ -5,6 +5,7 @@ "sender": "@example:example.org", "origin_server_ts": 1432735824653, "unsigned": { - "age": 1234 + "age": 1234, + "membership": "join" } } 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/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/changelogs.html b/layouts/shortcodes/changelog/changelogs.html index 78b5932f..f42963da 100644 --- a/layouts/shortcodes/changelog/changelogs.html +++ b/layouts/shortcodes/changelog/changelogs.html @@ -5,6 +5,6 @@ {{ with .Page.Resources.Match "*.md" }} {{ range ((sort . "Params.date" "desc")) }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/layouts/shortcodes/cs-module.html b/layouts/shortcodes/cs-module.html index 475ebd48..52c9a5d9 100644 --- a/layouts/shortcodes/cs-module.html +++ b/layouts/shortcodes/cs-module.html @@ -11,6 +11,6 @@ {{ with .Site.GetPage "client-server-api/modules" }} {{ with .Resources.GetMatch (printf "%s%s" $name ".md") }} -{{ .Content }} +{{ .RenderShortcodes }} {{ end }} {{ end }} diff --git a/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/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") {