Merge remote-tracking branch 'origin/main' into travis/animation-msc2705

.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

.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
 

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 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_,
-`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md`_, and many other
+`Docker <https://github.com/docker/docker/blob/master/CONTRIBUTING.md>`_, and many other
 projects: the `Developer Certificate of Origin <http://developercertificate.org/>`_
 (DCO). This is a simple declaration that you wrote
 the contribution or otherwise have the right to contribute it to Matrix::

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;

changelogs/application_service/newsfragments/1744.clarification

@@ -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`.

changelogs/client_server/newsfragments/1629.clarification

@@ -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.

changelogs/client_server/newsfragments/1685.clarification

@@ -1 +0,0 @@
-Clarify that read-receipts should be batched by thread as well as room.

changelogs/client_server/newsfragments/1687.clarification

@@ -1 +0,0 @@
-Clarify that threads can be created based on replies.

changelogs/client_server/newsfragments/1690.clarification

@@ -1 +0,0 @@
-Make clearer in the example for reply fallbacks that the prefix sequence should be repeated for each line.

changelogs/client_server/newsfragments/1695.clarification

@@ -1 +0,0 @@
-Clarify the format of account data objects for secret storage.

changelogs/client_server/newsfragments/1712.clarification

@@ -1 +0,0 @@
-Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256.

changelogs/client_server/newsfragments/1715.clarification

@@ -1 +0,0 @@
-Clarify one-time key and fallback key types in examples.

changelogs/client_server/newsfragments/1719.clarification

@@ -1 +0,0 @@
-Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes.

changelogs/client_server/newsfragments/1720.clarification

@@ -1 +0,0 @@
-Clarify how to perform the ECDH exchange in step 12 of the SAS process.

changelogs/client_server/newsfragments/1728.feature

@@ -1 +0,0 @@
-Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026).

changelogs/client_server/newsfragments/1730.feature

@@ -1 +0,0 @@
-Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025).

changelogs/client_server/newsfragments/1731.feature

@@ -1 +0,0 @@
-Use the `body` field as media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530).

changelogs/client_server/newsfragments/1732.clarification

@@ -1 +0,0 @@
-Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077).

changelogs/client_server/newsfragments/1734.clarification

@@ -1 +0,0 @@
-Clarify the format of account data objects for secret storage.

changelogs/client_server/newsfragments/1735.feature

@@ -1 +0,0 @@
-Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077).

changelogs/client_server/newsfragments/1740.clarification

@@ -1 +0,0 @@
-Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.

changelogs/client_server/newsfragments/1742.clarification

@@ -1 +0,0 @@
-Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`.

changelogs/client_server/newsfragments/1746.feature

@@ -1 +0,0 @@
-Add support for recursion on the /relations endpoints (MSC3981).

changelogs/client_server/newsfragments/1748.clarification

@@ -1 +0,0 @@
-Fix various typos throughout the specification.

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).

changelogs/internal/newsfragments/1680.clarification

@@ -1 +0,0 @@
-Update the spec release process.

changelogs/internal/newsfragments/1697.clarification

@@ -1 +0,0 @@
-Minor clarifications to the contributing guide.

changelogs/internal/newsfragments/1699.clarification

@@ -1 +0,0 @@
-Update Docsy to v0.8.0.

changelogs/internal/newsfragments/1718.clarification

@@ -1 +0,0 @@
-Add some clarifications around implementation requirements for MSCs

changelogs/internal/newsfragments/1724.clarification

@@ -1 +0,0 @@
-Update HTML templates to include links to object schema definitions.

changelogs/internal/newsfragments/1745.clarification

@@ -1 +0,0 @@
-Factor out all the common parameters of the various `/relations` apis.

changelogs/internal/newsfragments/1751.clarification

@@ -1 +0,0 @@
-Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.

changelogs/internal/newsfragments/1754.clarification

@@ -1 +0,0 @@
-Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.

changelogs/internal/newsfragments/1769.clarification

@@ -0,0 +1 @@
+Formatting fixes in CONTRIBUTING.rst.

changelogs/room_versions/newsfragments/1717.clarification

@@ -1 +0,0 @@
-For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition.

changelogs/server_server/newsfragments/1721.clarification

@@ -1 +0,0 @@
-Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies.

changelogs/server_server/newsfragments/1740.clarification

@@ -1 +0,0 @@
-Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.

changelogs/server_server/newsfragments/1741.clarification

@@ -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.

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"
+# minor = "10"
-# release_date = "November 29, 2023"
+# release_date = "March 22, 2024"
 
 # User interface configuration
 [params.ui]

content/changelog/v1.10.md

@@ -0,0 +1,102 @@
+---
+date: 2024-03-22T09:59:45-06:00
+---
+<!--
+This is a header file for the generated changelog.
+
+Variables:
+    v1.10  = Replaced by the version number (eg: v1.2)
+    March 22, 2024     = Replaced by the date (eg: April 01, 2021)
+-->
+
+## v1.10
+
+<table class="release-info">
+<tr><th>Git commit</th><td><a href="https://github.com/matrix-org/matrix-spec/tree/v1.10">https://github.com/matrix-org/matrix-spec/tree/v1.10</a></td>
+<tr><th>Release date</th><td>March 22, 2024</td>
+</table>
+
+<!-- Intentionally blank line to ensure headers work in the concatenated changelog -->
+
+### 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))

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

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
+Servers MUST reject setting account data for event types
-that the server manages. Currently, this only includes
+that the server manages by using a 405 error response.
-[m.fully\_read](#mfully_read).
+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.

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`,
+`del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`, `a`, `ul`,
-`a`, `ul`, `ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`,
+`ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`, `s`, `code`,
-`s`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`,
+`hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`, `th`, `td`,
-`th`, `td`, `caption`, `pre`, `span`, `img`, `details`, `summary`.
+`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))                      |

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, 
+Clients are recommended to not mute the audio of WebRTC tracks locally when an
-to metadata about that stream. Currently only one property is defined for the
+incoming stream has the `audio_muted` field set to `true`. This is because when
-metadata. This is `purpose`, which should be a string indicating the purpose of
+the other user unmutes themselves, there may be a slight delay between their
-the stream. The following `purpose`s are defined:
+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
+The same suggestion does not apply to `video_muted`. Clients _should_ mute video
-*  `m.screenshare` - stream with the screen-sharing tracks
+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

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

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
+        }
+    }
+  }
+}

data/event-schemas/schema/components/sdp_stream_metadata.yaml

@@ -13,8 +13,8 @@ additionalProperties:
     purpose:
       type: string
       enum:
-        - m.usermedia
+      - m.usermedia
-        - m.screenshare
+      - 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

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

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 }}
+{{ $content_types := .content_types }}
-{{ $description := .description}}
+{{ $descriptions := .descriptions}}
 
-{{ if $content_type }}
+{{ if (gt (len $content_types) 0) }}
 
 <table class="content-type-table">
  <thead>
   <th class="col-name">Content-Type</th>
   <th class="col-description">Description</th>
  </thead>
+ {{ range $idx, $content_type := $content_types }}
  <tr>
   <td><code>{{ $content_type }}</code></td>
-  <td>{{ $description | markdownify -}}</td>
+  <td>{{ index $descriptions $idx | markdownify -}}</td>
  </tr>
+ {{ end }}
 </table>
 
 {{ end }}

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_types" $mimes "descriptions" $descriptions) }}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }}
         {{ end }}
 
 <h3>Request body example</h3>

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_types" $mimes "descriptions" $descriptions) }}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }}
         {{ end }}
     {{ end }}
 {{ end }}