mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-23 11:34:09 +01:00
Merge remote-tracking branch 'origin/main' into travis/animation-msc2705
This commit is contained in:
Travis Ralston
commit
8961db8c2d
4
.github/workflows/main.yml
vendored
4
.github/workflows/main.yml
vendored
|
|
@ -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
|
||||
|
|
|
|||
3
.github/workflows/release.yaml
vendored
3
.github/workflows/release.yaml
vendored
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
@ -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.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that read-receipts should be batched by thread as well as room.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that threads can be created based on replies.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Make clearer in the example for reply fallbacks that the prefix sequence should be repeated for each line.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the format of account data objects for secret storage.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that the key backup MAC is implemented incorrectly and does not pass the ciphertext through HMAC-SHA-256.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify one-time key and fallback key types in examples.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how to perform the ECDH exchange in step 12 of the SAS process.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Allow `/versions` to optionally accept authentication, as per [MSC4026](https://github.com/matrix-org/matrix-spec-proposals/pull/4026).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add local erasure requests, as per [MSC4025](https://github.com/matrix-org/matrix-spec-proposals/pull/4025).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Use the `body` field as media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Document the deprecation policy of HTML tags, as per [MSC4077](https://github.com/matrix-org/matrix-spec-proposals/pull/4077).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the format of account data objects for secret storage.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add support for multi-stream VoIP, as per [MSC3077](https://github.com/matrix-org/matrix-spec-proposals/pull/3077).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify that `sdpMid` and `sdpMLineIndex` are not required in `m.call.candidates`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add support for recursion on the /relations endpoints (MSC3981).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -0,0 +1 @@
|
|||
Add support for muting in VoIP calls, as per [MSC3291](https://github.com/matrix-org/matrix-spec-proposals/pull/3291).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update the spec release process.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Minor clarifications to the contributing guide.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update Docsy to v0.8.0.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add some clarifications around implementation requirements for MSCs
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update HTML templates to include links to object schema definitions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Factor out all the common parameters of the various `/relations` apis.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Add support for `$ref` URIs containing fragments in OpenAPI definitions and JSON schemas.
|
||||
1
changelogs/internal/newsfragments/1769.clarification
Normal file
1
changelogs/internal/newsfragments/1769.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Formatting fixes in CONTRIBUTING.rst.
|
||||
|
|
@ -1 +0,0 @@
|
|||
For room versions 7 through 11: Clarify that `invite->knock` is not a legal transition.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify Server-Server API request signing example by using the `POST` HTTP method, as `GET` requests don't have request bodies.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Disambiguate uses of `PublicRoomsChunk` in the `GET /hierarchy` endpoint.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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]
|
||||
|
|
|
|||
102
content/changelog/v1.10.md
Normal file
102
content/changelog/v1.10.md
Normal file
|
|
@ -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))
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)) |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
135
data/api/client-server/support.yaml
Normal file
135
data/api/client-server/support.yaml
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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) }}
|
||||
|
||||
<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 }}
|
||||
|
|
|
|||
|
|
@ -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 }}
|
||||
|
||||
<h3>Request body example</h3>
|
||||
|
|
|
|||
|
|
@ -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 }}
|
||||
|
|
|
|||
Loading…
Reference in a new issue