From 188d568f3a086e4d2ceadad05d08ccac59a0e738 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Mon, 15 May 2023 16:31:47 +0100 Subject: [PATCH 01/24] Add 'deprecated:true' to /v1/send_{join,leave} (#1518) The words already say this is deprecated, but it was missing the flag. --- changelogs/server_server/newsfragments/1518.clarification | 1 + data/api/server-server/joins-v1.yaml | 1 + data/api/server-server/leaving-v1.yaml | 1 + 3 files changed, 3 insertions(+) create mode 100644 changelogs/server_server/newsfragments/1518.clarification diff --git a/changelogs/server_server/newsfragments/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification new file mode 100644 index 00000000..3ccb2333 --- /dev/null +++ b/changelogs/server_server/newsfragments/1518.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index edb987f2..c9480c49 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -218,6 +218,7 @@ paths: "/send_join/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed join event to a resident server description: |- **Note:** diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index 40c8a062..5264d38c 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -141,6 +141,7 @@ paths: } "/send_leave/{roomId}/{eventId}": put: + deprecated: true summary: Submit a signed leave event to a resident server description: |- **Note:** From c1ac9a9ad793c07c1699b5b0fd2ea01436513443 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 16 May 2023 21:33:05 +0100 Subject: [PATCH 02/24] Update transaction ID scope (#1526) --- .../client_server/newsfragments/1526.feature | 1 + content/client-server-api/_index.md | 30 +++++++++++++------ 2 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1526.feature diff --git a/changelogs/client_server/newsfragments/1526.feature b/changelogs/client_server/newsfragments/1526.feature new file mode 100644 index 00000000..f26f96eb --- /dev/null +++ b/changelogs/client_server/newsfragments/1526.feature @@ -0,0 +1 @@ +Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index cf00870b..798835a0 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 @@ -2671,4 +2684,3 @@ systems. {{< cs-module name="event_annotations" >}} {{< cs-module name="threading" >}} {{< cs-module name="reference_relations" >}} - From 9766b142f1d130b0392ba09a2398bd98abfb0ebe Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 16 May 2023 21:35:44 +0100 Subject: [PATCH 03/24] event_replacements: fix rationale box (#1525) This was missing its %s --- changelogs/client_server/newsfragments/1525.feature | 1 + content/client-server-api/modules/event_replacements.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1525.feature diff --git a/changelogs/client_server/newsfragments/1525.feature b/changelogs/client_server/newsfragments/1525.feature new file mode 100644 index 00000000..119ab2d6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1525.feature @@ -0,0 +1 @@ +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/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 6767b73f..1f0985ed 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 From 466acdfc467befa46278a5bfdbd51dec1db9ea13 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 17 May 2023 08:16:23 -0400 Subject: [PATCH 04/24] Update spec for MSC3952: intentional mentions (#1508) See MSC3952. --- .../client_server/newsfragments/1508.feature | 2 + .../modules/event_replacements.md | 67 ++++++++++++++ content/client-server-api/modules/mentions.md | 81 ++++++++++------- content/client-server-api/modules/push.md | 89 ++++++++++++++++++- .../client-server-api/modules/rich_replies.md | 32 ++++++- .../client-server/definitions/m.mentions.yaml | 37 ++++++++ 6 files changed, 271 insertions(+), 37 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1508.feature create mode 100644 data/api/client-server/definitions/m.mentions.yaml diff --git a/changelogs/client_server/newsfragments/1508.feature b/changelogs/client_server/newsfragments/1508.feature new file mode 100644 index 00000000..66e9670f --- /dev/null +++ b/changelogs/client_server/newsfragments/1508.feature @@ -0,0 +1,2 @@ +Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). + diff --git a/content/client-server-api/modules/event_replacements.md b/content/client-server-api/modules/event_replacements.md index 1f0985ed..9afe304e 100644 --- a/content/client-server-api/modules/event_replacements.md +++ b/content/client-server-api/modules/event_replacements.md @@ -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..ad2c544b 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 @@ -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/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/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.) From 4fabef1c973222242531318bdc3fdc7d71b0b063 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Wed, 17 May 2023 16:17:20 +0100 Subject: [PATCH 05/24] Add `allow_redirect` query parameter to relevant media endpoints (#1529) * Add `allow_redirect` query parameter to relevant media endpoints * Add added in version flag to `allow_redirect` params * Add 307/308 responses to media endpoints * Add changelogs --- .../client_server/newsfragments/1529.feature | 1 + data/api/client-server/content-repo.yaml | 69 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1529.feature diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature new file mode 100644 index 00000000..48f1d90b --- /dev/null +++ b/changelogs/client_server/newsfragments/1529.feature @@ -0,0 +1 @@ +Addition of redirect downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index 328ae1c4..e12c5612 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -308,6 +308,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: 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. responses: 200: description: "The content that was previously uploaded." @@ -323,6 +334,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 429: description: This request was rate-limited. schema: @@ -404,6 +427,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: 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. responses: 200: description: "The content that was previously uploaded." @@ -420,6 +454,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 429: description: This request was rate-limited. schema: @@ -518,6 +564,17 @@ paths: content repository can and should impose a maximum value for this parameter. The content repository may also choose to respond before the timeout. + - in: query + type: boolean + name: allow_redirect + x-addedInMatrixVersion: "1.7" + x-example: false + required: false + default: 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. responses: 200: description: "A thumbnail of the requested content." @@ -530,6 +587,18 @@ paths: type: file # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." + 307: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" + 308: + description: "A redirect to the thumbnail of the requested content." + headers: + Location: + description: "The URL of the thumbnail content." + type: "string" 400: description: |- The request does not make sense to the server, or the server cannot thumbnail From cad4f78711c51a4b66fdaaf540ecb0802f3fd99b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Fri, 19 May 2023 10:29:31 +0100 Subject: [PATCH 06/24] Update 1473.clarification fix formatting --- changelogs/server_server/newsfragments/1473.clarification | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/server_server/newsfragments/1473.clarification b/changelogs/server_server/newsfragments/1473.clarification index c5cfb948..d67095d8 100644 --- a/changelogs/server_server/newsfragments/1473.clarification +++ b/changelogs/server_server/newsfragments/1473.clarification @@ -1 +1 @@ -* Remove leftover `{key_id}` from `/_matrix/key/v2/server/` +Remove leftover `{key_id}` from `/_matrix/key/v2/server/`. From 6496d374d267e30eac1430d588cc71a205524bb2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 22 May 2023 22:38:26 -0600 Subject: [PATCH 07/24] Specify MSC3882: Using an existing session to log in another (#1530) * Specify MSC3882: Using an existing session to log in another MSC: https://github.com/matrix-org/matrix-spec-proposals/pull/3882 * Changelog entries * Update data/api/client-server/login.yaml Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Link to endpoint * Copy/paste `auth` dict definition * Move get_token API to the correct version prefix (v1, not v3) * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --------- Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../client_server/newsfragments/1530.feature | 1 + .../client_server/newsfragments/1530.new | 1 + content/client-server-api/_index.md | 6 + data/api/client-server/login.yaml | 14 ++- data/api/client-server/login_token.yaml | 118 ++++++++++++++++++ 5 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1530.feature create mode 100644 changelogs/client_server/newsfragments/1530.new create mode 100644 data/api/client-server/login_token.yaml diff --git a/changelogs/client_server/newsfragments/1530.feature b/changelogs/client_server/newsfragments/1530.feature new file mode 100644 index 00000000..90121439 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.feature @@ -0,0 +1 @@ +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). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new new file mode 100644 index 00000000..ffe9abd9 --- /dev/null +++ b/changelogs/client_server/newsfragments/1530.new @@ -0,0 +1 @@ +[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 798835a0..8ebe8f71 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1176,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" %}} diff --git a/data/api/client-server/login.yaml b/data/api/client-server/login.yaml index 7c33d1a4..b62cf2d2 100644 --- a/data/api/client-server/login.yaml +++ b/data/api/client-server/login.yaml @@ -42,7 +42,8 @@ paths: examples: application/json: { "flows": [ - {"type": "m.login.password"} + {"type": "m.login.password"}, + {"type": "m.login.token", "get_login_token": true} ] } schema: @@ -54,12 +55,23 @@ 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. 429: description: This request was rate-limited. schema: diff --git a/data/api/client-server/login_token.yaml b/data/api/client-server/login_token.yaml new file mode 100644 index 00000000..be0dca8b --- /dev/null +++ b/data/api/client-server/login_token.yaml @@ -0,0 +1,118 @@ +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server Registration and Login API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +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: [] + parameters: + - in: body + name: body + required: true + schema: + type: object + properties: + auth: + description: |- + Additional authentication information for the user-interactive authentication API. + allOf: + - $ref: "definitions/auth_data.yaml" + responses: + 200: + description: The login token an unauthenticated client can use to log in as the requesting user. + examples: + application/json: { + "login_token": "", + "expires_in_ms": 120000 + } + 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. + 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). + schema: + "$ref": "definitions/errors/error.yaml" + 401: + description: |- + The homeserver requires additional authentication information. + schema: + "$ref": "definitions/auth_response.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Session management From f564c07e600fa0f8ae63096387ed9cbc2066a022 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Tue, 23 May 2023 17:18:16 +0200 Subject: [PATCH 08/24] Fixes and clarifications around m.reaction (#1531) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1531.feature | 1 + content/client-server-api/modules/event_annotations.md | 6 ++++++ content/client-server-api/modules/push.md | 2 +- content/client-server-api/modules/receipts.md | 6 ------ data/event-schemas/schema/m.reaction.yaml | 8 +++++--- 5 files changed, 13 insertions(+), 10 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1531.feature diff --git a/changelogs/client_server/newsfragments/1531.feature b/changelogs/client_server/newsfragments/1531.feature new file mode 100644 index 00000000..a59c2177 --- /dev/null +++ b/changelogs/client_server/newsfragments/1531.feature @@ -0,0 +1 @@ +Add `m.annotation` relations (reactions), as per [MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). 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/push.md b/content/client-server-api/modules/push.md index ad2c544b..d1855f58 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -700,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: 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/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: "👍" From 9dd9639dd7c7dfb4712d389c4bcd14de9fa74840 Mon Sep 17 00:00:00 2001 From: Tulir Asokan Date: Tue, 23 May 2023 20:36:37 +0300 Subject: [PATCH 09/24] Add spec for MSC2659: application service ping endpoint (#1516) --- .../newsfragments/1516.feature | 1 + .../newsfragments/1516.new | 1 + content/application-service-api.md | 57 +++++++ data/api/application-service/ping.yaml | 63 ++++++++ data/api/client-server/appservice_ping.yaml | 150 ++++++++++++++++++ 5 files changed, 272 insertions(+) create mode 100644 changelogs/application_service/newsfragments/1516.feature create mode 100644 changelogs/application_service/newsfragments/1516.new create mode 100644 data/api/application-service/ping.yaml create mode 100644 data/api/client-server/appservice_ping.yaml diff --git a/changelogs/application_service/newsfragments/1516.feature b/changelogs/application_service/newsfragments/1516.feature new file mode 100644 index 00000000..ee222fb0 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.feature @@ -0,0 +1 @@ +Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/changelogs/application_service/newsfragments/1516.new b/changelogs/application_service/newsfragments/1516.new new file mode 100644 index 00000000..c6244075 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new @@ -0,0 +1 @@ +Add `POST /_matrix/app/v1/ping` and `POST /_matrix/client/v1/appservice/{appserviceId}/ping` endpoints as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). 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/data/api/application-service/ping.yaml b/data/api/application-service/ping.yaml new file mode 100644 index 00000000..18682f11 --- /dev/null +++ b/data/api/application-service/ping.yaml @@ -0,0 +1,63 @@ +# 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. +swagger: '2.0' +info: + title: "Matrix Application Service API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/app/v1 +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +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: [] + parameters: + - in: body + name: body + description: Ping body with optional transaction ID. + 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. + responses: + 200: + description: The provided `hs_token` is valid and the ping request was successful. + examples: + application/json: {} + schema: + type: object diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml new file mode 100644 index 00000000..4075e901 --- /dev/null +++ b/data/api/client-server/appservice_ping.yaml @@ -0,0 +1,150 @@ +# 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. +swagger: '2.0' +info: + title: "Matrix Client-Server Application Service Ping API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + # 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 +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 + type: string + 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 + x-example: "telegram" + - in: body + name: body + required: true + 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" + security: + # again, this is the appservice's token - not a typical client's + - accessToken: [] + responses: + 200: + description: The ping was successful. + 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. + examples: + application/json: {"duration_ms": 123} + 400: + description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "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`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "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. + 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: + application/json: { + "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`. + schema: + $ref: "definitions/errors/error.yaml" + examples: + application/json: { + "errcode": "M_CONNECTION_TIMEOUT", + "error": "Connection to application service timed out" + } From 17ebdf7c863b96db8c6ebe3eb075494ac3fc4064 Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 20:28:46 +0200 Subject: [PATCH 10/24] Fix ASCII art alignment (#1534) * Fix ASCII art alignment Signed-off-by: Michael Kohler Fixes #1430 * Add changelog --------- Co-authored-by: Travis Ralston --- changelogs/internal/newsfragments/1534.clarification | 1 + content/_index.md | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 changelogs/internal/newsfragments/1534.clarification diff --git a/changelogs/internal/newsfragments/1534.clarification b/changelogs/internal/newsfragments/1534.clarification new file mode 100644 index 00000000..ca5f3aea --- /dev/null +++ b/changelogs/internal/newsfragments/1534.clarification @@ -0,0 +1 @@ +Fix various typos throughout the specification. \ No newline at end of file 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: | From 4fd9f399663257747b65fc8a3b9ecc488a670613 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 23 May 2023 14:29:35 -0400 Subject: [PATCH 11/24] Add spec for MSC2746 (#1511) * Change version field to a string And add the notes on how the version field works. * Add spec requiring tracks to be within streams. * Put streams spec in its own section * Add 'invitee' field * Add party_id * Remember how JSON works * Add m.call.select_answer * Update examples * Add select_answer to call flow example diagram * Add m.call.reject * Make party_id required in other events * Add possible ways for client to handle an invite * Convert hangup & reject events to YAML So we can have a bulleted list in the description for the values of 'reason'. * Add new reason codes to hangup & reject * Add m.call.negotiate * Add other sections * Revert changes to package lock * Typos * Fix type of other version fields, fix anchor. * Add newsfragment * Fix reason in hangup/reject * Change tense Co-authored-by: Hubert Chathi * Tense, typos & grammar Co-authored-by: Hubert Chathi * Linkify Co-authored-by: Hubert Chathi * Remove unnecessary parts from link Co-authored-by: Hubert Chathi * Capitalise Co-authored-by: Hubert Chathi * Fix hangup reasons * Clarify who can answer Co-authored-by: Hubert Chathi * Linkify Co-authored-by: Hubert Chathi * Remove reference to 'this MSC'. * Move common VoIP fields into a call event type. * Move common voip events to the content, not the actual event * Remove reason from reject event I confused myself, but it's not in the MSC and it shouldn't be. * Failure to YAML * Fix number of room members allowed when sending voip events. Co-authored-by: Hubert Chathi * Add 'added in' version Co-authored-by: Hubert Chathi * Another added-in Co-authored-by: Hubert Chathi * Add missing comma --------- Co-authored-by: Hubert Chathi Co-authored-by: Travis Ralston --- .../client_server/newsfragments/1511.feature | 1 + .../client-server-api/modules/voip_events.md | 159 +++++++++++++++++- .../event-schemas/examples/m.call.answer.yaml | 3 +- .../examples/m.call.candidates.yaml | 3 +- .../event-schemas/examples/m.call.hangup.yaml | 6 +- .../event-schemas/examples/m.call.invite.yaml | 3 +- .../examples/m.call.negotiate.yaml | 14 ++ .../event-schemas/examples/m.call.reject.yaml | 9 + .../examples/m.call.select_answer.yaml | 10 ++ .../schema/core-event-schema/call_event.yaml | 25 +++ data/event-schemas/schema/m.call.answer.yaml | 13 +- .../schema/m.call.candidates.yaml | 13 +- data/event-schemas/schema/m.call.hangup.yaml | 89 ++++++---- data/event-schemas/schema/m.call.invite.yaml | 18 +- .../schema/m.call.negotiate.yaml | 74 ++++++++ data/event-schemas/schema/m.call.reject.yaml | 28 +++ .../schema/m.call.select_answer.yaml | 27 +++ 17 files changed, 426 insertions(+), 69 deletions(-) create mode 100644 changelogs/client_server/newsfragments/1511.feature create mode 100644 data/event-schemas/examples/m.call.negotiate.yaml create mode 100644 data/event-schemas/examples/m.call.reject.yaml create mode 100644 data/event-schemas/examples/m.call.select_answer.yaml create mode 100644 data/event-schemas/schema/core-event-schema/call_event.yaml create mode 100644 data/event-schemas/schema/m.call.negotiate.yaml create mode 100644 data/event-schemas/schema/m.call.reject.yaml create mode 100644 data/event-schemas/schema/m.call.select_answer.yaml diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature new file mode 100644 index 00000000..d3526b8e --- /dev/null +++ b/changelogs/client_server/newsfragments/1511.feature @@ -0,0 +1 @@ +Update VoIP spec for [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 90471cae..75cc7757 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 politenes 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/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"] + } + } +} From c94bebc98385ab2be1c37f7a2bb1ed7e86ace6af Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 21:40:32 +0200 Subject: [PATCH 12/24] Add knock_restricted to m.room.join_rules enum (#1535) * Add knock_restricted to m.room.join_rules enum Signed-off-by: Michael Kohler Fixes #1491 * Add changelog --- changelogs/client_server/newsfragments/1535.clarification | 1 + data/event-schemas/schema/m.room.join_rules.yaml | 1 + 2 files changed, 2 insertions(+) create mode 100644 changelogs/client_server/newsfragments/1535.clarification diff --git a/changelogs/client_server/newsfragments/1535.clarification b/changelogs/client_server/newsfragments/1535.clarification new file mode 100644 index 00000000..805f6b56 --- /dev/null +++ b/changelogs/client_server/newsfragments/1535.clarification @@ -0,0 +1 @@ +Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. 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" From c6348c9f78ac1a987f94dbed89e4f383117209f7 Mon Sep 17 00:00:00 2001 From: Michael Kohler Date: Tue, 23 May 2023 23:33:55 +0200 Subject: [PATCH 13/24] Remove age_ts from reference hash calculation (#1536) * Remove age_ts from reference hash calculation Signed-off-by: Michael Kohler * Add newsfragment * Fix newsfragment number * Update changelogs/server_server/newsfragments/1536.clarification Co-authored-by: Travis Ralston --------- Signed-off-by: Michael Kohler Co-authored-by: Travis Ralston --- changelogs/server_server/newsfragments/1536.clarification | 1 + content/server-server-api.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/server_server/newsfragments/1536.clarification diff --git a/changelogs/server_server/newsfragments/1536.clarification b/changelogs/server_server/newsfragments/1536.clarification new file mode 100644 index 00000000..717dc43f --- /dev/null +++ b/changelogs/server_server/newsfragments/1536.clarification @@ -0,0 +1 @@ +Remove extraneous `age_ts` field from the reference hash calculation section. \ No newline at end of file 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). From d028dc4b826fb94a508ed487becbec9a1deaa9f0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 23 May 2023 16:14:54 -0600 Subject: [PATCH 14/24] Normalize changelog for v1.7 --- changelogs/appendices/newsfragments/1468.clarification | 2 +- changelogs/appendices/newsfragments/1483.clarification | 2 +- changelogs/appendices/newsfragments/1484.clarification | 2 +- changelogs/application_service/newsfragments/1516.new | 1 - changelogs/application_service/newsfragments/1516.new.1 | 1 + changelogs/application_service/newsfragments/1516.new.2 | 1 + changelogs/client_server/newsfragments/1439.clarification | 2 +- changelogs/client_server/newsfragments/1442.clarification | 2 +- changelogs/client_server/newsfragments/1455.clarification | 2 +- changelogs/client_server/newsfragments/1464.clarification | 2 +- changelogs/client_server/newsfragments/1464.feature | 2 +- .../newsfragments/{1465.clarifications => 1465.clarification} | 0 changelogs/client_server/newsfragments/1485.clarification | 2 +- changelogs/client_server/newsfragments/1487.clarification | 2 +- changelogs/client_server/newsfragments/1495.clarification | 2 +- changelogs/client_server/newsfragments/1499.feature | 3 +-- changelogs/client_server/newsfragments/1499.new.1 | 1 + changelogs/client_server/newsfragments/1499.new.2 | 1 + changelogs/client_server/newsfragments/1501.clarification | 2 +- changelogs/client_server/newsfragments/1508.feature | 3 +-- changelogs/client_server/newsfragments/1510.feature | 3 +-- changelogs/client_server/newsfragments/1511.feature | 2 +- changelogs/client_server/newsfragments/1529.feature | 2 +- changelogs/client_server/newsfragments/1530.new | 2 +- changelogs/identity_service/newsfragments/1457.clarification | 1 - .../newsfragments/1457.clarification | 0 changelogs/internal/newsfragments/1488.clarification | 2 +- changelogs/server_server/newsfragments/1431.clarification | 2 +- changelogs/server_server/newsfragments/1454.clarification | 2 +- changelogs/server_server/newsfragments/1457.clarification | 1 - changelogs/server_server/newsfragments/1466.clarification | 2 +- changelogs/server_server/newsfragments/1518.clarification | 2 +- 32 files changed, 27 insertions(+), 29 deletions(-) delete mode 100644 changelogs/application_service/newsfragments/1516.new create mode 100644 changelogs/application_service/newsfragments/1516.new.1 create mode 100644 changelogs/application_service/newsfragments/1516.new.2 rename changelogs/client_server/newsfragments/{1465.clarifications => 1465.clarification} (100%) create mode 100644 changelogs/client_server/newsfragments/1499.new.1 create mode 100644 changelogs/client_server/newsfragments/1499.new.2 delete mode 100644 changelogs/identity_service/newsfragments/1457.clarification rename changelogs/{client_server => internal}/newsfragments/1457.clarification (100%) delete mode 100644 changelogs/server_server/newsfragments/1457.clarification diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification index 6f8ab86f..b3bb0bf4 100644 --- a/changelogs/appendices/newsfragments/1468.clarification +++ b/changelogs/appendices/newsfragments/1468.clarification @@ -1 +1 @@ -Clarify that the term "Canonical JSON" is a specific thing within the matrix specification. +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 index 4c2042e3..27a3b11d 100644 --- a/changelogs/appendices/newsfragments/1483.clarification +++ b/changelogs/appendices/newsfragments/1483.clarification @@ -1 +1 @@ -Remove references to groups +Remove references to groups. \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1484.clarification b/changelogs/appendices/newsfragments/1484.clarification index b29c7ad3..72edfa2f 100644 --- a/changelogs/appendices/newsfragments/1484.clarification +++ b/changelogs/appendices/newsfragments/1484.clarification @@ -1 +1 @@ -Clarifications of event ID formats in early room versions +Clarifications of event ID formats in early room versions. \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1516.new b/changelogs/application_service/newsfragments/1516.new deleted file mode 100644 index c6244075..00000000 --- a/changelogs/application_service/newsfragments/1516.new +++ /dev/null @@ -1 +0,0 @@ -Add `POST /_matrix/app/v1/ping` and `POST /_matrix/client/v1/appservice/{appserviceId}/ping` endpoints as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). diff --git a/changelogs/application_service/newsfragments/1516.new.1 b/changelogs/application_service/newsfragments/1516.new.1 new file mode 100644 index 00000000..7290a87c --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new.1 @@ -0,0 +1 @@ +[`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) diff --git a/changelogs/application_service/newsfragments/1516.new.2 b/changelogs/application_service/newsfragments/1516.new.2 new file mode 100644 index 00000000..ccde9078 --- /dev/null +++ b/changelogs/application_service/newsfragments/1516.new.2 @@ -0,0 +1 @@ +[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1439.clarification b/changelogs/client_server/newsfragments/1439.clarification index ed05216d..0323f6de 100644 --- a/changelogs/client_server/newsfragments/1439.clarification +++ b/changelogs/client_server/newsfragments/1439.clarification @@ -1 +1 @@ -Clarify that reply chain fallback for threads may not be present. +Clarify that reply chain fallback for threads might not be present. diff --git a/changelogs/client_server/newsfragments/1442.clarification b/changelogs/client_server/newsfragments/1442.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/1442.clarification +++ b/changelogs/client_server/newsfragments/1442.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1455.clarification b/changelogs/client_server/newsfragments/1455.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/client_server/newsfragments/1455.clarification +++ b/changelogs/client_server/newsfragments/1455.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification index f5bd822e..6096584f 100644 --- a/changelogs/client_server/newsfragments/1464.clarification +++ b/changelogs/client_server/newsfragments/1464.clarification @@ -1 +1 @@ -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). +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). diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature index 7c1c01ec..fa09a067 100644 --- a/changelogs/client_server/newsfragments/1464.feature +++ b/changelogs/client_server/newsfragments/1464.feature @@ -1 +1 @@ -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). +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). diff --git a/changelogs/client_server/newsfragments/1465.clarifications b/changelogs/client_server/newsfragments/1465.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1465.clarifications rename to changelogs/client_server/newsfragments/1465.clarification diff --git a/changelogs/client_server/newsfragments/1485.clarification b/changelogs/client_server/newsfragments/1485.clarification index 99e5fc79..0759c8cc 100644 --- a/changelogs/client_server/newsfragments/1485.clarification +++ b/changelogs/client_server/newsfragments/1485.clarification @@ -1 +1 @@ -Remove fictitious `token` parameter on `/keys/query` endpoint +Remove fictitious `token` parameter on `/keys/query` endpoint. diff --git a/changelogs/client_server/newsfragments/1487.clarification b/changelogs/client_server/newsfragments/1487.clarification index 44494576..f94a56f1 100644 --- a/changelogs/client_server/newsfragments/1487.clarification +++ b/changelogs/client_server/newsfragments/1487.clarification @@ -1 +1 @@ -Fix rendering of properties with a list of types +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 index 8132e060..69672a4c 100644 --- a/changelogs/client_server/newsfragments/1495.clarification +++ b/changelogs/client_server/newsfragments/1495.clarification @@ -1 +1 @@ -Clarify parts of the end-to-end encryption sections. +Clarify parts of the cross-signing signature upload request. diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature index efd70374..1532d281 100644 --- a/changelogs/client_server/newsfragments/1499.feature +++ b/changelogs/client_server/newsfragments/1499.feature @@ -1,2 +1 @@ -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). - +Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1499.new.1 b/changelogs/client_server/newsfragments/1499.new.1 new file mode 100644 index 00000000..d7fbdbb6 --- /dev/null +++ b/changelogs/client_server/newsfragments/1499.new.1 @@ -0,0 +1 @@ +[`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1499.new.2 b/changelogs/client_server/newsfragments/1499.new.2 new file mode 100644 index 00000000..226cb2e4 --- /dev/null +++ b/changelogs/client_server/newsfragments/1499.new.2 @@ -0,0 +1 @@ +[`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1501.clarification b/changelogs/client_server/newsfragments/1501.clarification index 97fa837c..cdac3968 100644 --- a/changelogs/client_server/newsfragments/1501.clarification +++ b/changelogs/client_server/newsfragments/1501.clarification @@ -1 +1 @@ -Remove the `dont_notify` and `coalesce` push rule actions per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). +Remove the `dont_notify` and `coalesce` push rule actions, as per [MSC3987](https://github.com/matrix-org/matrix-spec-proposals/pull/3987). diff --git a/changelogs/client_server/newsfragments/1508.feature b/changelogs/client_server/newsfragments/1508.feature index 66e9670f..324ca9a8 100644 --- a/changelogs/client_server/newsfragments/1508.feature +++ b/changelogs/client_server/newsfragments/1508.feature @@ -1,2 +1 @@ -Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952). - +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). diff --git a/changelogs/client_server/newsfragments/1510.feature b/changelogs/client_server/newsfragments/1510.feature index efd70374..1532d281 100644 --- a/changelogs/client_server/newsfragments/1510.feature +++ b/changelogs/client_server/newsfragments/1510.feature @@ -1,2 +1 @@ -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). - +Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature index d3526b8e..295a23da 100644 --- a/changelogs/client_server/newsfragments/1511.feature +++ b/changelogs/client_server/newsfragments/1511.feature @@ -1 +1 @@ -Update VoIP spec for [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). +Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature index 48f1d90b..e53bdfd8 100644 --- a/changelogs/client_server/newsfragments/1529.feature +++ b/changelogs/client_server/newsfragments/1529.feature @@ -1 +1 @@ -Addition of redirect downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). +Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new index ffe9abd9..94cb6715 100644 --- a/changelogs/client_server/newsfragments/1530.new +++ b/changelogs/client_server/newsfragments/1530.new @@ -1 +1 @@ -[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). \ No newline at end of file +[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) \ No newline at end of file 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/client_server/newsfragments/1457.clarification b/changelogs/internal/newsfragments/1457.clarification similarity index 100% rename from changelogs/client_server/newsfragments/1457.clarification rename to changelogs/internal/newsfragments/1457.clarification diff --git a/changelogs/internal/newsfragments/1488.clarification b/changelogs/internal/newsfragments/1488.clarification index d54557d9..6411f662 100644 --- a/changelogs/internal/newsfragments/1488.clarification +++ b/changelogs/internal/newsfragments/1488.clarification @@ -1 +1 @@ -Fix generation of anchors for additional properties +Fix generation of anchors for additional properties. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1431.clarification b/changelogs/server_server/newsfragments/1431.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1431.clarification +++ b/changelogs/server_server/newsfragments/1431.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +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 index 6d68b88a..559c1442 100644 --- a/changelogs/server_server/newsfragments/1454.clarification +++ b/changelogs/server_server/newsfragments/1454.clarification @@ -1 +1 @@ -Fix invalid OpenAPI specifications caused by overridden references to `examples/minimal_pdu.json`. +Fix PDU examples by removing invalid OpenAPI reference 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 index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1466.clarification +++ b/changelogs/server_server/newsfragments/1466.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification index 3ccb2333..ca5f3aea 100644 --- a/changelogs/server_server/newsfragments/1518.clarification +++ b/changelogs/server_server/newsfragments/1518.clarification @@ -1 +1 @@ -Fix various typos throughout the specification. +Fix various typos throughout the specification. \ No newline at end of file From db0fd307447edeb5724c9897e07e6c56d87123f6 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 23 May 2023 16:24:26 -0600 Subject: [PATCH 15/24] Fix stray localhost link --- data/api/client-server/content-repo.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index e12c5612..57445027 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -201,7 +201,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, From bdf574eeb2e54a832502b6a6ea5f8fb6f4a985f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 25 May 2023 00:00:38 +0200 Subject: [PATCH 16/24] Fix typo in VoIP module (#1540) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/client_server/newsfragments/1540.feature | 1 + content/client-server-api/modules/voip_events.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 changelogs/client_server/newsfragments/1540.feature diff --git a/changelogs/client_server/newsfragments/1540.feature b/changelogs/client_server/newsfragments/1540.feature new file mode 100644 index 00000000..295a23da --- /dev/null +++ b/changelogs/client_server/newsfragments/1540.feature @@ -0,0 +1 @@ +Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index 75cc7757..102e3dcd 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -44,7 +44,7 @@ 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 politenes of a party is therefore determined by +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. From 089d209047430f99fca747eed215469467b74289 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Thu, 25 May 2023 00:26:26 +0200 Subject: [PATCH 17/24] Mark the appservice ping response `duration_ms` field as required (#1541) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Mark the appservice ping response duration_ms field as required As intended in MSC2659. Signed-off-by: Kévin Commaille * Add changelog Signed-off-by: Kévin Commaille --------- Signed-off-by: Kévin Commaille --- changelogs/application_service/newsfragments/1541.feature | 1 + data/api/client-server/appservice_ping.yaml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 changelogs/application_service/newsfragments/1541.feature diff --git a/changelogs/application_service/newsfragments/1541.feature b/changelogs/application_service/newsfragments/1541.feature new file mode 100644 index 00000000..ee222fb0 --- /dev/null +++ b/changelogs/application_service/newsfragments/1541.feature @@ -0,0 +1 @@ +Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/data/api/client-server/appservice_ping.yaml b/data/api/client-server/appservice_ping.yaml index 4075e901..13b7289f 100644 --- a/data/api/client-server/appservice_ping.yaml +++ b/data/api/client-server/appservice_ping.yaml @@ -82,6 +82,8 @@ paths: 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: application/json: {"duration_ms": 123} 400: From fbb8a789f605a304e53b79e96b700b7f154aafcd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:35:38 -0600 Subject: [PATCH 18/24] Add release checklist issue template; Document some of our timelines around releases (#1538) * Add a spec release checklist issue template because I'm tired of copy/paste * Document a chunk of our release approach This should probably go elsewhere, but here is fine for now as a SCT-referenced doc/content. * changelog * Brief clarifications --- .github/ISSUE_TEMPLATE/release.md | 34 ++++++++++++++ .../internal/newsfragments/1538.clarification | 1 + meta/releasing.md | 45 +++++++++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/release.md create mode 100644 changelogs/internal/newsfragments/1538.clarification 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/internal/newsfragments/1538.clarification b/changelogs/internal/newsfragments/1538.clarification new file mode 100644 index 00000000..3362118d --- /dev/null +++ b/changelogs/internal/newsfragments/1538.clarification @@ -0,0 +1 @@ +Document more of the spec release timeline/process. \ No newline at end of file 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 From 65d70e90b82089dfc8971e8d1fd19f8cf449a8a0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:46:35 -0600 Subject: [PATCH 19/24] Tag Matrix 1.7 --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index d1749268..c36456cd 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "unstable" +status = "stable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. 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" +major = "1" +minor = "7" +release_date = "May 25, 2023" # User interface configuration [params.ui] From 8b51f1c0110384a970b777afdc11d76b17f4e97d Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 09:47:33 -0600 Subject: [PATCH 20/24] Matrix 1.7 --- .../newsfragments/1468.clarification | 1 - .../newsfragments/1483.clarification | 1 - .../newsfragments/1484.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1516.feature | 1 - .../newsfragments/1516.new.1 | 1 - .../newsfragments/1516.new.2 | 1 - .../newsfragments/1541.feature | 1 - .../newsfragments/1424.clarification | 1 - .../newsfragments/1432.clarification | 1 - .../newsfragments/1439.clarification | 1 - .../client_server/newsfragments/1440.feature | 1 - .../newsfragments/1441.clarification | 1 - .../newsfragments/1442.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1449.clarification | 1 - .../newsfragments/1455.clarification | 1 - .../newsfragments/1461.clarification | 1 - .../newsfragments/1463.clarification | 1 - .../newsfragments/1464.clarification | 1 - .../client_server/newsfragments/1464.feature | 1 - .../newsfragments/1465.clarification | 1 - .../newsfragments/1474.clarification | 1 - .../client_server/newsfragments/1475.feature | 1 - .../newsfragments/1479.clarification | 1 - .../newsfragments/1485.clarification | 1 - .../newsfragments/1487.clarification | 1 - .../newsfragments/1495.clarification | 1 - .../client_server/newsfragments/1499.feature | 1 - .../client_server/newsfragments/1499.new.1 | 1 - .../client_server/newsfragments/1499.new.2 | 1 - .../newsfragments/1500.clarification | 1 - .../newsfragments/1501.clarification | 1 - .../newsfragments/1507.clarification | 1 - .../client_server/newsfragments/1508.feature | 1 - .../newsfragments/1509.clarification | 1 - .../client_server/newsfragments/1510.feature | 1 - .../client_server/newsfragments/1511.feature | 1 - .../client_server/newsfragments/1525.feature | 1 - .../client_server/newsfragments/1526.feature | 1 - .../client_server/newsfragments/1529.feature | 1 - .../client_server/newsfragments/1530.feature | 1 - .../client_server/newsfragments/1530.new | 1 - .../client_server/newsfragments/1531.feature | 1 - .../newsfragments/1535.clarification | 1 - .../client_server/newsfragments/1540.feature | 1 - .../newsfragments/1486.clarification | 1 - .../internal/newsfragments/1444.clarification | 1 - .../internal/newsfragments/1446.clarification | 1 - .../internal/newsfragments/1457.clarification | 1 - .../internal/newsfragments/1476.clarification | 1 - .../internal/newsfragments/1488.clarification | 1 - .../internal/newsfragments/1534.clarification | 1 - .../internal/newsfragments/1538.clarification | 1 - .../newsfragments/1484.clarification | 1 - .../newsfragments/1431.clarification | 1 - .../newsfragments/1447.clarification | 1 - .../newsfragments/1454.clarification | 1 - .../newsfragments/1466.clarification | 1 - .../newsfragments/1473.clarification | 1 - .../newsfragments/1518.clarification | 1 - .../newsfragments/1536.clarification | 1 - content/changelog/v1.7.md | 147 ++++++++++++++++++ 63 files changed, 147 insertions(+), 62 deletions(-) delete mode 100644 changelogs/appendices/newsfragments/1468.clarification delete mode 100644 changelogs/appendices/newsfragments/1483.clarification delete mode 100644 changelogs/appendices/newsfragments/1484.clarification delete mode 100644 changelogs/application_service/newsfragments/1447.clarification delete mode 100644 changelogs/application_service/newsfragments/1516.feature delete mode 100644 changelogs/application_service/newsfragments/1516.new.1 delete mode 100644 changelogs/application_service/newsfragments/1516.new.2 delete mode 100644 changelogs/application_service/newsfragments/1541.feature delete mode 100644 changelogs/client_server/newsfragments/1424.clarification delete mode 100644 changelogs/client_server/newsfragments/1432.clarification delete mode 100644 changelogs/client_server/newsfragments/1439.clarification delete mode 100644 changelogs/client_server/newsfragments/1440.feature delete mode 100644 changelogs/client_server/newsfragments/1441.clarification delete mode 100644 changelogs/client_server/newsfragments/1442.clarification delete mode 100644 changelogs/client_server/newsfragments/1447.clarification delete mode 100644 changelogs/client_server/newsfragments/1449.clarification delete mode 100644 changelogs/client_server/newsfragments/1455.clarification delete mode 100644 changelogs/client_server/newsfragments/1461.clarification delete mode 100644 changelogs/client_server/newsfragments/1463.clarification delete mode 100644 changelogs/client_server/newsfragments/1464.clarification delete mode 100644 changelogs/client_server/newsfragments/1464.feature delete mode 100644 changelogs/client_server/newsfragments/1465.clarification delete mode 100644 changelogs/client_server/newsfragments/1474.clarification delete mode 100644 changelogs/client_server/newsfragments/1475.feature delete mode 100644 changelogs/client_server/newsfragments/1479.clarification delete mode 100644 changelogs/client_server/newsfragments/1485.clarification delete mode 100644 changelogs/client_server/newsfragments/1487.clarification delete mode 100644 changelogs/client_server/newsfragments/1495.clarification delete mode 100644 changelogs/client_server/newsfragments/1499.feature delete mode 100644 changelogs/client_server/newsfragments/1499.new.1 delete mode 100644 changelogs/client_server/newsfragments/1499.new.2 delete mode 100644 changelogs/client_server/newsfragments/1500.clarification delete mode 100644 changelogs/client_server/newsfragments/1501.clarification delete mode 100644 changelogs/client_server/newsfragments/1507.clarification delete mode 100644 changelogs/client_server/newsfragments/1508.feature delete mode 100644 changelogs/client_server/newsfragments/1509.clarification delete mode 100644 changelogs/client_server/newsfragments/1510.feature delete mode 100644 changelogs/client_server/newsfragments/1511.feature delete mode 100644 changelogs/client_server/newsfragments/1525.feature delete mode 100644 changelogs/client_server/newsfragments/1526.feature delete mode 100644 changelogs/client_server/newsfragments/1529.feature delete mode 100644 changelogs/client_server/newsfragments/1530.feature delete mode 100644 changelogs/client_server/newsfragments/1530.new delete mode 100644 changelogs/client_server/newsfragments/1531.feature delete mode 100644 changelogs/client_server/newsfragments/1535.clarification delete mode 100644 changelogs/client_server/newsfragments/1540.feature delete mode 100644 changelogs/identity_service/newsfragments/1486.clarification delete mode 100644 changelogs/internal/newsfragments/1444.clarification delete mode 100644 changelogs/internal/newsfragments/1446.clarification delete mode 100644 changelogs/internal/newsfragments/1457.clarification delete mode 100644 changelogs/internal/newsfragments/1476.clarification delete mode 100644 changelogs/internal/newsfragments/1488.clarification delete mode 100644 changelogs/internal/newsfragments/1534.clarification delete mode 100644 changelogs/internal/newsfragments/1538.clarification delete mode 100644 changelogs/room_versions/newsfragments/1484.clarification delete mode 100644 changelogs/server_server/newsfragments/1431.clarification delete mode 100644 changelogs/server_server/newsfragments/1447.clarification delete mode 100644 changelogs/server_server/newsfragments/1454.clarification delete mode 100644 changelogs/server_server/newsfragments/1466.clarification delete mode 100644 changelogs/server_server/newsfragments/1473.clarification delete mode 100644 changelogs/server_server/newsfragments/1518.clarification delete mode 100644 changelogs/server_server/newsfragments/1536.clarification create mode 100644 content/changelog/v1.7.md diff --git a/changelogs/appendices/newsfragments/1468.clarification b/changelogs/appendices/newsfragments/1468.clarification deleted file mode 100644 index b3bb0bf4..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 27a3b11d..00000000 --- a/changelogs/appendices/newsfragments/1483.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove references to groups. \ No newline at end of file diff --git a/changelogs/appendices/newsfragments/1484.clarification b/changelogs/appendices/newsfragments/1484.clarification deleted file mode 100644 index 72edfa2f..00000000 --- a/changelogs/appendices/newsfragments/1484.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarifications of event ID formats in early room versions. \ No newline at end of file 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/application_service/newsfragments/1516.feature b/changelogs/application_service/newsfragments/1516.feature deleted file mode 100644 index ee222fb0..00000000 --- a/changelogs/application_service/newsfragments/1516.feature +++ /dev/null @@ -1 +0,0 @@ -Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. diff --git a/changelogs/application_service/newsfragments/1516.new.1 b/changelogs/application_service/newsfragments/1516.new.1 deleted file mode 100644 index 7290a87c..00000000 --- a/changelogs/application_service/newsfragments/1516.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/app/v1/ping`](/application-service-api/#post_matrixappv1ping) diff --git a/changelogs/application_service/newsfragments/1516.new.2 b/changelogs/application_service/newsfragments/1516.new.2 deleted file mode 100644 index ccde9078..00000000 --- a/changelogs/application_service/newsfragments/1516.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/client/v1/appservice/{appserviceId}/ping`](/application-service-api/#post_matrixclientv1appserviceappserviceidping) \ No newline at end of file diff --git a/changelogs/application_service/newsfragments/1541.feature b/changelogs/application_service/newsfragments/1541.feature deleted file mode 100644 index ee222fb0..00000000 --- a/changelogs/application_service/newsfragments/1541.feature +++ /dev/null @@ -1 +0,0 @@ -Add homeserver->appservice ping mechanism, as per [MSC2659](https://github.com/matrix-org/matrix-spec-proposals/pull/2659). Contributed by @tulir at @beeper. 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 0323f6de..00000000 --- a/changelogs/client_server/newsfragments/1439.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify that reply chain fallback for threads might 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 ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1442.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/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 ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1455.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/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 6096584f..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, 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). diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature deleted file mode 100644 index fa09a067..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`, 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). diff --git a/changelogs/client_server/newsfragments/1465.clarification b/changelogs/client_server/newsfragments/1465.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/client_server/newsfragments/1465.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/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 0759c8cc..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 f94a56f1..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 69672a4c..00000000 --- a/changelogs/client_server/newsfragments/1495.clarification +++ /dev/null @@ -1 +0,0 @@ -Clarify parts of the cross-signing signature upload request. diff --git a/changelogs/client_server/newsfragments/1499.feature b/changelogs/client_server/newsfragments/1499.feature deleted file mode 100644 index 1532d281..00000000 --- a/changelogs/client_server/newsfragments/1499.feature +++ /dev/null @@ -1 +0,0 @@ -Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1499.new.1 b/changelogs/client_server/newsfragments/1499.new.1 deleted file mode 100644 index d7fbdbb6..00000000 --- a/changelogs/client_server/newsfragments/1499.new.1 +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/media/v1/create`](/client-server-api/#post_matrixmediav1create) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1499.new.2 b/changelogs/client_server/newsfragments/1499.new.2 deleted file mode 100644 index 226cb2e4..00000000 --- a/changelogs/client_server/newsfragments/1499.new.2 +++ /dev/null @@ -1 +0,0 @@ -[`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](/client-server-api/#put_matrixmediav3uploadservernamemediaid) \ No newline at end of file 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 cdac3968..00000000 --- a/changelogs/client_server/newsfragments/1501.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove the `dont_notify` and `coalesce` push rule actions, as 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/1508.feature b/changelogs/client_server/newsfragments/1508.feature deleted file mode 100644 index 324ca9a8..00000000 --- a/changelogs/client_server/newsfragments/1508.feature +++ /dev/null @@ -1 +0,0 @@ -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). 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 1532d281..00000000 --- a/changelogs/client_server/newsfragments/1510.feature +++ /dev/null @@ -1 +0,0 @@ -Support asynchronous media uploads, as per [MSC2246](https://github.com/matrix-org/matrix-spec-proposals/pull/2246). diff --git a/changelogs/client_server/newsfragments/1511.feature b/changelogs/client_server/newsfragments/1511.feature deleted file mode 100644 index 295a23da..00000000 --- a/changelogs/client_server/newsfragments/1511.feature +++ /dev/null @@ -1 +0,0 @@ -Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). diff --git a/changelogs/client_server/newsfragments/1525.feature b/changelogs/client_server/newsfragments/1525.feature deleted file mode 100644 index 119ab2d6..00000000 --- a/changelogs/client_server/newsfragments/1525.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/1526.feature b/changelogs/client_server/newsfragments/1526.feature deleted file mode 100644 index f26f96eb..00000000 --- a/changelogs/client_server/newsfragments/1526.feature +++ /dev/null @@ -1 +0,0 @@ -Update the scope of transaction IDs, as per [MSC3970](https://github.com/matrix-org/matrix-spec-proposals/pull/3970). diff --git a/changelogs/client_server/newsfragments/1529.feature b/changelogs/client_server/newsfragments/1529.feature deleted file mode 100644 index e53bdfd8..00000000 --- a/changelogs/client_server/newsfragments/1529.feature +++ /dev/null @@ -1 +0,0 @@ -Add an ability to redirect media downloads, as per [MSC3860](https://github.com/matrix-org/matrix-spec-proposals/pull/3860). diff --git a/changelogs/client_server/newsfragments/1530.feature b/changelogs/client_server/newsfragments/1530.feature deleted file mode 100644 index 90121439..00000000 --- a/changelogs/client_server/newsfragments/1530.feature +++ /dev/null @@ -1 +0,0 @@ -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). \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1530.new b/changelogs/client_server/newsfragments/1530.new deleted file mode 100644 index 94cb6715..00000000 --- a/changelogs/client_server/newsfragments/1530.new +++ /dev/null @@ -1 +0,0 @@ -[`POST /_matrix/client/v1/login/get_token`](/client-server-api/#post_matrixclientv1loginget_token) \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1531.feature b/changelogs/client_server/newsfragments/1531.feature deleted file mode 100644 index a59c2177..00000000 --- a/changelogs/client_server/newsfragments/1531.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/1535.clarification b/changelogs/client_server/newsfragments/1535.clarification deleted file mode 100644 index 805f6b56..00000000 --- a/changelogs/client_server/newsfragments/1535.clarification +++ /dev/null @@ -1 +0,0 @@ -Add missing `knock_restricted` join rule to the `m.room.join_rules` schema. diff --git a/changelogs/client_server/newsfragments/1540.feature b/changelogs/client_server/newsfragments/1540.feature deleted file mode 100644 index 295a23da..00000000 --- a/changelogs/client_server/newsfragments/1540.feature +++ /dev/null @@ -1 +0,0 @@ -Improve VoIP signaling, as per [MSC2746](https://github.com/matrix-org/matrix-spec-proposals/pull/2746). 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/1457.clarification b/changelogs/internal/newsfragments/1457.clarification deleted file mode 100644 index 0abd9b6c..00000000 --- a/changelogs/internal/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/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 6411f662..00000000 --- a/changelogs/internal/newsfragments/1488.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix generation of anchors for additional properties. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1534.clarification b/changelogs/internal/newsfragments/1534.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/internal/newsfragments/1534.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix various typos throughout the specification. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1538.clarification b/changelogs/internal/newsfragments/1538.clarification deleted file mode 100644 index 3362118d..00000000 --- a/changelogs/internal/newsfragments/1538.clarification +++ /dev/null @@ -1 +0,0 @@ -Document more of the spec release timeline/process. \ No newline at end of file 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 ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1431.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/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 559c1442..00000000 --- a/changelogs/server_server/newsfragments/1454.clarification +++ /dev/null @@ -1 +0,0 @@ -Fix PDU examples by removing invalid OpenAPI reference to `examples/minimal_pdu.json`. diff --git a/changelogs/server_server/newsfragments/1466.clarification b/changelogs/server_server/newsfragments/1466.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1466.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/1473.clarification b/changelogs/server_server/newsfragments/1473.clarification deleted file mode 100644 index d67095d8..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/1518.clarification b/changelogs/server_server/newsfragments/1518.clarification deleted file mode 100644 index ca5f3aea..00000000 --- a/changelogs/server_server/newsfragments/1518.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/1536.clarification b/changelogs/server_server/newsfragments/1536.clarification deleted file mode 100644 index 717dc43f..00000000 --- a/changelogs/server_server/newsfragments/1536.clarification +++ /dev/null @@ -1 +0,0 @@ -Remove extraneous `age_ts` field from the reference hash calculation section. \ No newline at end of file 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)) From 48ee5074899e5e17e1113c07956ffcd75fd0d599 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 25 May 2023 10:29:58 -0600 Subject: [PATCH 21/24] Build unstable --- config.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml b/config.toml index c36456cd..00757bd5 100644 --- a/config.toml +++ b/config.toml @@ -47,14 +47,14 @@ privacy_policy = "https://matrix.org/legal/privacy-notice" [params.version] # must be one of "unstable", "current", "historical" # this is used to decide whether to show a banner pointing to the current release -status = "stable" +status = "unstable" # A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner. 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 = "7" -release_date = "May 25, 2023" +# major = "1" +# minor = "7" +# release_date = "May 25, 2023" # User interface configuration [params.ui] From 48459dee9b949be023cffe65c280ef172cc54868 Mon Sep 17 00:00:00 2001 From: David Robertson Date: Tue, 30 May 2023 13:22:30 +0100 Subject: [PATCH 22/24] Only include titles in summaries (#1549) I previously made this change for HTTP endpoints in #1446. It seems there are other places where we have over-sized `` elements. I would like to elimintate those too, as grumbled about in https://github.com/matrix-org/matrix-spec/issues/1358#issuecomment-1325220859 and https://github.com/matrix-org/matrix-spec/issues/1352#issuecomment-1439033334 --- changelogs/internal/newsfragments/1549.clarification | 1 + layouts/partials/events/render-event.html | 4 ++-- layouts/shortcodes/definition.html | 3 ++- layouts/shortcodes/event-fields.html | 2 +- 4 files changed, 6 insertions(+), 4 deletions(-) create mode 100644 changelogs/internal/newsfragments/1549.clarification 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/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" "") }} From dd6af5bfb14ef4f385d1b2cc9d960042a2a7124e Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Wed, 31 May 2023 04:50:21 -0500 Subject: [PATCH 23/24] Document why `/state_ids` can respond with a 404 (#1521) --- .../server_server/newsfragments/1521.clarification | 1 + data/api/server-server/events.yaml | 11 +++++++++++ 2 files changed, 12 insertions(+) create mode 100644 changelogs/server_server/newsfragments/1521.clarification 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/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 427978fb..6d7ca45a 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -137,6 +137,17 @@ paths: type: string example: ["$an_event:example.org"] 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. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" + } + schema: + "$ref": "../client-server/definitions/errors/error.yaml" "/event/{eventId}": get: summary: Get a single event From c64a616d54dc62030e7637582d3a58d14f13f118 Mon Sep 17 00:00:00 2001 From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Date: Wed, 31 May 2023 11:30:51 +0100 Subject: [PATCH 24/24] Update the changelog entry checker script to check newsfragment file extension (#1542) --- changelogs/internal/newsfragments/1542.clarification | 1 + scripts/check-newsfragments | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelogs/internal/newsfragments/1542.clarification 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/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