diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md new file mode 100644 index 00000000..83701f14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/release.md @@ -0,0 +1,34 @@ +--- +name: [SCT] Release checklist +about: Used by the Spec Core Team to create a new release. +title: 'Matrix 1.X' +labels: 'release-blocker' +assignees: '' + +--- + + + + + +Date: **Thursday, May 25, 2023** +Previous release: + +Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): + +* [ ] Blog post written +* [ ] Check for release blockers that may have been missed +* [ ] Review/fix the changelog + +Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)): +* [ ] Branch stuffs +* [ ] Github release artifact +* [ ] Published to spec.matrix.org +* [ ] All links work +* [ ] Publish blog post +* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted +* [ ] Post to Twitter/Mastodon +* [ ] Close this issue + +Known release blockers: +* [ ] diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification deleted file mode 100644 index 6f8ab86f..00000000 --- a/changelogs/appendices/newsfragments/1468.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that the term "Canonical JSON" is a specific thing within the matrix specification. diff --git a/changelogs/appendices/newsfragments/1483.clarification b/changelogs/appendices/newsfragments/1483.clarification deleted file mode 100644 index 4c2042e3..00000000 --- a/changelogs/appendices/newsfragments/1483.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove references to groups diff --git a/changelogs/appendices/newsfragments/1484.clarification b/changelogs/appendices/newsfragments/1484.clarification deleted file mode 100644 index b29c7ad3..00000000 --- a/changelogs/appendices/newsfragments/1484.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarifications of event ID formats in early room versions diff --git a/changelogs/application_service/newsfragments/1447.clarification b/changelogs/application_service/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/application_service/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1424.clarification b/changelogs/client_server/newsfragments/1424.clarification deleted file mode 100644 index 758d455f..00000000 --- a/changelogs/client_server/newsfragments/1424.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the sections of the specification concerning aggregation of child events. diff --git a/changelogs/client_server/newsfragments/1432.clarification b/changelogs/client_server/newsfragments/1432.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1432.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1439.clarification b/changelogs/client_server/newsfragments/1439.clarification deleted file mode 100644 index ed05216d..00000000 --- a/changelogs/client_server/newsfragments/1439.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that reply chain fallback for threads may not be present. diff --git a/changelogs/client_server/newsfragments/1440.feature b/changelogs/client_server/newsfragments/1440.feature deleted file mode 100644 index 119ab2d6..00000000 --- a/changelogs/client_server/newsfragments/1440.feature +++ /dev/null @@ -1 +0,0 @@ -Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). diff --git a/changelogs/client_server/newsfragments/1441.clarification b/changelogs/client_server/newsfragments/1441.clarification deleted file mode 100644 index f03519b8..00000000 --- a/changelogs/client_server/newsfragments/1441.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify what event property the content-specific push rules match against. diff --git a/changelogs/client_server/newsfragments/1442.clarification b/changelogs/client_server/newsfragments/1442.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1442.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1447.clarification b/changelogs/client_server/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1449.clarification b/changelogs/client_server/newsfragments/1449.clarification deleted file mode 100644 index 1c105229..00000000 --- a/changelogs/client_server/newsfragments/1449.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify the semantics that make requests idempotent. diff --git a/changelogs/client_server/newsfragments/1455.clarification b/changelogs/client_server/newsfragments/1455.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/client_server/newsfragments/1455.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/client_server/newsfragments/1457.clarification b/changelogs/client_server/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/client_server/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/client_server/newsfragments/1461.clarification b/changelogs/client_server/newsfragments/1461.clarification deleted file mode 100644 index c205f380..00000000 --- a/changelogs/client_server/newsfragments/1461.clarification +++ /dev/null @@ -1 +0,0 @@ -Improve documentation of how clients use push rules. diff --git a/changelogs/client_server/newsfragments/1463.clarification b/changelogs/client_server/newsfragments/1463.clarification deleted file mode 100644 index 1cf431ee..00000000 --- a/changelogs/client_server/newsfragments/1463.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that servers should enforce a default `limit` on a filter if one is not specified. diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification deleted file mode 100644 index f5bd822e..00000000 --- a/changelogs/client_server/newsfragments/1464.clarification +++ /dev/null @@ -1 +0,0 @@ -Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature deleted file mode 100644 index 7c1c01ec..00000000 --- a/changelogs/client_server/newsfragments/1464.feature +++ /dev/null @@ -1 +0,0 @@ -Add new push rule conditions: `event_property_is` and `event_property_contains` from [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). diff --git a/changelogs/client_server/newsfragments/1465.clarifications b/changelogs/client_server/newsfragments/1465.clarifications deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1465.clarifications +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1474.clarification b/changelogs/client_server/newsfragments/1474.clarification deleted file mode 100644 index 9b874821..00000000 --- a/changelogs/client_server/newsfragments/1474.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1475.feature b/changelogs/client_server/newsfragments/1475.feature deleted file mode 100644 index a59c2177..00000000 --- a/changelogs/client_server/newsfragments/1475.feature +++ /dev/null @@ -1 +0,0 @@ -Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). diff --git a/changelogs/client_server/newsfragments/1479.clarification b/changelogs/client_server/newsfragments/1479.clarification deleted file mode 100644 index f1c4b178..00000000 --- a/changelogs/client_server/newsfragments/1479.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. diff --git a/changelogs/client_server/newsfragments/1485.clarification b/changelogs/client_server/newsfragments/1485.clarification deleted file mode 100644 index 99e5fc79..00000000 --- a/changelogs/client_server/newsfragments/1485.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove fictitious `token` parameter on `/keys/query` endpoint diff --git a/changelogs/client_server/newsfragments/1487.clarification b/changelogs/client_server/newsfragments/1487.clarification deleted file mode 100644 index 44494576..00000000 --- a/changelogs/client_server/newsfragments/1487.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix rendering of properties with a list of types diff --git a/changelogs/client_server/newsfragments/1495.clarification b/changelogs/client_server/newsfragments/1495.clarification deleted file mode 100644 index 8132e060..00000000 --- a/changelogs/client_server/newsfragments/1495.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify parts of the end-to-end encryption sections. diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature deleted file mode 100644 index efd70374..00000000 --- a/changelogs/client_server/newsfragments/1499.feature +++ /dev/null @@ -1,2 +0,0 @@ -Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). - diff --git a/changelogs/client_server/newsfragments/1500.clarification b/changelogs/client_server/newsfragments/1500.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1500.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1501.clarification b/changelogs/client_server/newsfragments/1501.clarification deleted file mode 100644 index 97fa837c..00000000 --- a/changelogs/client_server/newsfragments/1501.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove the `dont_notify` and `coalesce` push rule actions per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). diff --git a/changelogs/client_server/newsfragments/1507.clarification b/changelogs/client_server/newsfragments/1507.clarification deleted file mode 100644 index c810cc8c..00000000 --- a/changelogs/client_server/newsfragments/1507.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. diff --git a/changelogs/client_server/newsfragments/1509.clarification b/changelogs/client_server/newsfragments/1509.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1509.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1510.feature b/changelogs/client_server/newsfragments/1510.feature deleted file mode 100644 index efd70374..00000000 --- a/changelogs/client_server/newsfragments/1510.feature +++ /dev/null @@ -1,2 +0,0 @@ -Add new endpoints `POST /_matrix/media/v1/create` and `PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`, and other changes for asynchronous media upload, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). - diff --git a/changelogs/identity_service/newsfragments/1457.clarification b/changelogs/identity_service/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/identity_service/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/identity_service/newsfragments/1486.clarification b/changelogs/identity_service/newsfragments/1486.clarification deleted file mode 100644 index c7372cc4..00000000 --- a/changelogs/identity_service/newsfragments/1486.clarification +++ /dev/null @@ -1 +0,0 @@ -Corrections to the response format of `/_matrix/identity/v2/store-invite`. diff --git a/changelogs/internal/newsfragments/1444.clarification b/changelogs/internal/newsfragments/1444.clarification deleted file mode 100644 index 1bbaa905..00000000 --- a/changelogs/internal/newsfragments/1444.clarification +++ /dev/null @@ -1 +0,0 @@ -Update references to Inter font. diff --git a/changelogs/internal/newsfragments/1446.clarification b/changelogs/internal/newsfragments/1446.clarification deleted file mode 100644 index fdc3d1fc..00000000 --- a/changelogs/internal/newsfragments/1446.clarification +++ /dev/null @@ -1 +0,0 @@ -Endpoint disclosures now hide everything but the URL. diff --git a/changelogs/internal/newsfragments/1476.clarification b/changelogs/internal/newsfragments/1476.clarification deleted file mode 100644 index 340826b1..00000000 --- a/changelogs/internal/newsfragments/1476.clarification +++ /dev/null @@ -1 +0,0 @@ -Minor cleanups to the GitHub Actions workflows diff --git a/changelogs/internal/newsfragments/1488.clarification b/changelogs/internal/newsfragments/1488.clarification deleted file mode 100644 index d54557d9..00000000 --- a/changelogs/internal/newsfragments/1488.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix generation of anchors for additional properties diff --git a/changelogs/internal/newsfragments/1542.clarification b/changelogs/internal/newsfragments/1542.clarification new file mode 100644 index 00000000..422a4eef --- /dev/null +++ b/changelogs/internal/newsfragments/1542.clarification @@ -0,0 +1 @@ +Update the CI to validate the file extension of changelog entries. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1549.clarification b/changelogs/internal/newsfragments/1549.clarification new file mode 100644 index 00000000..67dbd67e --- /dev/null +++ b/changelogs/internal/newsfragments/1549.clarification @@ -0,0 +1 @@ +Disclosure sections now only display their title when collapsed. diff --git a/changelogs/room_versions/newsfragments/1484.clarification b/changelogs/room_versions/newsfragments/1484.clarification deleted file mode 100644 index b29c7ad3..00000000 --- a/changelogs/room_versions/newsfragments/1484.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarifications of event ID formats in early room versions diff --git a/changelogs/server_server/newsfragments/1431.clarification b/changelogs/server_server/newsfragments/1431.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/server_server/newsfragments/1431.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/server_server/newsfragments/1447.clarification b/changelogs/server_server/newsfragments/1447.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1447.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1454.clarification b/changelogs/server_server/newsfragments/1454.clarification deleted file mode 100644 index 6d68b88a..00000000 --- a/changelogs/server_server/newsfragments/1454.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`. diff --git a/changelogs/server_server/newsfragments/1457.clarification b/changelogs/server_server/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/server_server/newsfragments/1457.clarification +++ /dev/null @@ -1 +0,0 @@ -Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. diff --git a/changelogs/server_server/newsfragments/1466.clarification b/changelogs/server_server/newsfragments/1466.clarification deleted file mode 100644 index 3ccb2333..00000000 --- a/changelogs/server_server/newsfragments/1466.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. diff --git a/changelogs/server_server/newsfragments/1473.clarification b/changelogs/server_server/newsfragments/1473.clarification deleted file mode 100644 index c5cfb948..00000000 --- a/changelogs/server_server/newsfragments/1473.clarification +++ /dev/null @@ -1 +0,0 @@ -* Remove leftover `{key_id}` from `/_matrix/key/v2/server/` diff --git a/changelogs/server_server/newsfragments/1521.clarification b/changelogs/server_server/newsfragments/1521.clarification new file mode 100644 index 00000000..6c1ebf9d --- /dev/null +++ b/changelogs/server_server/newsfragments/1521.clarification @@ -0,0 +1 @@ +Document why `/state_ids` can respond with a 404. diff --git a/config.toml b/config.toml index d1749268..00757bd5 100644 --- a/config.toml +++ b/config.toml @@ -53,8 +53,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 = "6" -# release_date = "February 14, 2023" +# minor = "7" +# release_date = "May 25, 2023" # User interface configuration [params.ui] diff --git a/content/_index.md b/content/_index.md index 6396e4a3..69832f2e 100644 --- a/content/_index.md +++ b/content/_index.md @@ -357,8 +357,8 @@ servers that are in the room that can be used to join via. HTTP GET #matrix:example.org !aaabaa:matrix.org - | ^ - | | + | ^ + | | _______V____________________|____ | example.org | | Mappings: | diff --git a/content/application-service-api.md b/content/application-service-api.md index 7a14869a..f3db06cf 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -207,6 +207,54 @@ processed the events. {{% http-api spec="application-service" api="transactions" %}} +#### Pinging + +{{% added-in v="1.7" %}} + +The application service API includes a ping mechanism to allow +appservices to ensure that the homeserver can reach the appservice. +Appservices may use this mechanism to detect misconfigurations and +report them appropriately. + +Implementations using this mechanism should take care to not fail +entirely in the event of temporary issues, e.g. gracefully handling +cases where the appservice is started before the homeserver. + +The mechanism works as follows (note: the human-readable `error` fields +have been omitted for brevity): + +**Typical** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} + HS <--- AS : 200 OK {} +AS <--- HS : 200 OK {"duration_ms": 123} +``` + +**Incorrect `hs_token`** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} + HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"} +AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body": "{\"errcode\": \"M_FORBIDDEN\"}"} +``` + +**Can't connect to appservice** + +``` +AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"} + HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"} +AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"} +``` + +The `/_matrix/app/v1/ping` endpoint is described here. The +[`/_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping) +endpoint is under the Client-Server API extensions section below. + +{{% http-api spec="application-service" api="ping" %}} + #### Querying The application service API includes two querying APIs: for room aliases @@ -388,6 +436,15 @@ an application service-defined namespace will receive the same `M_EXCLUSIVE` error code, but only if the application service has defined the namespace as `exclusive`. +#### Pinging + +{{% added-in v="1.7" %}} + +This is the client-server API companion endpoint for the +[pinging](#pinging) mechanism described above. + +{{% http-api spec="client-server" api="appservice_ping" %}} + #### Using `/sync` and `/events` Application services wishing to use `/sync` or `/events` from the diff --git a/content/changelog/v1.7.md b/content/changelog/v1.7.md new file mode 100644 index 00000000..61ade090 --- /dev/null +++ b/content/changelog/v1.7.md @@ -0,0 +1,147 @@ +--- +date: 2023-05-25T09:47:21-06:00 +--- + + +## v1.7 + + + + +
Git commithttps://github.com/matrix-org/matrix-spec/tree/v1.7
Release dateMay 25, 2023
+ + +### Client-Server API + + +New Endpoints + + +- [`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499)) +- [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499)) +- [`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530)) + + +Backwards Compatible Changes + + +- Changes to the server-side aggregation of `m.replace` (edit) events, as per [MSC3925](https://github.com/matrix-org/matrix-spec-proposals/pull/3925). ([#1440](https://github.com/matrix-org/matrix-spec/issues/1440), [#1525](https://github.com/matrix-org/matrix-spec/issues/1525)) +- Add new push rule conditions `event_property_is` and `event_property_contains`, as per [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464)) +- Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). ([#1475](https://github.com/matrix-org/matrix-spec/issues/1475), [#1531](https://github.com/matrix-org/matrix-spec/issues/1531)) +- Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). ([#1499](https://github.com/matrix-org/matrix-spec/issues/1499), [#1510](https://github.com/matrix-org/matrix-spec/issues/1510)) +- Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other notification behaviour, as per [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). ([#1508](https://github.com/matrix-org/matrix-spec/issues/1508)) +- Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). ([#1511](https://github.com/matrix-org/matrix-spec/issues/1511), [#1540](https://github.com/matrix-org/matrix-spec/issues/1540)) +- Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). ([#1526](https://github.com/matrix-org/matrix-spec/issues/1526)) +- Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). ([#1529](https://github.com/matrix-org/matrix-spec/issues/1529)) +- Add an ability to use an existing session to log in another, as per [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882). ([#1530](https://github.com/matrix-org/matrix-spec/issues/1530)) + + +Spec Clarifications + + +- Clarify the sections of the specification concerning aggregation of child events. ([#1424](https://github.com/matrix-org/matrix-spec/issues/1424)) +- Fix various typos throughout the specification. ([#1432](https://github.com/matrix-org/matrix-spec/issues/1432), [#1442](https://github.com/matrix-org/matrix-spec/issues/1442), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1455](https://github.com/matrix-org/matrix-spec/issues/1455), [#1465](https://github.com/matrix-org/matrix-spec/issues/1465), [#1500](https://github.com/matrix-org/matrix-spec/issues/1500), [#1509](https://github.com/matrix-org/matrix-spec/issues/1509)) +- Clarify that reply chain fallback for threads might not be present. ([#1439](https://github.com/matrix-org/matrix-spec/issues/1439)) +- Clarify what event property the content-specific push rules match against. ([#1441](https://github.com/matrix-org/matrix-spec/issues/1441)) +- Clarify the semantics that make requests idempotent. ([#1449](https://github.com/matrix-org/matrix-spec/issues/1449)) +- Improve documentation of how clients use push rules. ([#1461](https://github.com/matrix-org/matrix-spec/issues/1461)) +- Clarify that servers should enforce a default `limit` on a filter if one is not specified. ([#1463](https://github.com/matrix-org/matrix-spec/issues/1463)) +- Disambiguate using property names with dots in them during push rule processing, as per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980). ([#1464](https://github.com/matrix-org/matrix-spec/issues/1464)) +- Fix phrasing & typography in the registration endpoint description. Contributed by @HarHarLinks. ([#1474](https://github.com/matrix-org/matrix-spec/issues/1474)) +- Remove outdated text saying that `state_default` is 0 if there is no `m.room.power_levels` event in a room. ([#1479](https://github.com/matrix-org/matrix-spec/issues/1479)) +- Remove fictitious `token` parameter on `/keys/query` endpoint. ([#1485](https://github.com/matrix-org/matrix-spec/issues/1485)) +- Fix rendering of properties with a list of types. ([#1487](https://github.com/matrix-org/matrix-spec/issues/1487)) +- Clarify parts of the cross-signing signature upload request. ([#1495](https://github.com/matrix-org/matrix-spec/issues/1495)) +- Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). ([#1501](https://github.com/matrix-org/matrix-spec/issues/1501)) +- Clarify `m.location` scheme by partially reverting [f1f32d3](https://github.com/matrix-org/matrix-spec/commit/f1f32d3a15c325ee8aa9d2c6bafd96c38069bb53). Contributed by @HarHarLinks. ([#1507](https://github.com/matrix-org/matrix-spec/issues/1507)) +- Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. ([#1535](https://github.com/matrix-org/matrix-spec/issues/1535)) + + +### Server-Server API + + +Spec Clarifications + + +- Fix various typos throughout the specification. ([#1431](https://github.com/matrix-org/matrix-spec/issues/1431), [#1447](https://github.com/matrix-org/matrix-spec/issues/1447), [#1466](https://github.com/matrix-org/matrix-spec/issues/1466), [#1518](https://github.com/matrix-org/matrix-spec/issues/1518)) +- Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. ([#1454](https://github.com/matrix-org/matrix-spec/issues/1454)) +- Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. ([#1473](https://github.com/matrix-org/matrix-spec/issues/1473)) +- Remove extraneous `age_ts` field from the reference hash calculation section. ([#1536](https://github.com/matrix-org/matrix-spec/issues/1536)) + + +### Application Service API + + +New Endpoints + + +- [`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516)) +- [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516)) + + +Backwards Compatible Changes + + +- Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. ([#1516](https://github.com/matrix-org/matrix-spec/issues/1516), [#1541](https://github.com/matrix-org/matrix-spec/issues/1541)) + + +Spec Clarifications + + +- Fix various typos throughout the specification. ([#1447](https://github.com/matrix-org/matrix-spec/issues/1447)) + + +### Identity Service API + + +Spec Clarifications + + +- Corrections to the response format of `/_matrix/identity/v2/store-invite`. ([#1486](https://github.com/matrix-org/matrix-spec/issues/1486)) + + +### Push Gateway API + + +No significant changes. + + +### Room Versions + + +Spec Clarifications + + +- Clarifications of event ID formats in early room versions ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) + + +### Appendices + + +Spec Clarifications + + +- Clarify that the term "Canonical JSON" is a specific thing within the Matrix specification. ([#1468](https://github.com/matrix-org/matrix-spec/issues/1468)) +- Remove references to groups. ([#1483](https://github.com/matrix-org/matrix-spec/issues/1483)) +- Clarifications of event ID formats in early room versions. ([#1484](https://github.com/matrix-org/matrix-spec/issues/1484)) + + +### Internal Changes/Tooling + + +Spec Clarifications + + +- Update references to Inter font. ([#1444](https://github.com/matrix-org/matrix-spec/issues/1444)) +- Endpoint disclosures now hide everything but the URL. ([#1446](https://github.com/matrix-org/matrix-spec/issues/1446)) +- Wrap $ref in allOf where other attributes are present, to improve OpenAPI compliance. ([#1457](https://github.com/matrix-org/matrix-spec/issues/1457)) +- Minor cleanups to the GitHub Actions workflows ([#1476](https://github.com/matrix-org/matrix-spec/issues/1476)) +- Fix generation of anchors for additional properties. ([#1488](https://github.com/matrix-org/matrix-spec/issues/1488)) +- Fix various typos throughout the specification. ([#1534](https://github.com/matrix-org/matrix-spec/issues/1534)) +- Document more of the spec release timeline/process. ([#1538](https://github.com/matrix-org/matrix-spec/issues/1538)) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index cf00870b..8ebe8f71 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -237,19 +237,32 @@ For example, `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}` would return a `200 OK` with the `event_id` of the original request in the response body. -As well as the HTTP path, the scope of a transaction ID is a "client -session", where that session is identified by a particular access token. -When [refreshing](#refreshing-access-tokens) an access token, the -transaction ID's scope is retained. This means that if a client with -token `A` uses `TXN1` as their transaction ID, refreshes the token to -`B`, and uses `TXN1` again it'll be assumed to be a duplicate request -and ignored. If the client logs out and back in between the `A` and `B` -tokens, `TXN1` could be used once for each. +The scope of a transaction ID is for a single [device](../index.html#devices), +and a single HTTP endpoint. In other words: a single device could use the same +transaction ID for a request to [`PUT +/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`](#put_matrixclientv3roomsroomidsendeventtypetxnid) +and [`PUT +/_matrix/client/v3/sendToDevice/{eventType}/{txnId}`](#put_matrixclientv3sendtodeviceeventtypetxnid), +and the two requests would be considered distinct because the two are +considered separate endpoints. Similarly, if a client logs out and back in +between two requests using the same transaction ID, the requests are distinct +because the act of logging in and out creates a new device (unless an existing +`device_id` is passed to [`POST +/_matrix/client/v3/login`](#post_matrixclientv3login)). On the other hand, if a +client re-uses a transaction ID for the same endpoint after +[refreshing](#refreshing-access-tokens) an access token, it will be assumed to +be a duplicate request and ignored. See also +[Relationship between access tokens and devices](#relationship-between-access-tokens-and-devices). Some API endpoints may allow or require the use of `POST` requests without a transaction ID. Where this is optional, the use of a `PUT` request is strongly recommended. +{{% boxes/rationale %}} +Prior to `v1.7`, transaction IDs were scoped to "client sessions" rather than +devices. +{{% /boxes/rationale %}} + ## Web Browser Clients It is realistic to expect that some clients will be written to be run @@ -1163,8 +1176,14 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. +{{< added-in v="1.7" >}} Already-authenticated clients can additionally generate +a token for their user ID if supported by the homeserver using +[`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). + {{% http-api spec="client-server" api="login" %}} +{{% http-api spec="client-server" api="login_token" %}} + {{% http-api spec="client-server" api="refresh" %}} {{% http-api spec="client-server" api="logout" %}} @@ -2671,4 +2690,3 @@ systems. {{< cs-module name="event_annotations" >}} {{< cs-module name="threading" >}} {{< cs-module name="reference_relations" >}} - diff --git a/content/client-server-api/modules/event_annotations.md b/content/client-server-api/modules/event_annotations.md index 8aeff40f..661d8001 100644 --- a/content/client-server-api/modules/event_annotations.md +++ b/content/client-server-api/modules/event_annotations.md @@ -71,6 +71,12 @@ change their reaction, the original reaction should be redacted and a new one sent in its place. {{% /boxes/note %}} +{{% boxes/note %}} +The `key` field in `m.reaction` can be any string so clients must take care to +render long reactions in a sensible manner. For example, clients can elide +overly-long reactions. +{{% /boxes/note %}} + #### Server behaviour ##### Avoiding duplicate annotations diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 6767b73f..9afe304e 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -249,14 +249,14 @@ events](#redactions-of-edited-events) below. **Note:** the `content` of the original event is left intact. In particular servers should **not** replace the content with that of the replacement event. -{{ boxes/rationale }} +{{% boxes/rationale %}} In previous versions of the specification, servers were expected to replace the content of an edited event whenever it was served to clients (with the exception of the [`GET /_matrix/client/v3/rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid) endpoint). However, that behaviour made reliable client-side implementation difficult, and servers should no longer make this replacement. -{{ /boxes/rationale }} +{{% /boxes/rationale %}} #### Client behaviour @@ -293,6 +293,73 @@ events will not be included in the aggregation bundled with the original event. Note that the subsequent edits are not actually redacted themselves: they simply serve no purpose within the visible timeline. +#### Edits of events with mentions + +When editing an event with [user and room mentions](#user-and-room-mentions) the +replacement event will have two `m.mentions` properties: + +* One at the top-level of the `content`, which should contain mentions due to + this edit revision. +* One inside the `m.new_content` property, which should contain the resolved mentions + for the final version of the event. + +The difference between these properties ensures that users will not be notified +for each edit revision of an event, but allows for new users to be mentioned (or +for re-notifying if the sending client feels a large enough revision was made). + +For example, if there is an event mentioning Alice: + +```json5 +{ + "event_id": "$original_event", + "type": "m.room.message", + "content": { + "body": "Hello Alice!", + "m.mentions": { + "user_ids": ["@alice:example.org"] + } + } +} +``` + +And an edit to also mention Bob: + +```json5 +{ + "content": { + "body": "* Hello Alice & Bob!", + "m.mentions": { + "user_ids": [ + // Include only the newly mentioned user. + "@bob:example.org" + ] + }, + "m.new_content": { + "body": "Hello Alice & Bob!", + "m.mentions": { + "user_ids": [ + // Include all of the mentioned users. + "@alice:example.org", + "@bob:example.org" + ] + }, + }, + "m.relates_to": { + "rel_type": "m.replace", + "event_id": "$original_event" + } + }, + // other fields as required by events +} +``` + +If an edit revision removes a user's mention then that user's Matrix ID should be +included in neither `m.mentions` property. + +Clients may also wish to modify the [client behaviour](#user-and-room-mentions) of +determining if an event mentions the current user by checking the `m.mentions` +property under `m.new_content`. + #### Edits of replies Some particular constraints apply to events which replace a diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md index fe51208c..32309740 100644 --- a/content/client-server-api/modules/mentions.md +++ b/content/client-server-api/modules/mentions.md @@ -1,61 +1,76 @@ ### User and room mentions -This module allows users to mention other users and rooms within a room message. -This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of -an [m.room.message](#mroommessage) event. This module does not have any server-specific -behaviour to it. +{{% changed-in v="1.7" %}} -Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is -`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be -`org.matrix.custom.html` and therefore requires a `formatted_body`. +This module allows users to "mention" other users and rooms within a room event. +This is primarily used as an indicator that the recipient should receive a notification +about the event. +This is achieved by including metadata in the `m.mentions` content property of +the event to reference the entity being mentioned. -To make a mention, reference the entity being mentioned in the -`formatted_body` using an anchor, like so: +`m.mentions` is defined as follows: -```json -{ - "body": "Hello Alice!", - "msgtype": "m.text", - "format": "org.matrix.custom.html", - "formatted_body": "Hello Alice!" -} -``` +{{% definition path="api/client-server/definitions/m.mentions" %}} + +Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and +[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules. +Users should not add their own Matrix ID to the `m.mentions` property as outgoing +messages cannot self-notify. + +{{% boxes/warning %}} +If an encrypted event contains an `m.mentions` in its payload, it should be +encrypted as normal. To properly process mentions in encrypted rooms, events +must be decrypted first. See [receiving notifications](#receiving-notifications). +{{% /boxes/warning %}} + +Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name), +[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and +[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of +the event contains the user's display name or ID. To avoid unintentional notifications, +**it is recommended that clients include a `m.mentions` property on each event**. +(If there are no mentions to include it can be an empty object.) + +{{% boxes/rationale %}} +In previous versions of the specification, mentioning users was done by +including the user's display name or the localpart of their Matrix ID and room +mentions were done by including the string "@room" in the plaintext `body` of +the event. This was prone to confusing and buggy behaviour. +{{% /boxes/rationale %}} #### Client behaviour -In addition to using the appropriate `Matrix URI` for the mention, -clients should use the following guidelines when making mentions in -events to be sent: +Although it is possible to silently mention users, it is recommended to include a +[Matrix URI](/appendices/#uris) in the HTML body of an [m.room.message](#mroommessage) +event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is +`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be +`org.matrix.custom.html` and therefore requires a `formatted_body`. -- When mentioning users, use the user's potentially ambiguous display +Clients should use the following guidelines when adding a `Matrix URI` +representing a mention to events to be sent: + +- When linking to users, use the user's potentially ambiguous display name for the anchor's text. If the user does not have a display name, use the user's ID. -- When mentioning rooms, use the canonical alias for the room. If the +- When linking to rooms, use the canonical alias for the room. If the room does not have a canonical alias, prefer one of the aliases listed on the room. If no alias can be found, fall back to the room ID. In all cases, use the alias/room ID being linked to as the anchor's text. The text component of the anchor should be used in the event's `body` -where the mention would normally be represented, as shown in the example +where the link would normally be represented, as shown in the example above. Clients should display mentions differently from other elements. For example, this may be done by changing the background color of the mention to indicate that it is different from a normal link. -If the current user is mentioned in a message (either by a mention as -defined in this module or by a push rule), the client should show that +If the current user is mentioned in a message, the client should show that mention differently from other mentions, such as by using a red -background color to signify to the user that they were mentioned. +background color to signify to the user that they were mentioned. Note that +it is possible for a user to be mentioned without including their `Matrix URI` +in the event. When clicked, the mention should navigate the user to the appropriate user or room information. - -{{% boxes/note %}} -Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation), -groups used to be representable by mentions. They follow a similar format -to room mentions, though using the group ID in both the link and anchor -text. -{{% /boxes/note %}} \ No newline at end of file diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md index 9a2a671f..d1855f58 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -521,7 +521,46 @@ Definition: } ``` -**`.m.rule.contains_display_name`** + **`.m.rule.is_user_mention`** + +{{< added-in v="1.7" >}} + +Matches any message which contains the user's Matrix ID in the list of `user_ids` +under the `m.mentions` property. + +Definition: + +```json +{ + "rule_id": ".m.rule.is_user_mention", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_property_contains", + "key": "content.m\\.mentions.user_ids", + "value": "[the user's Matrix ID]" + } + ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight" + } + ] +} +``` + + **`.m.rule.contains_display_name`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message whose content contains the user's current display name in the room in which it was sent. @@ -551,7 +590,46 @@ Definition: } ``` -**`.m.rule.roomnotif`** + **`.m.rule.is_room_mention`** + +{{< added-in v="1.7" >}} + +Matches any message from a sender with the proper power level with the `room` +property of the `m.mentions` property set to `true`. + +Definition: + +```json +{ + "rule_id": ".m.rule.is_room_mention", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_property_is", + "key": "content.m\\.mentions.room", + "value": true + }, + { + "kind": "sender_notification_permission", + "key": "room" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight" + } + ] +} +``` + + **`.m.rule.roomnotif`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message from a sender with the proper power level whose content contains the text `@room`, signifying the whole room should be notified of @@ -622,7 +700,7 @@ Definition: {{% added-in v="1.7" %}} -Matches any event whose type is `m.room.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events. +Matches any event whose type is `m.reaction`. This suppresses notifications for [`m.reaction`](#mreaction) events. Definition: @@ -674,7 +752,12 @@ Definition: ##### Default Content Rules -**`.m.rule.contains_user_name`** + **`.m.rule.contains_user_name`** + +{{% changed-in v="1.7" %}} + +As of `v1.7`, this rule is deprecated and **should only be enabled if the event +does not have an [`m.mentions` property](#definition-mmentions)**. Matches any message whose content contains the local part of the user's Matrix ID, separated by word boundaries. diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index 1b1af61a..8cd4e9f6 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -153,12 +153,6 @@ relationships and solid lines showing topological ordering. ![threaded-dag](/diagrams/threaded-dag.png) -{{% boxes/note %}} -`m.reaction` relationships are not currently specified, but are shown here for -their conceptual place in a threaded DAG. They are currently proposed as -[MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). -{{% /boxes/note %}} - This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread roots: diff --git a/content/client-server-api/modules/rich_replies.md b/content/client-server-api/modules/rich_replies.md index 5132c36e..a0018630 100644 --- a/content/client-server-api/modules/rich_replies.md +++ b/content/client-server-api/modules/rich_replies.md @@ -176,4 +176,34 @@ This is where the reply goes. For `m.image`, the text should be `"sent an image."`. For `m.video`, the text should be `"sent a video."`. For `m.audio`, the text should be -`"sent an audio file"`. \ No newline at end of file +`"sent an audio file"`. + +#### Mentioning the replied to user + +In order to notify users of the reply, it may be desirable to include the `sender` +of the replied to event and any users mentioned in that event. See +[user and room mentions](#user-and-room-mentions) for additional information. + +An example including mentioning the original sender and other users: + +```json5 +{ + "content": { + "m.relates_to": { + "m.in_reply_to": { + "event_id": "$another_event" + } + }, + "body": "That sounds like a great idea!", + "m.mentions": { + "user_ids": [ + // The sender of $another_event. + "@alice:example.org", + // Another Matrix ID copied from the m.mentions property of $another_event. + "@bob:example.org" + ] + } + }, + // other fields as required by events +} +``` diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 90471cae..102e3dcd 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -6,11 +6,128 @@ This module outlines how two users in a room can set up a Voice over IP WebRTC 1.0 standard. Call signalling is achieved by sending [message events](#events) to the room. In this version of the spec, only two-party communication is supported (e.g. between two peers, or between a peer -and a multi-point conferencing unit). This means that clients MUST only -send call events to rooms with exactly two participants. +and a multi-point conferencing unit). Calls can take place in rooms with +multiple members, but only two devices can take part in the call. + +All VoIP events have a `version` field. This is used to determine whether +devices support this new version of the protocol. For example, clients can use +this field to know whether to expect an `m.call.select_answer` event from their +opponent. If clients see events with `version` other than `0` or `"1"` +(including, for example, the numeric value `1`), they should treat these the +same as if they had `version` == `"1"`. + +Note that this implies any and all future versions of VoIP events should be +backwards-compatible. If it does become necessary to introduce a non +backwards-compatible VoIP spec, the intention would be for it to simply use a +separate set of event types. + +#### Party Identifiers +Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the +duration of the call. This needs to be long enough that the chance of a collision between multiple devices +both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase + +lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of +`(user_id, party_id)`. + +The client adds a `party_id` field containing this ID to the top-level of the content of all VoIP events +it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own +events: since a user may call themselves, they cannot simply ignore events from their own user. This +field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates` +events to their respective answer/invite. + +A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose, +or it may choose, for example, to use a different one for each call to avoid leaking information on which +devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to +send signalling for more than one call party. + +A grammar for `party_id` is defined [below](#grammar-for-voip-ids). + +#### Politeness +In line with [WebRTC perfect negotiation](https://w3c.github.io/webrtc-pc/#perfect-negotiation-example) +there are rules to establish which party is polite in the process of renegotiation. The callee is +always the polite party. In a glare situation, the politeness of a party is therefore determined by +whether the inbound or outbound call is used: if a client discards its outbound call in favour of +an inbound call, it becomes the polite party. + +#### Call Event Liveness +`m.call.invite` contains a `lifetime` field that indicates how long the offer is valid for. When +a client receives an invite, it should use the event's `age` field in the sync response plus the +time since it received the event from the homeserver to determine whether the invite is still valid. +The use of the `age` field ensures that incorrect clocks on client devices don't break calls. + +If the invite is still valid *and will remain valid for long enough for the user to accept the call*, +it should signal an incoming call. The amount of time allowed for the user to accept the call may +vary between clients. For example, it may be longer on a locked mobile device than on an unlocked +desktop device. + +The client should only signal an incoming call in a given room once it has completed processing the +entire sync response and, for encrypted rooms, attempted to decrypt all encrypted events in the +sync response for that room. This ensures that if the sync response contains subsequent events that +indicate the call has been hung up, rejected, or answered elsewhere, the client does not signal it. + +If on startup, after processing locally stored events, the client determines that there is an invite +that is still valid, it should still signal it but only after it has completed a sync from the homeserver. + +The minimal recommended lifetime is 90 seconds - this should give the user enough time to actually pick +up the call. + +#### ICE Candidate Batching +Clients should aim to send a small number of candidate events, with guidelines: + * ICE candidates which can be discovered immediately or almost immediately in the invite/answer + event itself (eg. host candidates). If server reflexive or relay candidates can be gathered in + a sufficiently short period of time, these should be sent here too. A delay of around 200ms is + suggested as a starting point. + * The client should then allow some time for further candidates to be gathered in order to batch them, + rather than sending each candidate as it arrives. A starting point of 2 seconds after sending the + invite or 500ms after sending the answer is suggested as a starting point (since a delay is natural + anyway after the invite whilst the client waits for the user to accept it). + +#### End-of-candidates +An ICE candidate whose value is the empty string means that no more ICE candidates will +be sent. Clients must send such a candidate in an `m.call.candidates` message. +The WebRTC spec requires browsers to generate such a candidate, however note that at time of writing, +not all browsers do (Chrome does not, but does generate an `icegatheringstatechange` event). The +client should send any remaining candidates once candidate generation finishes, ignoring timeouts above. +This allows bridges to batch the candidates together when bridging to protocols that don't support +trickle ICE. + +#### DTMF +Matrix clients can send DTMF as specified by WebRTC. The WebRTC standard as of August +2020 does not support receiving DTMF but a Matrix client can receive and interpret the DTMF sent +in the RTP payload. + +#### Grammar for VoIP IDs +`call_id`s and `party_id` are explicitly defined to be between 1 and 255 characters long, consisting +of the characters `[0-9a-zA-Z._~-]`. + +(Note that this matches the grammar of 'opaque IDs' from +[MSC1597](https://github.com/matrix-org/matrix-spec-proposals/blob/rav/proposals/id_grammar/proposals/1597-id-grammar.md#opaque-ids), +and that of the `id` property of the + [`m.login.sso` flow schema](#definition-mloginsso-flow-schema).) + +#### Behaviour on Room Leave +If the client sees the user it is in a call with leave the room, the client should treat this +as a hangup event for any calls that are in progress. No specific requirement is given for the +situation where a client has sent an invite and the invitee leaves the room, but the client may +wish to treat it as a rejection if there are no more users in the room who could answer the call +(eg. the user is now alone or the `invitee` field was set on the invite). + +The same behaviour applies when a client is looking at historic calls. + +#### Supported Codecs +The Matrix spec does not mandate particular audio or video codecs, but instead defers to the +WebRTC spec. A compliant Matrix VoIP client will behave in the same way as a supported 'browser' +in terms of what codecs it supports and what variants thereof. The latest WebRTC specification +applies, so clients should keep up to date with new versions of the WebRTC specification whether +or not there have been any changes to the Matrix spec. #### Events +##### Common Fields + +{{% event-fields event_type="call_event" %}} + +##### Events + {{% event-group group_name="m.call" %}} #### Client behaviour @@ -25,6 +142,7 @@ A call is set up with message events exchanged as follows: [..candidates..] --------> [Answers call] <--------------- m.call.answer + m.call.select_answer -----------> [Call is active and ongoing] <--------------- m.call.hangup ``` @@ -42,6 +160,43 @@ Or a rejected call: Calls are negotiated according to the WebRTC specification. +In response to an incoming invite, a client may do one of several things: + * Attempt to accept the call by sending an `m.call.answer`. + * Actively reject the call everywhere: send an `m.call.reject` as per above, which will stop the call from + ringing on all the user's devices and the caller's client will inform them that the user has + rejected their call. + * Ignore the call: send no events, but stop alerting the user about the call. The user's other + devices will continue to ring, and the caller's device will continue to indicate that the call + is ringing, and will time the call out in the normal way if no other device responds. + +##### Streams + +Clients are expected to send one stream with one track of kind `audio` (creating a +voice call). They can optionally send a second track in the same stream of kind +`video` (creating a video call). + +Clients implementing this specification use the first stream and will ignore +any streamless tracks. Note that in the JavaScript WebRTC API, this means +`addTrack()` must be passed two parameters: a track and a stream, not just a +track, and in a video call the stream must be the same for both audio and video +track. + +A client may send other streams and tracks but the behaviour of the other party +with respect to presenting such streams and tracks is undefined. + +##### Invitees +The `invitee` field should be added whenever the call is intended for one +specific user, and should be set to the Matrix user ID of that user. Invites +without an `invitee` field are defined to be intended for any member of the +room other than the sender of the event. + +Clients should consider an incoming call if they see a non-expired invite event where the `invitee` field is either +absent or equal to their user's Matrix ID, however they should evaluate whether or not to ring based on their +user's trust relationship with the callers and/or where the call was placed. As a starting point, it is +suggested that clients ignore call invites from users in public rooms. It is strongly recommended that +when clients do not ring for an incoming call invite, they still display the call invite in the room and +annotate that it was ignored. + ##### Glare "Glare" is a problem which occurs when two users call each other at diff --git a/content/server-server-api.md b/content/server-server-api.md index fabe7820..b8c78345 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -1270,7 +1270,7 @@ specification](/rooms) for more information. It is calculated as follows. 1. The event is put through the redaction algorithm. -2. The `signatures`, `age_ts`, and `unsigned` properties are removed +2. The `signatures` and `unsigned` properties are removed from the event, if present. 3. The event is converted into [Canonical JSON](/appendices#canonical-json). diff --git a/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml new file mode 100644 index 00000000..291f96fa --- /dev/null +++ b/data/api/application-service/ping.yaml @@ -0,0 +1,72 @@ +# Copyright 2023 Tulir Asokan +# +# 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 Application Service API + version: 1.0.0 +paths: + /ping: + post: + x-addedInMatrixVersion: "1.7" + summary: Ping the application service + description: |- + This API is called by the homeserver to ensure that the connection works + and the `hs_token` the homeserver has is correct. + + Currently this is only called by the homeserver as a direct result of + the application service calling + [`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](#post_matrixclientv1appserviceappserviceidping). + operationId: ping + security: + - homeserverAccessToken: [] + requestBody: + content: + application/json: + schema: + type: object + example: { + "transaction_id": "mautrix-go_1683636478256400935_123" + } + properties: + transaction_id: + type: string + description: |- + A transaction ID for the ping, copied directly from the + `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call. + description: Ping body with optional transaction ID. + responses: + "200": + description: The provided `hs_token` is valid and the ping request was successful. + content: + application/json: + schema: + type: object + examples: + response: + value: {} +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/app/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml new file mode 100644 index 00000000..7102659e --- /dev/null +++ b/data/api/client-server/appservice_ping.yaml @@ -0,0 +1,182 @@ +# Copyright 2023 Tulir Asokan +# +# 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 Application Service Ping API + version: 1.0.0 +paths: + "/appservice/{appserviceId}/ping": + post: + x-addedInMatrixVersion: "1.7" + summary: Ask the homeserver to ping the application service to ensure the + connection works. + description: |- + This API asks the homeserver to call the + [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the + application service to ensure that the homeserver can communicate + with the application service. + + This API requires the use of an application service access token (`as_token`) + instead of a typical client's access token. This API cannot be invoked by + users who are not identified as application services. Additionally, the + appservice ID in the path must be the same as the appservice whose `as_token` + is being used. + operationId: pingAppservice + parameters: + - in: path + name: appserviceId + description: |- + The appservice ID of the appservice to ping. This must be the same + as the appservice whose `as_token` is being used to authenticate the + request. + required: true + example: telegram + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + transaction_id: + type: string + description: An optional transaction ID that is passed through to the + `/_matrix/app/v1/ping` call. + example: mautrix-go_1683636478256400935_123 + required: true + security: + # again, this is the appservice's token - not a typical client's + - accessToken: [] + responses: + "200": + description: The ping was successful. + content: + application/json: + schema: + type: object + properties: + duration_ms: + type: integer + description: |- + The duration in milliseconds that the + [`/_matrix/app/v1/ping`](#post_matrixappv1ping) + request took from the homeserver's point of view. + required: + - duration_ms + examples: + response: + value: { + "duration_ms": 123 + } + "400": + description: The application service doesn't have a URL configured. The errcode + is `M_URL_NOT_SET`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_URL_NOT_SET", + "error": "Application service doesn't have a URL configured" + } + "403": + description: The access token used to authenticate the request doesn't belong to + an appservice, or belongs to a different appservice than the one in + the path. The errcode is `M_FORBIDDEN`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_FORBIDDEN", + "error": "Provided access token is not the appservice's as_token" + } + "502": + description: |- + The application service returned a bad status, or the connection failed. + The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`. + + For bad statuses, the response may include `status` and `body` + fields containing the HTTP status code and response body text + respectively to aid with debugging. + content: + application/json: + schema: + type: object + title: Error + description: A Matrix-level Error + properties: + errcode: + type: string + description: An error code. + enum: + - M_BAD_STATUS + - M_CONNECTION_FAILED + error: + type: string + description: A human-readable error message. + example: Ping returned status 401 + status: + type: integer + description: The HTTP status code returned by the appservice. + example: 401 + body: + type: string + description: The HTTP response body returned by the appservice. + example: '{"errcode": "M_UNKNOWN_TOKEN"}' + required: + - errcode + examples: + response: + value: { + "errcode": "M_BAD_STATUS", + "error": "Ping returned status 401", + "status": 401, + "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}" + } + "504": + description: The connection to the application service timed out. The errcode is + `M_CONNECTION_TIMEOUT`. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_CONNECTION_TIMEOUT", + "error": "Connection to application service timed out" + } +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. + $ref: definitions/security.yaml diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 3678f782..7792b2a9 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -219,7 +219,7 @@ paths: summary: Create a new `mxc://` URI without uploading the content. description: |- Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later - via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](http://localhost:1313/client-server-api/#put_matrixmediav3uploadservernamemediaid). + via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid). The server may optionally enforce a maximum age for unused IDs, and delete media IDs when the client doesn't start the upload in time, @@ -242,7 +242,6 @@ paths: security: - accessToken: [] # empty json object - parameters: [] responses: "200": description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for @@ -335,6 +334,18 @@ paths: type: integer format: int64 default: 20000 + - in: query + name: allow_redirect + x-addedInMatrixVersion: "1.7" + required: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. + example: false + schema: + type: boolean + default: false responses: "200": description: The content that was previously uploaded. @@ -353,6 +364,21 @@ paths: type: string # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + format: binary + "307": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string "429": description: This request was rate-limited. content: @@ -445,6 +471,18 @@ paths: type: integer format: int64 default: 20000 + - in: query + name: allow_redirect + x-addedInMatrixVersion: "1.7" + required: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. + example: false + schema: + type: boolean + default: false responses: "200": description: The content that was previously uploaded. @@ -466,6 +504,20 @@ paths: # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." format: binary + "307": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string "429": description: This request was rate-limited. content: @@ -579,6 +631,18 @@ paths: type: integer format: int64 default: 20000 + - in: query + name: allow_redirect + x-addedInMatrixVersion: "1.7" + required: false + description: | + Indicates to the server that it may return a 307 or 308 redirect response that points + at the relevant media content. When not explicitly set to true the server must return + the media content itself. + example: false + schema: + type: boolean + default: false responses: "200": description: A thumbnail of the requested content. @@ -600,9 +664,22 @@ paths: image/png: schema: type: string - # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." format: binary + "307": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string + "308": + description: A redirect to the thumbnail of the requested content. + headers: + Location: + description: The URL of the thumbnail content. + schema: + type: string "400": description: |- The request does not make sense to the server, or the server cannot thumbnail diff --git a/data/api/client-server/definitions/m.mentions.yaml b/data/api/client-server/definitions/m.mentions.yaml new file mode 100644 index 00000000..806897b4 --- /dev/null +++ b/data/api/client-server/definitions/m.mentions.yaml @@ -0,0 +1,37 @@ +# Copyright 2023 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +type: object +title: m.mentions +description: |- + Describes whether the event mentions other users or the room. This is contained + within the event's `content` alongside other fields for the relevant event type. +example: { + "body": "Hello Alice!", + "msgtype": "m.text", + "format": "org.matrix.custom.html", + "formatted_body": "Hello Alice!", + "m.mentions": { + "user_ids": ["@alice:example.org"] + } +} +properties: + user_ids: + type: string[] + description: A list of Matrix IDs of mentioned users. + room: + type: boolean + description: |- + A boolean set to `true` to mention the room, for an `@room` notification. + (`room` should otherwise not be included on the event.) diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 3bcc90aa..a8953e65 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -39,18 +39,34 @@ paths: items: type: object title: LoginFlow + required: + - type properties: type: description: |- The login type. This is supplied as the `type` when logging in. type: string + get_login_token: + type: boolean + x-addedInMatrixVersion: "1.7" + description: |- + If `type` is `m.login.token`, an optional field to indicate + to the unauthenticated client that the homeserver supports + the [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) + endpoint. Note that supporting the endpoint does not + necessarily indicate that the user attempting to log in will + be able to generate such a token. examples: response: value: { "flows": [ { "type": "m.login.password" + }, + { + "type": "m.login.token", + "get_login_token": true } ] } diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml new file mode 100644 index 00000000..73e607d1 --- /dev/null +++ b/data/api/client-server/login_token.yaml @@ -0,0 +1,134 @@ +# Copyright 2023 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +openapi: 3.1.0 +info: + title: Matrix Client-Server Registration and Login API + version: 1.0.0 +paths: + /login/get_token: + post: + summary: Optional endpoint to generate a single-use, time-limited, + `m.login.token` token. + description: |- + Optional endpoint - the server is not required to implement this endpoint if it does not + intend to use or support this functionality. + + This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + An already-authenticated client can call this endpoint to generate a single-use, time-limited, + token for an unauthenticated client to log in with, becoming logged in as the same user which + called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + login flow with the homeserver. + + Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + this feature if the server is not offering it. Authenticated clients can check for support on + a per-user basis with the `m.get_login_token` [capability](/client-server-api/#capabilities-negotiation), + while unauthenticated clients can detect server support by looking for an `m.login.token` login + flow with `get_login_token: true` on [`GET /login`](/client-server-api/#post_matrixclientv3login). + + In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + might standarise a way to transmit the token between clients. + + The generated token MUST only be valid for a single login, enforced by the server. Clients which + intend to log in multiple devices must generate a token for each. + + With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + the user for verification to ensure explicit consent is gained for each additional client. + + Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + of 1 request per minute. + operationId: generateLoginToken + x-addedInMatrixVersion: "1.7" + security: + - accessToken: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + auth: + description: Additional authentication information for the user-interactive + authentication API. + allOf: + - $ref: definitions/auth_data.yaml + required: true + responses: + "200": + description: The login token an unauthenticated client can use to log in as the + requesting user. + content: + application/json: + schema: + type: object + required: + - login_token + - expires_in_ms + properties: + login_token: + type: string + description: The login token for the `m.login.token` login flow. + expires_in_ms: + type: integer + description: |- + The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + (2 minutes) is recommended as a default. + examples: + response: + value: { + "login_token": "", + "expires_in_ms": 120000 + } + "400": + description: |- + The request was malformed, or the user does not have an ability to generate tokens for their devices, + as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api). + + Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` + [capability](/client-server-api/#capabilities-negotiation). + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + "401": + description: The homeserver requires additional authentication information. + content: + application/json: + schema: + $ref: definitions/auth_response.yaml + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Session management +servers: + - url: "{protocol}://{hostname}{basePath}" + variables: + protocol: + enum: + - http + - https + default: https + hostname: + default: localhost:8008 + basePath: + default: /_matrix/client/v1 +components: + securitySchemes: + $ref: definitions/security.yaml diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 5ad87f5f..009df48b 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -140,6 +140,20 @@ paths: required: - auth_chain_ids - pdu_ids + "404": + description: |- + The given `event_id` was not found or the server doesn't know about the state at + that event to return anything useful. + content: + application/json: + schema: + $ref: ../client-server/definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" + } "/event/{eventId}": get: summary: Get a single event diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index 35b20e61..d04e2ced 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -225,6 +225,7 @@ paths: } "/send_join/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed join event to a resident server description: |- **Note:** @@ -319,18 +320,6 @@ paths: - origin_server_ts - type - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "join", - "join_authorised_via_users_server": "@anyone:resident.example.org" - } - } required: true responses: "200": diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index 096cc5a6..ed9e6302 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -88,7 +88,6 @@ paths: given. additionalProperties: type: object - title: ServerName description: The server names to query. additionalProperties: type: object diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index a6c82987..ee616323 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -140,6 +140,7 @@ paths: } "/send_leave/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed leave event to a resident server description: |- **Note:** @@ -222,17 +223,6 @@ paths: - type - depth - content - example: { - "room_id": "!somewhere:example.org", - "type": "m.room.member", - "state_key": "@someone:example.org", - "origin": "example.org", - "origin_server_ts": 1549041175876, - "sender": "@someone:example.org", - "content": { - "membership": "leave" - } - } required: true responses: "200": diff --git a/data/event-schemas/examples/m.call.answer.yaml b/data/event-schemas/examples/m.call.answer.yaml index aaa4da71..78b48878 100644 --- a/data/event-schemas/examples/m.call.answer.yaml +++ b/data/event-schemas/examples/m.call.answer.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.answer", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "answer": { "type" : "answer", diff --git a/data/event-schemas/examples/m.call.candidates.yaml b/data/event-schemas/examples/m.call.candidates.yaml index 8f1f807a..23d0a178 100644 --- a/data/event-schemas/examples/m.call.candidates.yaml +++ b/data/event-schemas/examples/m.call.candidates.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.candidates", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "candidates": [ { diff --git a/data/event-schemas/examples/m.call.hangup.yaml b/data/event-schemas/examples/m.call.hangup.yaml index 295f16e4..a505bc36 100644 --- a/data/event-schemas/examples/m.call.hangup.yaml +++ b/data/event-schemas/examples/m.call.hangup.yaml @@ -2,7 +2,9 @@ "$ref": "core/room_event.json", "type": "m.call.hangup", "content": { - "version" : 0, - "call_id": "12345" + "version" : "1", + "party_id": "67890", + "call_id": "12345", + "reason": "user_hangup" } } diff --git a/data/event-schemas/examples/m.call.invite.yaml b/data/event-schemas/examples/m.call.invite.yaml index fa482bd9..45600001 100644 --- a/data/event-schemas/examples/m.call.invite.yaml +++ b/data/event-schemas/examples/m.call.invite.yaml @@ -2,7 +2,8 @@ "$ref": "core/room_event.json", "type": "m.call.invite", "content": { - "version" : 0, + "version" : "1", + "party_id": "67890", "call_id": "12345", "lifetime": 60000, "offer": { diff --git a/data/event-schemas/examples/m.call.negotiate.yaml b/data/event-schemas/examples/m.call.negotiate.yaml new file mode 100644 index 00000000..f4ad8587 --- /dev/null +++ b/data/event-schemas/examples/m.call.negotiate.yaml @@ -0,0 +1,14 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.negotiate", + "content": { + "version" : "1", + "party_id": "67890", + "call_id": "12345", + "lifetime": 10000, + "offer": { + "type" : "offer", + "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" + } + } +} diff --git a/data/event-schemas/examples/m.call.reject.yaml b/data/event-schemas/examples/m.call.reject.yaml new file mode 100644 index 00000000..2014566c --- /dev/null +++ b/data/event-schemas/examples/m.call.reject.yaml @@ -0,0 +1,9 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.reject", + "content": { + "version" : "1", + "party_id": "67890", + "call_id": "12345" + } +} diff --git a/data/event-schemas/examples/m.call.select_answer.yaml b/data/event-schemas/examples/m.call.select_answer.yaml new file mode 100644 index 00000000..fbd6ad16 --- /dev/null +++ b/data/event-schemas/examples/m.call.select_answer.yaml @@ -0,0 +1,10 @@ +{ + "$ref": "core/room_event.json", + "type": "m.call.select_answer", + "content": { + "version" : "1", + "call_id": "12345", + "party_id": "67890", + "selected_party_id": "111213" + } +} diff --git a/data/event-schemas/schema/core-event-schema/call_event.yaml b/data/event-schemas/schema/core-event-schema/call_event.yaml new file mode 100644 index 00000000..a8175fc8 --- /dev/null +++ b/data/event-schemas/schema/core-event-schema/call_event.yaml @@ -0,0 +1,25 @@ +description: "The content of all call events shares a set of common fields: those + of room events and some additional VoIP specific fields." +properties: + call_id: + type: string + description: The ID of the call this event relates to. + version: + type: string + description: The version of the VoIP specification this message adheres to. + This specification is version 1. This field is a string such that experimental + implementations can use non-integer versions. This field was an integer + in the previous spec version and implementations must accept an integer + 0. + party_id: + type: string + description: 'This identifies the party that sent this event. A client may + choose to re-use the device ID from end-to-end cryptography for the value + of this field.' + x-addedInMatrixVersion: "1.7" +required: +- call_id +- version +- party_id +title: CallEvent +type: object diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml index e84cf6f8..163690be 100644 --- a/data/event-schemas/schema/m.call.answer.yaml +++ b/data/event-schemas/schema/m.call.answer.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "answer": { "type": "object", "title": "Answer", @@ -28,13 +27,9 @@ } }, "required": ["type", "sdp"] - }, - "version": { - "type": "number", - "description": "The version of the VoIP specification this messages adheres to. This specification is version 0." } }, - "required": ["call_id", "answer", "version"] + "required": ["answer"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 7426717c..6aa16229 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, "candidates": { "type": "array", "description": "Array of objects describing the candidates.", @@ -34,13 +33,9 @@ }, "required": ["candidate", "sdpMLineIndex", "sdpMid"] } - }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this messages adheres to. This specification is version 0." } }, - "required": ["call_id", "candidates", "version"] + "required": ["candidates"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index 116d5af7..65d697ab 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -1,35 +1,54 @@ -{ - "type": "object", - "description": "Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.", - "allOf": [{ - "$ref": "core-event-schema/room_event.yaml" - }], - "properties": { - "content": { - "type": "object", - "properties": { - "call_id": { - "type": "string", - "description": "The ID of the call this event relates to." - }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this message adheres to. This specification is version 0." - }, - "reason": { - "type": "string", - "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.", - "enum": [ - "ice_failed", - "invite_timeout" - ] - } - }, - "required": ["call_id", "version"] - }, - "type": { - "type": "string", - "enum": ["m.call.hangup"] - } - } -} +--- +type: object +description: | + Sent by either party to signal their termination of the call. This can + be sent either once the call has has been established or before to abort the call. + + The meanings of the `reason` field are as follows: + * `ice_failed`: ICE negotiation has failed and a media connection could not be established. + * `ice_timeout`: The connection failed after some media was exchanged (as opposed to `ice_failed` + which means no media connection could be established). Note that, in the case of an ICE + renegotiation, a client should be sure to send `ice_timeout` rather than `ice_failed` if media + had previously been received successfully, even if the ICE renegotiation itself failed. + * `invite_timeout`: The other party did not answer in time. + * `user_hangup`: Clients must now send this code when the user chooses to end the call, although + for backwards compatibility with version 0, a clients should treat an absence of the `reason` + field as `user_hangup`. + * `user_media_failed`: The client was unable to start capturing media in such a way that it is unable + to continue the call. + * `user_busy`: The user is busy. Note that this exists primarily for bridging to other networks such + as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject + the new call unless the user had specifically chosen to do so. + * `unknown_error`: Some other failure occurred that meant the client was unable to continue the call + rather than the user choosing to end it. +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + properties: + reason: + type: string + description: Reason for the hangup. Note that this was optional in + previous previous versions of the spec, so a missing value should be + treated as `user_hangup`. + x-changedInMatrixVersion: + 1.7: |- + Additional values were added. + enum: + - ice_timeout + - ice_failed + - invite_timeout + - user_hangup + - user_media_failed + - user_busy + - unknown_error + required: + - reason + type: + type: string + enum: + - m.call.hangup + diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml index 65796e1e..72020b26 100644 --- a/data/event-schemas/schema/m.call.invite.yaml +++ b/data/event-schemas/schema/m.call.invite.yaml @@ -7,11 +7,10 @@ "properties": { "content": { "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], "properties": { - "call_id": { - "type": "string", - "description": "A unique identifier for the call." - }, "offer": { "type": "object", "title": "Offer", @@ -29,16 +28,17 @@ }, "required": ["type", "sdp"] }, - "version": { - "type": "integer", - "description": "The version of the VoIP specification this message adheres to. This specification is version 0." - }, "lifetime": { "type": "integer", "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI." + }, + "invitee": { + "type": "string", + "description": "The ID of the user being called. If omitted, any user in the room can answer.", + "x-addedInMatrixVersion": "1.7", } }, - "required": ["call_id", "offer", "version", "lifetime"] + "required": ["offer", "lifetime"] }, "type": { "type": "string", diff --git a/data/event-schemas/schema/m.call.negotiate.yaml b/data/event-schemas/schema/m.call.negotiate.yaml new file mode 100644 index 00000000..abc5ef1d --- /dev/null +++ b/data/event-schemas/schema/m.call.negotiate.yaml @@ -0,0 +1,74 @@ +--- +type: object +description: | + Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts + and voice/video call up/downgrading. Clients should implement and honour hold + functionality as per [WebRTC's recommendation](https://www.w3.org/TR/webrtc/#hold-functionality). + + If both the invite event and the accepted answer event have `version` equal + to `"1"`, either party may send `m.call.negotiate` with a `description` field + to offer new SDP to the other party. This event has `call_id` with the ID of + the call and `party_id` equal to the client's party ID for that call. The + caller ignores any negotiate events with `party_id` + `user_id` tuple not + equal to that of the answer it accepted and the callee ignores any negotiate + events with `party_id` + `user_id` tuple not equal to that of the caller. + Clients should use the `party_id` field to ignore the remote echo of their + own negotiate events. + + This has a `lifetime` field as in `m.call.invite`, after which the sender of + the negotiate event should consider the negotiation failed (timed out) and + the recipient should ignore it. + + The `description` field is the same as the `offer` field in `m.call.invite` + and `answer` field in `m.call.answer` and is an `RTCSessionDescriptionInit` + object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit. + + Once an `m.call.negotiate` event is received, the client must respond with + another `m.call.negotiate` event, with the SDP answer (with `"type": "answer"`) + in the `description` property. + + In the `m.call.invite` and `m.call.answer` events, the `offer` and `answer` + fields respectively are objects of type `RTCSessionDescriptionInit`. Hence + the `type` field, whilst redundant in these events, is included for ease of + working with the WebRTC API and is mandatory. Receiving clients should not + attempt to validate the `type` field, but simply pass the object into the + WebRTC API. +x-addedInMatrixVersion: "1.7" +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + properties: + offer: + type: object + title: Offer + description: The session description object + properties: + type: + type: string + enum: + - offer + description: The type of session description. + sdp: + type: string + description: The SDP text of the session description. + required: + - type + - sdp + lifetime: + type: integer + description: The time in milliseconds that the invite is valid for. + Once the invite age exceeds this value, clients should discard it. + They should also no longer show the call as awaiting an answer in the + UI. + required: + - offer + - lifetime + type: + type: string + enum: + - m.call.negotiate + diff --git a/data/event-schemas/schema/m.call.reject.yaml b/data/event-schemas/schema/m.call.reject.yaml new file mode 100644 index 00000000..39726c1a --- /dev/null +++ b/data/event-schemas/schema/m.call.reject.yaml @@ -0,0 +1,28 @@ +--- +type: object +description: | + If the `m.call.invite` event has `version` `"1"`, a client wishing to + reject the call sends an `m.call.reject` event. This rejects the call on all devices, + but if the calling device sees an `answer` before the `reject`, it disregards the + reject event and carries on. The reject has a `party_id` just like an answer, and + the caller sends a `select_answer` for it just like an answer. If another client + had already sent an answer and sees the caller select the reject response instead + of its answer, it ends the call. If the `m.call.invite` event has `version` `0`, + the callee sends an `m.call.hangup` event. If the calling user chooses to end the + call before setup is complete, the client sends `m.call.hangup` as previously. + + Note that, unlike `m.call.hangup`, this event has no `reason` field: the rejection of + a call is always implicitly because the user chose not to answer it. +x-addedInMatrixVersion: "1.7" +allOf: +- "$ref": core-event-schema/room_event.yaml +properties: + content: + type: object + allOf: + - "$ref": core-event-schema/call_event.yaml + type: + type: string + enum: + - m.call.reject + diff --git a/data/event-schemas/schema/m.call.select_answer.yaml b/data/event-schemas/schema/m.call.select_answer.yaml new file mode 100644 index 00000000..b47c1352 --- /dev/null +++ b/data/event-schemas/schema/m.call.select_answer.yaml @@ -0,0 +1,27 @@ +{ + "type": "object", + "description": "This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming `m.call.answer` events. Its `selected_party_id` field indicates the answer it's chosen. The `call_id` and `party_id` of the caller is also included. If the callee's client sees a `select_answer` for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent. Clients that implement previous versions of this specification will ignore this event and behave as they did before.", + "x-addedInMatrixVersion": "1.7", + "allOf": [{ + "$ref": "core-event-schema/room_event.yaml" + }], + "properties": { + "content": { + "type": "object", + "allOf": [{ + "$ref": "core-event-schema/call_event.yaml" + }], + "properties": { + "selected_party_id": { + "type": "string", + "description": "The `party_id` field from the answer event that the caller chose." + }, + }, + "required": ["selected_party_id"] + }, + "type": { + "type": "string", + "enum": ["m.call.select_answer"] + } + } +} diff --git a/data/event-schemas/schema/m.reaction.yaml b/data/event-schemas/schema/m.reaction.yaml index 4d8ce43b..6d369c5f 100644 --- a/data/event-schemas/schema/m.reaction.yaml +++ b/data/event-schemas/schema/m.reaction.yaml @@ -30,8 +30,10 @@ properties: key: type: string description: |- - An emoji representing the reaction being made. Should include the - unicode emoji presentation selector (`\uFE0F`) for codepoints - which allow it (see the [emoji variation sequences + The reaction being made, usually an emoji. + + If this is an emoji, it should include the unicode emoji + presentation selector (`\uFE0F`) for codepoints which allow it + (see the [emoji variation sequences list](https://www.unicode.org/Public/UCD/latest/ucd/emoji/emoji-variation-sequences.txt)). example: "👍" diff --git a/data/event-schemas/schema/m.room.join_rules.yaml b/data/event-schemas/schema/m.room.join_rules.yaml index d5f8eb2d..b6a322c6 100644 --- a/data/event-schemas/schema/m.room.join_rules.yaml +++ b/data/event-schemas/schema/m.room.join_rules.yaml @@ -28,6 +28,7 @@ properties: - invite - private - restricted + - knock_restricted type: string allow: x-addedInMatrixVersion: "1.2" diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html index 369a80db..0f4d543d 100644 --- a/layouts/partials/events/render-event.html +++ b/layouts/partials/events/render-event.html @@ -25,6 +25,8 @@ {{ with .title }}{{ . | markdownify }}{{ else }}{{ $event_name }}{{ end }} + +
{{ if (index $event_data "x-addedInMatrixVersion") }} @@ -36,8 +38,6 @@ {{ $event_data.description | markdownify }} - - {{ $state_key := index $event_data.properties "state_key" }} diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html index 2d03179e..67cd63c0 100644 --- a/layouts/shortcodes/definition.html +++ b/layouts/shortcodes/definition.html @@ -39,6 +39,8 @@ {{ $definition.title }} + +
{{ if (index $definition "x-addedInMatrixVersion") }} @@ -47,7 +49,6 @@ {{ $definition.description | markdownify }} - {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition "name" (printf "\"%s\"" $path)) }} {{ $additional_types = uniq $additional_types }} diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html index 7120f87f..91e2faf2 100644 --- a/layouts/shortcodes/event-fields.html +++ b/layouts/shortcodes/event-fields.html @@ -26,12 +26,12 @@

