diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 5fa57a4f..3288b42a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -45,7 +45,7 @@ jobs: - name: "πŸ”Ž Run validator" run: | python scripts/check-event-schema-examples.py - + check-openapi-examples: name: "πŸ”Ž Check OpenAPI definitions examples" runs-on: ubuntu-latest @@ -268,7 +268,7 @@ jobs: - name: "βž• Setup Hugo" uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d with: - hugo-version: '0.93.3' + hugo-version: '0.113.0' extended: true - name: "πŸ“₯ Source checkout" uses: actions/checkout@v4 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 05e5be7a..6f8d1353 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -26,8 +26,9 @@ jobs: - name: πŸ”¨ Install dependencies run: "yarn install --frozen-lockfile" + # We bump the package.json version to git, we just need it for publish to do the right thing - name: πŸŽ– Bump package.json version - run: "yarn version --new-version $VERSION" + run: "yarn version --new-version ${VERSION#v} --no-git-tag-version" env: VERSION: ${{ github.event.release.tag_name }}.0 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 93763a29..f93b44f4 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -12,7 +12,7 @@ The documentation style is described at https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst. Matrix-spec workflows --------------------- +--------------------- Specification changes ~~~~~~~~~~~~~~~~~~~~~ @@ -117,7 +117,7 @@ license - in our case, this is Apache Software License v2 (see LICENSE). In order to have a concrete record that your contribution is intentional and you agree to license it under the same terms as the project's license, we've adopted the same lightweight approach used by the `Linux Kernel `_, -`Docker `_, and many other projects: the `Developer Certificate of Origin `_ (DCO). This is a simple declaration that you wrote the contribution or otherwise have the right to contribute it to Matrix:: diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index 6eec3e7c..350e39cd 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -49,3 +49,6 @@ $td-enable-google-fonts: false; * The font itself is loaded via stylesheet link layouts/partials/hooks/head-end.html. */ $font-family-sans-serif: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; + +// Disable smooth scrolling as it makes TOC highlighting jump during the transition. +$enable-smooth-scroll: false; diff --git a/changelogs/application_service/newsfragments/1744.clarification b/changelogs/application_service/newsfragments/1744.clarification deleted file mode 100644 index 908c48ab..00000000 --- a/changelogs/application_service/newsfragments/1744.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. diff --git a/changelogs/client_server/newsfragments/1629.clarification b/changelogs/client_server/newsfragments/1629.clarification deleted file mode 100644 index 81ed5aaa..00000000 --- a/changelogs/client_server/newsfragments/1629.clarification +++ /dev/null @@ -1 +0,0 @@ -The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1685.clarification b/changelogs/client_server/newsfragments/1685.clarification deleted file mode 100644 index 9daf762e..00000000 --- a/changelogs/client_server/newsfragments/1685.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that read-receipts should be batched by thread as well as room. diff --git a/changelogs/client_server/newsfragments/1687.clarification b/changelogs/client_server/newsfragments/1687.clarification deleted file mode 100644 index 09bacd28..00000000 --- a/changelogs/client_server/newsfragments/1687.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that threads can be created based on replies. diff --git a/changelogs/client_server/newsfragments/1690.clarification b/changelogs/client_server/newsfragments/1690.clarification deleted file mode 100644 index 02427e33..00000000 --- a/changelogs/client_server/newsfragments/1690.clarification +++ /dev/null @@ -1 +0,0 @@ -Make clearer in the example for reply fallbacks that the prefix sequence should be repeated for each line. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1695.clarification b/changelogs/client_server/newsfragments/1695.clarification deleted file mode 100644 index 32d9bb51..00000000 --- a/changelogs/client_server/newsfragments/1695.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the format of account data objects for secret storage. diff --git a/changelogs/client_server/newsfragments/1712.clarification b/changelogs/client_server/newsfragments/1712.clarification deleted file mode 100644 index 9e1523c5..00000000 --- a/changelogs/client_server/newsfragments/1712.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. diff --git a/changelogs/client_server/newsfragments/1715.clarification b/changelogs/client_server/newsfragments/1715.clarification deleted file mode 100644 index a1d30432..00000000 --- a/changelogs/client_server/newsfragments/1715.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify one-time key and fallback key types in examples. diff --git a/changelogs/client_server/newsfragments/1719.clarification b/changelogs/client_server/newsfragments/1719.clarification deleted file mode 100644 index 031e1e41..00000000 --- a/changelogs/client_server/newsfragments/1719.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. diff --git a/changelogs/client_server/newsfragments/1720.clarification b/changelogs/client_server/newsfragments/1720.clarification deleted file mode 100644 index e8c8a623..00000000 --- a/changelogs/client_server/newsfragments/1720.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify how to perform the ECDH exchange in step 12 of the SAS process. diff --git a/changelogs/client_server/newsfragments/1728.feature b/changelogs/client_server/newsfragments/1728.feature deleted file mode 100644 index 98d055fb..00000000 --- a/changelogs/client_server/newsfragments/1728.feature +++ /dev/null @@ -1 +0,0 @@ -Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). diff --git a/changelogs/client_server/newsfragments/1730.feature b/changelogs/client_server/newsfragments/1730.feature deleted file mode 100644 index 673f7515..00000000 --- a/changelogs/client_server/newsfragments/1730.feature +++ /dev/null @@ -1 +0,0 @@ -Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). diff --git a/changelogs/client_server/newsfragments/1731.feature b/changelogs/client_server/newsfragments/1731.feature deleted file mode 100644 index f4561bf3..00000000 --- a/changelogs/client_server/newsfragments/1731.feature +++ /dev/null @@ -1 +0,0 @@ -Use the `body` field as media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1732.clarification b/changelogs/client_server/newsfragments/1732.clarification deleted file mode 100644 index 61e74c6c..00000000 --- a/changelogs/client_server/newsfragments/1732.clarification +++ /dev/null @@ -1 +0,0 @@ -Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1734.clarification b/changelogs/client_server/newsfragments/1734.clarification deleted file mode 100644 index 32d9bb51..00000000 --- a/changelogs/client_server/newsfragments/1734.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the format of account data objects for secret storage. diff --git a/changelogs/client_server/newsfragments/1735.feature b/changelogs/client_server/newsfragments/1735.feature deleted file mode 100644 index 1d764142..00000000 --- a/changelogs/client_server/newsfragments/1735.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1740.clarification b/changelogs/client_server/newsfragments/1740.clarification deleted file mode 100644 index 1760ac9f..00000000 --- a/changelogs/client_server/newsfragments/1740.clarification +++ /dev/null @@ -1 +0,0 @@ -Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1742.clarification b/changelogs/client_server/newsfragments/1742.clarification deleted file mode 100644 index 84f21b9e..00000000 --- a/changelogs/client_server/newsfragments/1742.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1746.feature b/changelogs/client_server/newsfragments/1746.feature deleted file mode 100644 index a3673074..00000000 --- a/changelogs/client_server/newsfragments/1746.feature +++ /dev/null @@ -1 +0,0 @@ -Add support for recursion on the /relations endpoints (MSC3981). diff --git a/changelogs/client_server/newsfragments/1748.clarification b/changelogs/client_server/newsfragments/1748.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1748.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1755.clarification b/changelogs/client_server/newsfragments/1755.clarification new file mode 100644 index 00000000..65c5ba36 --- /dev/null +++ b/changelogs/client_server/newsfragments/1755.clarification @@ -0,0 +1 @@ +Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291). diff --git a/changelogs/internal/newsfragments/1680.clarification b/changelogs/internal/newsfragments/1680.clarification deleted file mode 100644 index 16352364..00000000 --- a/changelogs/internal/newsfragments/1680.clarification +++ /dev/null @@ -1 +0,0 @@ -Update the spec release process. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1697.clarification b/changelogs/internal/newsfragments/1697.clarification deleted file mode 100644 index d238b2e9..00000000 --- a/changelogs/internal/newsfragments/1697.clarification +++ /dev/null @@ -1 +0,0 @@ -Minor clarifications to the contributing guide. diff --git a/changelogs/internal/newsfragments/1699.clarification b/changelogs/internal/newsfragments/1699.clarification deleted file mode 100644 index 7d1c0526..00000000 --- a/changelogs/internal/newsfragments/1699.clarification +++ /dev/null @@ -1 +0,0 @@ -Update Docsy to v0.8.0. diff --git a/changelogs/internal/newsfragments/1718.clarification b/changelogs/internal/newsfragments/1718.clarification deleted file mode 100644 index 5b89875a..00000000 --- a/changelogs/internal/newsfragments/1718.clarification +++ /dev/null @@ -1 +0,0 @@ -Add some clarifications around implementation requirements for MSCs diff --git a/changelogs/internal/newsfragments/1724.clarification b/changelogs/internal/newsfragments/1724.clarification deleted file mode 100644 index 12be0c5a..00000000 --- a/changelogs/internal/newsfragments/1724.clarification +++ /dev/null @@ -1 +0,0 @@ -Update HTML templates to include links to object schema definitions. diff --git a/changelogs/internal/newsfragments/1745.clarification b/changelogs/internal/newsfragments/1745.clarification deleted file mode 100644 index acd85892..00000000 --- a/changelogs/internal/newsfragments/1745.clarification +++ /dev/null @@ -1 +0,0 @@ -Factor out all the common parameters of the various `/relations` apis. diff --git a/changelogs/internal/newsfragments/1751.clarification b/changelogs/internal/newsfragments/1751.clarification deleted file mode 100644 index 50c50693..00000000 --- a/changelogs/internal/newsfragments/1751.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. diff --git a/changelogs/internal/newsfragments/1754.clarification b/changelogs/internal/newsfragments/1754.clarification deleted file mode 100644 index 50c50693..00000000 --- a/changelogs/internal/newsfragments/1754.clarification +++ /dev/null @@ -1 +0,0 @@ -Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. diff --git a/changelogs/internal/newsfragments/1713.misc b/changelogs/internal/newsfragments/1765.clarification similarity index 100% rename from changelogs/internal/newsfragments/1713.misc rename to changelogs/internal/newsfragments/1765.clarification diff --git a/changelogs/internal/newsfragments/1769.clarification b/changelogs/internal/newsfragments/1769.clarification new file mode 100644 index 00000000..ebf8030d --- /dev/null +++ b/changelogs/internal/newsfragments/1769.clarification @@ -0,0 +1 @@ +Formatting fixes in CONTRIBUTING.rst. diff --git a/changelogs/room_versions/newsfragments/1717.clarification b/changelogs/room_versions/newsfragments/1717.clarification deleted file mode 100644 index 80bc9d55..00000000 --- a/changelogs/room_versions/newsfragments/1717.clarification +++ /dev/null @@ -1 +0,0 @@ -For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1721.clarification b/changelogs/server_server/newsfragments/1721.clarification deleted file mode 100644 index a742501b..00000000 --- a/changelogs/server_server/newsfragments/1721.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. diff --git a/changelogs/server_server/newsfragments/1740.clarification b/changelogs/server_server/newsfragments/1740.clarification deleted file mode 100644 index 1760ac9f..00000000 --- a/changelogs/server_server/newsfragments/1740.clarification +++ /dev/null @@ -1 +0,0 @@ -Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1741.clarification b/changelogs/server_server/newsfragments/1741.clarification deleted file mode 100644 index ec31cac1..00000000 --- a/changelogs/server_server/newsfragments/1741.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. \ No newline at end of file diff --git a/config.toml b/config.toml index 15a284b5..7197c693 100644 --- a/config.toml +++ b/config.toml @@ -65,8 +65,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 = "9" -# release_date = "November 29, 2023" +# minor = "10" +# release_date = "March 22, 2024" # User interface configuration [params.ui] diff --git a/content/changelog/v1.10.md b/content/changelog/v1.10.md new file mode 100644 index 00000000..16b3217d --- /dev/null +++ b/content/changelog/v1.10.md @@ -0,0 +1,102 @@ +--- +date: 2024-03-22T09:59:45-06:00 +--- + + +## v1.10 + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.10
Release dateMarch 22, 2024
+ + + +### Client-Server API + +**Backwards Compatible Changes** + +- Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026). ([#1728](https://github.com/matrix-org/matrix-spec/issues/1728)) +- Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025). ([#1730](https://github.com/matrix-org/matrix-spec/issues/1730)) +- Use the `body` field as optional media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530). ([#1731](https://github.com/matrix-org/matrix-spec/issues/1731)) +- Add server support discovery endpoint, as per [MSC1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929). ([#1733](https://github.com/matrix-org/matrix-spec/issues/1733)) +- Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077). ([#1735](https://github.com/matrix-org/matrix-spec/issues/1735)) +- Specify that the `Retry-After` header may be used to rate-limit a client, as per [MSC4041](https://github.com/matrix-org/matrix-spec-proposals/pull/4041). ([#1737](https://github.com/matrix-org/matrix-spec/issues/1737)) +- Add support for recursion on the `GET /relations` endpoints, as per [MSC3981](https://github.com/matrix-org/matrix-spec-proposals/pull/3981). ([#1746](https://github.com/matrix-org/matrix-spec/issues/1746)) + +**Spec Clarifications** + +- The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead. ([#1629](https://github.com/matrix-org/matrix-spec/issues/1629)) +- Clarify that read receipts should be batched by thread as well as by room. ([#1685](https://github.com/matrix-org/matrix-spec/issues/1685)) +- Clarify that threads can be created based on replies. ([#1687](https://github.com/matrix-org/matrix-spec/issues/1687)) +- Clarify in the reply fallbacks example that the prefix sequence should be repeated for each line. ([#1690](https://github.com/matrix-org/matrix-spec/issues/1690)) +- Clarify the format of account data objects for secret storage. ([#1695](https://github.com/matrix-org/matrix-spec/issues/1695), [#1734](https://github.com/matrix-org/matrix-spec/issues/1734)) +- Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256. ([#1712](https://github.com/matrix-org/matrix-spec/issues/1712)) +- Clarify one-time key and fallback key types in examples. ([#1715](https://github.com/matrix-org/matrix-spec/issues/1715)) +- Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes. ([#1719](https://github.com/matrix-org/matrix-spec/issues/1719)) +- Clarify how to perform the ECDH exchange in step 12 of the SAS process. ([#1720](https://github.com/matrix-org/matrix-spec/issues/1720)) +- Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077). ([#1732](https://github.com/matrix-org/matrix-spec/issues/1732)) +- The [font](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font) element is deprecated in the HTML spec. Clients should prefer [span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span) with the `data-mx-bg-color` and `data-mx-color` attributes instead. ([#1739](https://github.com/matrix-org/matrix-spec/issues/1739)) +- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740)) +- Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`. ([#1742](https://github.com/matrix-org/matrix-spec/issues/1742)) +- Fix various typos throughout the specification. ([#1748](https://github.com/matrix-org/matrix-spec/issues/1748)) +- Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses. ([#1756](https://github.com/matrix-org/matrix-spec/issues/1756)) +- Clarify that the `m.push_rules` account data type cannot be set using the `/account_data` API, as per [MSC4010](https://github.com/matrix-org/matrix-spec-proposals/pull/4010). ([#1763](https://github.com/matrix-org/matrix-spec/issues/1763)) + + +### Server-Server API + +**Spec Clarifications** + +- Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies. ([#1721](https://github.com/matrix-org/matrix-spec/issues/1721)) +- Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint. ([#1740](https://github.com/matrix-org/matrix-spec/issues/1740)) +- Clarify that the `children_state`, `room_type` and `allowed_room_ids` properties in the items of the `children` array of the response of the `GET /hierarchy` endpoint are not required. ([#1741](https://github.com/matrix-org/matrix-spec/issues/1741)) + + +### Application Service API + +**Spec Clarifications** + +- Clarify that the `/login` and `/register` endpoints should fail when using the `m.login.application_service` login type without a valid `as_token`. ([#1744](https://github.com/matrix-org/matrix-spec/issues/1744)) + + +### Identity Service API + +No significant changes. + + +### Push Gateway API + +No significant changes. + + +### Room Versions + +**Spec Clarifications** + +- For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition. ([#1717](https://github.com/matrix-org/matrix-spec/issues/1717)) + + +### Appendices + +No significant changes. + + +### Internal Changes/Tooling + +**Spec Clarifications** + +- Update the spec release process. ([#1680](https://github.com/matrix-org/matrix-spec/issues/1680)) +- Minor clarifications to the contributing guide. ([#1697](https://github.com/matrix-org/matrix-spec/issues/1697)) +- Update Docsy to v0.8.0. ([#1699](https://github.com/matrix-org/matrix-spec/issues/1699), [#1762](https://github.com/matrix-org/matrix-spec/issues/1762)) +- Fix npm release script for `@matrix-org/spec`. ([#1713](https://github.com/matrix-org/matrix-spec/issues/1713)) +- Add some clarifications around implementation requirements for MSCs. ([#1718](https://github.com/matrix-org/matrix-spec/issues/1718)) +- Update HTML templates to include links to object schema definitions. ([#1724](https://github.com/matrix-org/matrix-spec/issues/1724)) +- Factor out all the common parameters of the various `/relations` apis. ([#1745](https://github.com/matrix-org/matrix-spec/issues/1745)) +- Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas. ([#1751](https://github.com/matrix-org/matrix-spec/issues/1751), [#1754](https://github.com/matrix-org/matrix-spec/issues/1754)) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 11023a33..5889ec0f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -106,7 +106,7 @@ No resource was found for this request. `M_LIMIT_EXCEEDED` Too many requests have been sent in a short period of time. Wait a while -then try again. +then try again. See [Rate limiting](#rate-limiting). `M_UNRECOGNIZED` The server did not understand the request. This is expected to be returned with @@ -212,6 +212,28 @@ only read state (e.g.: `/sync`, get account data, etc). The user is unable to reject an invite to join the server notices room. See the [Server Notices](#server-notices) module for more information. +#### Rate limiting + +Homeservers SHOULD implement rate limiting to reduce the risk of being +overloaded. If a request is refused due to rate limiting, it should +return a standard error response of the form: + +```json +{ + "errcode": "M_LIMIT_EXCEEDED", + "error": "string", + "retry_after_ms": integer (optional, deprecated) +} +``` + +Homeservers SHOULD include a [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#field.retry-after) +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 +deprecated, in favour of the `Retry-After` header. + +{{< changed-in v="1.10" >}}: `retry_after_ms` property deprecated in favour of `Retry-After` header. ### Transaction identifiers The client-server API typically uses `HTTP PUT` to submit requests with @@ -363,6 +385,8 @@ specify parameter values. The flow for this method is as follows: {{% http-api spec="client-server" api="versions" %}} +{{% http-api spec="client-server" api="support" %}} + ## Client Authentication Most API endpoints require the user to identify themselves by presenting @@ -2534,25 +2558,6 @@ users, they should include the display name and avatar URL fields in these events so that clients already have these details to hand, and do not have to perform extra round trips to query it. -## Security - -### Rate limiting - -Homeservers SHOULD implement rate limiting to reduce the risk of being -overloaded. If a request is refused due to rate limiting, it should -return a standard error response of the form: - -```json -{ - "errcode": "M_LIMIT_EXCEEDED", - "error": "string", - "retry_after_ms": integer (optional) -} -``` - -The `retry_after_ms` key SHOULD be included to tell the client how long -they have to wait in milliseconds before they can try again. - ## Modules Modules are parts of the Client-Server API which are not universal to diff --git a/content/client-server-api/modules/account_data.md b/content/client-server-api/modules/account_data.md index 12233bcd..3068602d 100644 --- a/content/client-server-api/modules/account_data.md +++ b/content/client-server-api/modules/account_data.md @@ -26,6 +26,15 @@ These events can also be received in a `/events` response or in the #### Server Behaviour -Servers MUST reject clients from setting account data for event types -that the server manages. Currently, this only includes -[m.fully\_read](#mfully_read). +Servers MUST reject setting account data for event types +that the server manages by using a 405 error response. +Currently, this only includes [`m.fully_read`](#mfully_read) +and [`m.push_rules`](#push-rules-events). This applies to +both global and room-specific account data. + +{{% boxes/note %}} +{{% changed-in v="1.10" %}} `m.push_rules` was added to the rejection +list. +{{% /boxes/note %}} + +Servers must allow clients to read the above event types as normal. diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index fd05b74b..5f5f450f 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -43,10 +43,10 @@ were limited to `m.text`, `m.emote`, `m.notice`, and Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML tags to permit, denying the use and rendering of anything else, is: -`font`, `del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`, -`a`, `ul`, `ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`, -`s`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`, -`th`, `td`, `caption`, `pre`, `span`, `img`, `details`, `summary`. +`del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`, `a`, `ul`, +`ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`, `s`, `code`, +`hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, +`caption`, `pre`, `span`, `img`, `details`, `summary`. {{% boxes/note %}} {{% added-in v="1.10" %}} @@ -55,6 +55,14 @@ requiring a [Spec Change Proposal](/proposals) when they are deprecated in the [WHATWG HTML Living Standard](https://html.spec.whatwg.org/multipage/). {{% /boxes/note %}} +{{% boxes/note %}} +{{% changed-in v="1.10" %}} +In previous versions of the specification, the `font` tag was suggested with the +`data-mx-bg-color`, `data-mx-color` and `color` attributes. This tag is now +deprecated in favor of the `span` tag with the `data-mx-bg-color` and +`data-mx-color` attributes in new messages. +{{% /boxes/note %}} + Not all attributes on those tags should be permitted as they may be avenues for other disruption attempts, such as adding `onclick` handlers or excessively large text. Clients should only permit the attributes @@ -65,7 +73,6 @@ the tag. | Tag | Permitted Attributes | |--------|--------------------------------------------------------------------------------------------------------------------------------------------| -| `font` | `data-mx-bg-color`, `data-mx-color`, `color` | | `span` | `data-mx-bg-color`, `data-mx-color`, `data-mx-spoiler` (see [spoiler messages](#spoiler-messages)) | | `a` | `name`, `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)) | diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 4df0ba13..c45a4824 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -174,15 +174,19 @@ In response to an incoming invite, a client may do one of several things: Clients may send more than one stream in a VoIP call. The streams should be differentiated by including metadata in the [`m.call.invite`](/client-server-api/#mcallinvite), [`m.call.answer`](/client-server-api/#mcallanswer) and [`m.call.negotiate`](/client-server-api/#mcallnegotiate) -events, using the `sdp_stream_metadata` property. +events, using the `sdp_stream_metadata` property. An [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed) +event can be sent when the metadata changes but no negotiation is required. -`sdp_stream_metadata` maps from the `id` of a stream in the session description, -to metadata about that stream. Currently only one property is defined for the -metadata. This is `purpose`, which should be a string indicating the purpose of -the stream. The following `purpose`s are defined: +Clients are recommended to not mute the audio of WebRTC tracks locally when an +incoming stream has the `audio_muted` field set to `true`. This is because when +the other user unmutes themselves, there may be a slight delay between their +client sending audio and the [`m.call.sdp_stream_metadata_changed`](/client-server-api/#mcallsdp_stream_metadata_changed) +event arriving and any audio sent in between will not be heard. The other user +will still stop transmitting audio once they mute on their side, so no audio is +sent without the user's knowledge. -* `m.usermedia` - stream that contains the webcam and/or microphone tracks -* `m.screenshare` - stream with the screen-sharing tracks +The same suggestion does not apply to `video_muted`. Clients _should_ mute video +locally, so that the receiving side doesn't see a black video. If `sdp_stream_metadata` is present and an incoming stream is not listed in it, the stream should be ignored. If a stream has a `purpose` of an unknown type, it diff --git a/data/api/client-server/support.yaml b/data/api/client-server/support.yaml new file mode 100644 index 00000000..1598d5d7 --- /dev/null +++ b/data/api/client-server/support.yaml @@ -0,0 +1,135 @@ +# Copyright 2024 KΓ©vin Commaille +# +# 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 Support Discovery API + version: 1.0.0 +paths: + /matrix/support: + get: + summary: Gets homeserver contacts and support details. + description: |- + Gets server admin contact and support page of the domain. + + Like the [well-known discovery URI](/client-server-api/#well-known-uri), + this should be accessed with the hostname of the homeserver by making a + GET request to `https://hostname/.well-known/matrix/support`. + + Note that this endpoint is not necessarily handled by the homeserver. + It may be served by another webserver, used for discovering support + information for the homeserver. + operationId: getWellknownSupport + x-addedInMatrixVersion: "1.10" + responses: + "200": + description: Server support information. + content: + application/json: + schema: + type: object + properties: + contacts: + type: array + description: |- + Ways to contact the server administrator. + + At least one of `contacts` or `support_page` is required. + If only `contacts` is set, it must contain at least one + item. + items: + type: object + title: Contact + description: A way to contact the server administrator. + properties: + matrix_id: + type: string + description: |- + A [Matrix User ID](/appendices/#user-identifiers) + representing the administrator. + + It could be an account registered on a different + homeserver so the administrator can be contacted + when the homeserver is down. + + At least one of `matrix_id` or `email_address` is + required. + email_address: + type: string + description: |- + An email address to reach the administrator. + + At least one of `matrix_id` or `email_address` is + required. + role: + type: string + enum: + - "m.role.admin" + - "m.role.security" + description: |- + An informal description of what the contact methods + are used for. + + `m.role.admin` is a catch-all role for any queries + and `m.role.security` is intended for sensitive + requests. + + Unspecified roles are permitted through the use of + [Namespaced Identifiers](/appendices/#common-namespaced-identifier-grammar). + required: + - role + example: { + "matrix_id": "@admin:example.org", + "email_address": "admin@example.org", + "role": "m.role.admin" + } + support_page: + type: string + description: |- + The URL of a page to give users help specific to the + homeserver, like extra login/registration steps. + + At least one of `contacts` or `support_page` is required. + example: "https://example.org/support.html" + examples: + response: + value: + { + "contacts": [ + { + "matrix_id": "@admin:example.org", + "email_address": "admin@example.org", + "role": "m.role.admin" + }, + { + "email_address": "security@example.org", + "role": "m.role.security" + } + ], + "support_page": "https://example.org/support.html" + } + "404": + description: No server support information available. + tags: + - Server administration +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /.well-known diff --git a/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml new file mode 100644 index 00000000..43b4fd75 --- /dev/null +++ b/data/event-schemas/examples/m.call.sdp_stream_metadata_changed.yaml @@ -0,0 +1,16 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.sdp_stream_metadata_changed", + "content": { + "version": "1", + "call_id": "1414213562373095", + "party_id": "1732050807568877", + "sdp_stream_metadata": { + "2311546231": { + "purpose": "m.usermedia", + "audio_muted:": true, + "video_muted": true + } + } + } +} diff --git a/data/event-schemas/schema/components/sdp_stream_metadata.yaml b/data/event-schemas/schema/components/sdp_stream_metadata.yaml index f16b4cbd..35566abe 100644 --- a/data/event-schemas/schema/components/sdp_stream_metadata.yaml +++ b/data/event-schemas/schema/components/sdp_stream_metadata.yaml @@ -13,8 +13,8 @@ additionalProperties: purpose: type: string enum: - - m.usermedia - - m.screenshare + - m.usermedia + - m.screenshare description: |- The purpose of the stream. @@ -23,5 +23,19 @@ additionalProperties: * `m.usermedia`: Stream that contains the webcam and/or microphone tracks. * `m.screenshare`: Stream with the screen-sharing tracks. + audio_muted: + type: boolean + description: |- + Whether the audio track in the stream is muted. + + Defaults to `false` if not present. + x-addedInMatrixVersion: "1.11" + video_muted: + type: boolean + description: |- + Whether the video track in the stream is muted. + + Defaults to `false` if not present. + x-addedInMatrixVersion: "1.11" required: - - purpose + - purpose diff --git a/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml new file mode 100644 index 00000000..953817c2 --- /dev/null +++ b/data/event-schemas/schema/m.call.sdp_stream_metadata_changed.yaml @@ -0,0 +1,21 @@ +type: object +x-addedInMatrixVersion: "1.11" +description: |- + This event is sent by callers when they wish to update a stream's metadata + but no negotiation is required. +allOf: + - $ref: core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - $ref: core-event-schema/call_event.yaml + properties: + sdp_stream_metadata: + $ref: components/sdp_stream_metadata.yaml + required: + - sdp_stream_metadata + type: + type: string + enum: + - m.call.sdp_stream_metadata_changed diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html index da1a69bd..036522de 100644 --- a/layouts/partials/openapi/render-content-type.html +++ b/layouts/partials/openapi/render-content-type.html @@ -1,27 +1,30 @@ {{/* - Render a table showing content type and description, given: + Render a table showing content types and their descriptions, given + two arrays with equal length: - * `content_type`: the content type as a string + * `content_types`: the content type strings - * `description`: the description as a string + * `descriptions`: the description strings */}} -{{ $content_type := .content_type }} -{{ $description := .description}} +{{ $content_types := .content_types }} +{{ $descriptions := .descriptions}} -{{ if $content_type }} +{{ if (gt (len $content_types) 0) }} + {{ range $idx, $content_type := $content_types }} - + + {{ end }}
Content-Type Description
{{ $content_type }}{{ $description | markdownify -}}{{ index $descriptions $idx | markdownify -}}
{{ end }} diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html index 5ef55c64..f41e062d 100644 --- a/layouts/partials/openapi/render-request.html +++ b/layouts/partials/openapi/render-request.html @@ -53,12 +53,13 @@ {{/* Show the content types and description. */}} - {{ $mimes := slice }} + {{ $mimes := slice }} + {{ $descriptions := slice }} {{ range $mime, $body := $request_body.content }} {{ $mimes = $mimes | append $mime }} + {{ $descriptions = $descriptions | append $request_body.description }} {{ end }} - {{ $content_type := delimit $mimes "|"}} - {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }} + {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} {{ end }}

Request body example

diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html index 82c2f954..dba7fa8b 100644 --- a/layouts/partials/openapi/render-responses.html +++ b/layouts/partials/openapi/render-responses.html @@ -109,13 +109,12 @@ Show the content types and description. */}} {{ $mimes := slice }} - {{ $desc := "" }} + {{ $descriptions := slice }} {{ range $mime, $body := $response.content }} {{ $mimes = $mimes | append $mime }} - {{ $desc = $body.schema.description }} + {{ $descriptions = $descriptions | append $body.schema.description }} {{ end }} - {{ $content_type := delimit $mimes "|"}} - {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }} + {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }} {{ end }} {{ end }} {{ end }}