{{ humanize $event.title }}

+
{{ $event.description | markdownify }} - {{ $event = merge $event (dict "title" "") }} diff --git a/meta/releasing.md b/meta/releasing.md index 7483c357..92dd9be8 100644 --- a/meta/releasing.md +++ b/meta/releasing.md @@ -4,6 +4,51 @@ The whole specification is now released as a single unit/artifact. This document the process for releasing the specification and a description of how the (public) machinery works. +## Timeline + +The spec is released each calendar quarter. The target release dates are within the +following ranges: + +* Q1: January 20-27 (critically, before FOSDEM). +* Q2: May 20-27. +* Q3: August 20-27. +* Q4: November 1-15 (before recurring November conflicts, like IETF). + +The SCT aims to have dates picked out by: + +* Q1: January 10. +* Q2: May 1. +* Q3: August 1. +* Q4: October 15. + +When a release date is picked, a [checklist](https://github.com/matrix-org/matrix-spec/issues/new?assignees=&labels=release-blocker&projects=&template=release.md&title=Matrix+1.X) +issue is created to track details of the release. Release blockers should continue to +be accepted up until 7 calendar days prior to the release date. + +**Release dates are not promises.** The SCT reserves the ability to change, cancel, +postpone, etc a release for any reason. Do not rely on a release happening on a given +day until the release has actually happened & blog post published. + +Once a release is scheduled, the SCT will begin planning what the next release is +expected to look like. The plan should be included in the spec release blog post, +and be ready for exeuction on spec release day. Plans are guides and not promises. + +A blog post for the SCT members to review should be ready at minimum 1 week before +the target release date. 1-2 days before the release itself, the prerequisite steps +below are executed to ensure the spec release can go ahead. + +## Release composition + +*This section is a work in progress.* + +Mentioned above, the SCT aims to have spec releases quarterly. Each quarter has a +slightly different theme to it: + +* Q1: Massive feature release, if possible. This generally happens thanks to FOSDEM. +* Q2: Regular feature release, if possible. +* Q3: Momentum-continuing feature release, if possible. +* Q4: Preferably a maintenance release, but will accept features per normal. + ## Prerequisites / preparation First, can we even release the spec? This stage is mostly preparation work needed diff --git a/scripts/check-newsfragments b/scripts/check-newsfragments index ddba0d28..242b46d8 100755 --- a/scripts/check-newsfragments +++ b/scripts/check-newsfragments @@ -21,6 +21,12 @@ matched=0 while read f; do basename=$(basename $f) dirname=$(dirname $f) + extension="${f##*.}" + + # check that each changelog file has a known extension + if ! [[ "$extension" == "new" || "$extension" == "feature" || "$extension" == "clarification" || "$extension" == "breaking" || "$extension" == "deprecation" ]]; then + echo -e "\e[31mERROR: newsfragment $f does not have one of the required file extensions for a changelog entry: .new, .feature, .clarification, .breaking, .deprecation\e[39m" >&2 + fi # check that there is nothing that looks like a newsfile outside one of the # expected directories. @@ -31,6 +37,7 @@ while read f; do # see if this newsfile corresponds to the right PR [[ -n "$pr" && "$basename" == "$pr".* ]] && matched=1 fi +# find all files in the 'changelogs/*/' dirs that are in the form `.` done < <(find changelogs -regex '.*/[0-9]+\.[^/]+$') if [[ -n "$pr" && "$matched" -eq 0 ]]; then