diff --git a/changelogs/client_server/newsfragments/1366.feature b/changelogs/client_server/newsfragments/1366.feature new file mode 100644 index 00000000..42d035f5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1366.feature @@ -0,0 +1 @@ +Add `/rooms//timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/changelogs/client_server/newsfragments/1381.clarification b/changelogs/client_server/newsfragments/1381.clarification new file mode 100644 index 00000000..8132e060 --- /dev/null +++ b/changelogs/client_server/newsfragments/1381.clarification @@ -0,0 +1 @@ +Clarify parts of the end-to-end encryption sections. diff --git a/changelogs/client_server/newsfragments/1382.clarification b/changelogs/client_server/newsfragments/1382.clarification new file mode 100644 index 00000000..6f08f207 --- /dev/null +++ b/changelogs/client_server/newsfragments/1382.clarification @@ -0,0 +1 @@ +Move login API definitions to the right heading. Contributed by @HarHarLinks. diff --git a/changelogs/internal/newsfragments/1368.clarification b/changelogs/internal/newsfragments/1368.clarification new file mode 100644 index 00000000..a08f1ebe --- /dev/null +++ b/changelogs/internal/newsfragments/1368.clarification @@ -0,0 +1 @@ +Improve safety of the proposals retrieval script in the event of failure. \ No newline at end of file diff --git a/changelogs/internal/newsfragments/1384.clarification b/changelogs/internal/newsfragments/1384.clarification new file mode 100644 index 00000000..46c5f9f0 --- /dev/null +++ b/changelogs/internal/newsfragments/1384.clarification @@ -0,0 +1 @@ +Stop autogenerating examples where we already have an example. diff --git a/changelogs/room_versions/newsfragments/1397.feature b/changelogs/room_versions/newsfragments/1397.feature new file mode 100644 index 00000000..4ffe3415 --- /dev/null +++ b/changelogs/room_versions/newsfragments/1397.feature @@ -0,0 +1 @@ +Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1350.breaking b/changelogs/server_server/newsfragments/1350.breaking new file mode 100644 index 00000000..81ce2585 --- /dev/null +++ b/changelogs/server_server/newsfragments/1350.breaking @@ -0,0 +1 @@ +Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938). diff --git a/changelogs/server_server/newsfragments/1366.feature b/changelogs/server_server/newsfragments/1366.feature new file mode 100644 index 00000000..22834501 --- /dev/null +++ b/changelogs/server_server/newsfragments/1366.feature @@ -0,0 +1 @@ +Add `/timestamp_to_event/` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030). diff --git a/changelogs/server_server/newsfragments/1371.clarification b/changelogs/server_server/newsfragments/1371.clarification new file mode 100644 index 00000000..e43199b8 --- /dev/null +++ b/changelogs/server_server/newsfragments/1371.clarification @@ -0,0 +1 @@ +Correct the default invite level definition in the "Checks performed on receipt of a PDU" section. diff --git a/changelogs/server_server/newsfragments/1376.clarification b/changelogs/server_server/newsfragments/1376.clarification new file mode 100644 index 00000000..470783c4 --- /dev/null +++ b/changelogs/server_server/newsfragments/1376.clarification @@ -0,0 +1 @@ +Clarify that CNAMEs are permissible for server names. diff --git a/changelogs/server_server/newsfragments/1383.clarification b/changelogs/server_server/newsfragments/1383.clarification new file mode 100644 index 00000000..f6713b87 --- /dev/null +++ b/changelogs/server_server/newsfragments/1383.clarification @@ -0,0 +1 @@ +Fix `edu_type` in EDU examples. diff --git a/changelogs/server_server/newsfragments/1393.feature b/changelogs/server_server/newsfragments/1393.feature new file mode 100644 index 00000000..e5ca05a5 --- /dev/null +++ b/changelogs/server_server/newsfragments/1393.feature @@ -0,0 +1 @@ +Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). \ No newline at end of file diff --git a/changelogs/server_server/newsfragments/1398.feature b/changelogs/server_server/newsfragments/1398.feature new file mode 100644 index 00000000..e5ca05a5 --- /dev/null +++ b/changelogs/server_server/newsfragments/1398.feature @@ -0,0 +1 @@ +Extend `/_matrix/federation/v2/send_join` to allow omitting membership events, per [MSC3706](https://github.com/matrix-org/matrix-doc/pull/3706). \ No newline at end of file diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8c2c0322..06318ae3 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1145,6 +1145,12 @@ 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`. +{{% http-api spec="client-server" api="login" %}} + +{{% http-api spec="client-server" api="refresh" %}} + +{{% http-api spec="client-server" api="logout" %}} + #### Appservice Login {{% added-in v="1.2" %}} @@ -1182,12 +1188,6 @@ If the access token does correspond to an appservice, but the user id does not lie within its namespace then the homeserver will respond with an errcode of `M_EXCLUSIVE`. -{{% http-api spec="client-server" api="login" %}} - -{{% http-api spec="client-server" api="refresh" %}} - -{{% http-api spec="client-server" api="logout" %}} - #### Login Fallback If a client does not recognize any or all login flows it can use the @@ -1818,6 +1818,8 @@ There are several APIs provided to `GET` events for a room: {{% http-api spec="client-server" api="message_pagination" %}} +{{% http-api spec="client-server" api="room_event_by_timestamp" %}} + {{% http-api spec="client-server" api="room_initial_sync" %}} ### Sending events to a room @@ -2646,4 +2648,4 @@ systems. {{< cs-module name="spaces" >}} {{< cs-module name="event_replacements" >}} {{< cs-module name="threading" >}} -{{< cs-module name="reference_relations" >}} \ No newline at end of file +{{< cs-module name="reference_relations" >}} diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index e396b409..ad10a633 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -51,6 +51,9 @@ keys. ##### Key algorithms +Different key algorithms are used for different purposes. Each key algorithm +is identified by a name and is represented in a specific way. + The name `ed25519` corresponds to the [Ed25519](http://ed25519.cr.yp.to/) signature algorithm. The key is a 32-byte Ed25519 public key, encoded using [unpadded Base64](/appendices/#unpadded-base64). Example: @@ -64,9 +67,9 @@ Example: "JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y" -The name `signed_curve25519` also corresponds to the Curve25519 -algorithm, but a key using this algorithm is represented by an object -with the following properties: +The name `signed_curve25519` also corresponds to the Curve25519 ECDH algorithm, +but the key is signed so that it can be authenticated. A key using this +algorithm is represented by an object with the following properties: `KeyObject` @@ -88,23 +91,55 @@ Example: } ``` +`ed25519` and `curve25519` keys are used for [device keys](#device-keys). +Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing). + +`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys). + ##### Device keys Each device should have one Ed25519 signing key. This key should be generated on the device from a cryptographically secure source, and the private part of the key should never be exported from the device. This -key is used as the fingerprint for a device by other clients. +key is used as the fingerprint for a device by other clients, and signs the +device's other keys. A device will generally need to generate a number of additional keys. Details of these will vary depending on the messaging algorithm in use. -Algorithms generally require device identity keys as well as signing -keys. Some algorithms also require one-time keys to improve their -secrecy and deniability. These keys are used once during session -establishment, and are then thrown away. +For Olm version 1, each device also requires a single Curve25519 identity +key. -For Olm version 1, each device requires a single Curve25519 identity -key, and a number of signed Curve25519 one-time keys. +##### One-time and fallback keys + +In addition to the device keys, which are long-lived, some encryption +algorithms require that devices may also have a number of one-time keys, which +are only used once and discarded after use. For Olm version 1, devices use +`signed_curve25519` one-time keys, signed by the device's Ed25519 key. + +Devices will generate one-time keys and upload them to the server; these will +later be [claimed](#post_matrixclientv3keysclaim) by other users. Servers must +ensure that each one-time key is only claimed once: a homeserver should discard +the one time key once it has been given to another user. + +{{% added-in v="1.2" %}} Fallback keys are similar to one-time keys, but are +not consumed once used. If a fallback key has been uploaded, it will be +returned by the server when the device has run out of one-time keys and a user +tries to claim a key. Fallback keys should be replaced with new fallback keys +as soon as possible after they have been used. + +{{% boxes/warning %}} +Fallback keys are used to prevent one-time key exhaustion when devices +are offline/unable to upload additional keys, though sessions started using +fallback keys could be vulnerable to replay attacks. +{{% /boxes/warning %}} + +Devices will be informed, [via +`/sync`](#a-namee2e-extensions-to-sync-extensions-to-sync), about the number of +one-time keys remaining that can be claimed, as well as whether the fallback +keys have been used. The device can thus ensure that, while it is online, there +is a sufficient supply of one-time keys available, and that the fallback keys +get replaced if they have been used. ##### Uploading keys @@ -115,11 +150,8 @@ signed by that key, as described in [Signing JSON](/appendices/#signing-json). One-time and fallback keys are also uploaded to the homeserver using the -[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API. - -{{% added-in v="1.2" %}} Fallback keys are similar to one-time keys, but -are not consumed once used. They are only used when the device has run out -of one-time keys, and can be replaced by a new fallback key. +[`/keys/upload`](/client-server-api/#post_matrixclientv3keysupload) API. New +one-time and fallback keys are uploaded as needed. Devices must store the private part of each key they upload. They can discard the private part of a one-time key when they receive a message @@ -129,12 +161,6 @@ never know that it can discard the key. Therefore a device could end up trying to store too many private keys. A device that is trying to store too many private keys may discard keys starting with the oldest. -{{% boxes/warning %}} -Fallback keys are used to prevent one-time key exhaustion when devices -are offline/unable to upload additional keys, though sessions started using -fallback keys could be vulnerable to replay attacks. -{{% /boxes/warning %}} - {{% boxes/warning %}} Clients should not store the private half of fallback keys indefinitely to avoid situations where attackers can decrypt past messages sent using @@ -353,21 +379,6 @@ Example: } ``` -##### Claiming one-time keys - -A client wanting to set up a session with another device can claim a -one-time key for that device. This is done by making a request to the -[`/keys/claim`](/client-server-api/#post_matrixclientv3keysclaim) API. - -A homeserver should rate-limit the number of one-time keys that a given -user or remote server can claim. A homeserver should discard the public -part of a one time key once it has given that key to another user. - -{{% added-in v="1.2" %}} If the device has run out of one-time keys which -can be claimed, the homeserver will return the fallback key (if one was -uploaded). Fallback keys are not deleted once used and should be replaced -by the device when they are able to upload more one-time keys. - #### Device verification Before Alice sends Bob encrypted data, or trusts data received from him, diff --git a/content/rooms/_index.md b/content/rooms/_index.md index ac93e69e..190b305e 100644 --- a/content/rooms/_index.md +++ b/content/rooms/_index.md @@ -52,7 +52,7 @@ stable and unstable periodically for a variety of reasons, including discovered security vulnerabilities and age. Clients should not ask room administrators to upgrade their rooms if the -room is running a stable version. Servers SHOULD use **room version 9** as +room is running a stable version. Servers SHOULD use **room version 10** as the default room version when creating new rooms. The available room versions are: diff --git a/content/rooms/fragments/v5-signing-requirements.md b/content/rooms/fragments/v5-signing-requirements.md index 136c1c13..ae1d0675 100644 --- a/content/rooms/fragments/v5-signing-requirements.md +++ b/content/rooms/fragments/v5-signing-requirements.md @@ -3,7 +3,7 @@ When validating event signatures, servers MUST enforce the `valid_until_ts` property from a key request is at least as large as the `origin_server_ts` for the event being validated. Servers missing a copy of the signing key MUST try to obtain one via the [GET -/\_matrix/key/v2/server](/server-server-api#get_matrixkeyv2serverkeyid) +/\_matrix/key/v2/server](/server-server-api#get_matrixkeyv2server) or [POST /\_matrix/key/v2/query](/server-server-api#post_matrixkeyv2query) APIs. When using the `/query` endpoint, servers MUST set the diff --git a/content/server-server-api.md b/content/server-server-api.md index 1f325e27..13bd9934 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -110,11 +110,14 @@ to send. The process overall is as follows: given. The target server must present a valid certificate for the IP address. The `Host` header in the request should be set to the server name, including the port if the server name included one. -2. If the hostname is not an IP literal, and the server name includes - an explicit port, resolve the IP address using AAAA or A records. + +2. If the hostname is not an IP literal, and the server name includes an + explicit port, resolve the hostname to an IP address using CNAME, AAAA or A + records. Requests are made to the resolved IP address and given port with a `Host` header of the original server name (with port). The target server must present a valid certificate for the hostname. + 3. If the hostname is not an IP literal, a regular HTTPS request is made to `https:///.well-known/matrix/server`, expecting the schema defined later in this section. 30x redirects should be @@ -140,7 +143,7 @@ to send. The process overall is as follows: one was provided. - If `` is not an IP literal, and `` is present, an IP address is discovered by - looking up an AAAA or A record for ``. The + looking up CNAME, AAAA or A records for ``. The resulting IP address is used, alongside the ``. Requests must be made with a `Host` header of `:`. The target server must @@ -153,11 +156,12 @@ to send. The process overall is as follows: a `Host` header containing the ``. The target server must present a valid certificate for ``. - - If no SRV record is found, an IP address is resolved using AAAA + - If no SRV record is found, an IP address is resolved using CNAME, AAAA or A records. Requests are then made to the resolve IP address and a port of 8448, using a `Host` header of ``. The target server must present a valid certificate for ``. + 4. If the `/.well-known` request resulted in an error response, a server is found by resolving an SRV record for `_matrix._tcp.`. This may result in a hostname (to be @@ -165,8 +169,9 @@ to send. The process overall is as follows: resolved IP address and port, using 8448 as a default port, with a `Host` header of ``. The target server must present a valid certificate for ``. + 5. If the `/.well-known` request returned an error response, and the - SRV record was not found, an IP address is resolved using AAAA and A + SRV record was not found, an IP address is resolved using CNAME, AAAA and A records. Requests are made to the resolved IP address using port 8448 and a `Host` header containing the ``. The target server must present a valid certificate for ``. @@ -180,6 +185,13 @@ delegation are: and other applications using SRV records such [XMPP](https://datatracker.ietf.org/doc/html/rfc6120#section-13.7.2.1). {{% /boxes/note %}} +{{% boxes/note %}} +Note that the target of a SRV record may *not* be a CNAME, as +mandated by [RFC2782](https://www.rfc-editor.org/rfc/rfc2782.html): + +> the name MUST NOT be an alias (in the sense of RFC 1034 or RFC 2181) +{{% /boxes/note %}} + {{% http-api spec="server-server" api="wellknown" %}} ### Server implementation @@ -196,11 +208,11 @@ draft](https://github.com/matrix-org/matrix-doc/blob/51faf8ed2e4a63d4cfd6d231836 {{% /boxes/note %}} Each homeserver publishes its public keys under -`/_matrix/key/v2/server/{keyId}`. Homeservers query for keys by either -getting `/_matrix/key/v2/server/{keyId}` directly or by querying an +`/_matrix/key/v2/server`. Homeservers query for keys by either +getting `/_matrix/key/v2/server` directly or by querying an intermediate notary server using a -`/_matrix/key/v2/query/{serverName}/{keyId}` API. Intermediate notary -servers query the `/_matrix/key/v2/server/{keyId}` API on behalf of +`/_matrix/key/v2/query/{serverName}` API. Intermediate notary +servers query the `/_matrix/key/v2/server` API on behalf of another server and sign the response with their own key. A server may query multiple notary servers to ensure that they all report the same public keys. @@ -227,7 +239,7 @@ homeserver and for signing events. It contains a list of Servers may query another server's keys through a notary server. The notary server may be another homeserver. The notary server will retrieve keys from the queried servers through use of the -`/_matrix/key/v2/server/{keyId}` API. The notary server will +`/_matrix/key/v2/server` API. The notary server will additionally sign the response from the queried server before returning the results. @@ -437,21 +449,25 @@ them. #### Definitions -**Required Power Level** \ -A given event type has an associated *required power level*. This is -given by the current `m.room.power_levels` event. The event type is -either listed explicitly in the `events` section or given by either -`state_default` or `events_default` depending on if the event is a state -event or not. +Required Power Level -**Invite Level, Kick Level, Ban Level, Redact Level** \ -The levels given by the `invite`, `kick`, `ban`, and `redact` properties -in the current `m.room.power_levels` state. Each defaults to 50 if -unspecified. +: A given event type has an associated *required power level*. This is given by + the current [`m.room.power_levels`](/client-server-api/#mroompower_levels) + event. The event type is either listed explicitly in the `events` section or + given by either `state_default` or `events_default` depending on if the event + is a state event or not. -**Target User** \ -For an `m.room.member` state event, the user given by the `state_key` of -the event. +Invite Level, Kick Level, Ban Level, Redact Level + +: The levels given by the `invite`, `kick`, `ban`, and `redact` properties in + the current [`m.room.power_levels`](/client-server-api/#mroompower_levels) + state. The invite level defaults to 0 if unspecified. The kick level, ban level + and redact level each default to 50 if unspecified. + +Target User + +: For an [`m.room.member`](/client-server-api/#mroommember) state event, the + user given by the `state_key` of the event. {{% boxes/warning %}} Some [room versions](/rooms) accept power level values to be represented as @@ -653,7 +669,7 @@ EDUs, by comparison to PDUs, do not have an ID, a room ID, or a list of "previous" IDs. They are intended to be non-persistent data such as user presence, typing notifications, etc. -{{% definition path="api/server-server/definitions/edu" %}} +{{% definition path="api/server-server/definitions/edu_with_example" %}} ## Room State Resolution diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml index e2e782aa..8bee761f 100644 --- a/data/api/client-server/administrative_contact.yaml +++ b/data/api/client-server/administrative_contact.yaml @@ -210,14 +210,12 @@ paths: client_secret: type: string description: The client secret used in the session with the homeserver. + example: "d0nt-T3ll" sid: type: string description: The session identifier given by the homeserver. + example: "abc123987" required: ["client_secret", "sid"] - example: { - "sid": "abc123987", - "client_secret": "d0nt-T3ll" - } responses: 200: description: The addition was successful. diff --git a/data/api/client-server/cross_signing.yaml b/data/api/client-server/cross_signing.yaml index b88da999..0ac32cfb 100644 --- a/data/api/client-server/cross_signing.yaml +++ b/data/api/client-server/cross_signing.yaml @@ -75,6 +75,11 @@ paths: allOf: - $ref: "definitions/auth_data.yaml" example: { + "auth": { + "type": "example.type.foo", + "session": "xxxxx", + "example_credential": "verypoorsharedsecret" + }, "master_key": { "user_id": "@alice:example.com", "usage": ["master"], diff --git a/data/api/client-server/room_event_by_timestamp.yaml b/data/api/client-server/room_event_by_timestamp.yaml new file mode 100644 index 00000000..7b360921 --- /dev/null +++ b/data/api/client-server/room_event_by_timestamp.yaml @@ -0,0 +1,123 @@ +# Copyright 2022 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 events in room by date 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: + "/rooms/{roomId}/timestamp_to_event": + get: + x-addedInMatrixVersion: "1.6" + summary: Get the closest event ID to the given timestamp + description: |- + Get the ID of the event closest to the given timestamp, in the + direction specified by the `dir` parameter. + + If the server does not have all of the room history and does not have + an event suitably close to the requested timestamp, it can use the + corresponding [federation endpoint](/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid) + to ask other servers for a suitable event. + + After calling this endpoint, clients can call + [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid) + to obtain a pagination token to retrieve the events around the returned event. + + The event returned by this endpoint could be an event that the client + cannot render, and so may need to paginate in order to locate an event + that it can display, which may end up being outside of the client's + suitable range. Clients can employ different strategies to display + something reasonable to the user. For example, the client could try + paginating in one direction for a while, while looking at the + timestamps of the events that it is paginating through, and if it + exceeds a certain difference from the target timestamp, it can try + paginating in the opposite direction. The client could also simply + paginate in one direction and inform the user that the closest event + found in that direction is outside of the expected range. + operationId: getEventByTimestamp + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The ID of the room to search + required: true + x-example: "!636q39766251:matrix.org" + - in: query + type: integer + name: ts + description: |- + The timestamp to search from, as given in milliseconds + since the Unix epoch. + required: true + x-example: 1432684800000 + - in: query + type: string + enum: [f, b] + name: dir + description: |- + The direction in which to search. `f` for forwards, `b` for backwards. + required: true + x-example: f + responses: + 200: + description: |- + An event was found matching the search parameters. + schema: + type: object + properties: + event_id: + type: string + description: |- + The ID of the event found + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + This makes it easy to do a quick comparison to see if the + `event_id` fetched is too far out of range to be useful for your + use case. + required: ['event_id', 'origin_server_ts'] + examples: + application/json: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + 404: + description: |- + No event was found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Room participation diff --git a/data/api/identity/definitions/request_email_validation.yaml b/data/api/identity/definitions/request_email_validation.yaml index c8a3af6a..a447c871 100644 --- a/data/api/identity/definitions/request_email_validation.yaml +++ b/data/api/identity/definitions/request_email_validation.yaml @@ -12,11 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -example: { - "client_secret": "monkeys_are_GREAT", - "email": "foo@example.com", - "send_attempt": 1 -} properties: client_secret: type: string diff --git a/data/api/identity/definitions/request_msisdn_validation.yaml b/data/api/identity/definitions/request_msisdn_validation.yaml index 2b1c8708..28544580 100644 --- a/data/api/identity/definitions/request_msisdn_validation.yaml +++ b/data/api/identity/definitions/request_msisdn_validation.yaml @@ -12,12 +12,6 @@ # See the License for the specific language governing permissions and # limitations under the License. type: object -example: { - "client_secret": "monkeys_are_GREAT", - "country": "GB", - "phone_number": "07700900001", - "send_attempt": 1 -} properties: client_secret: type: string diff --git a/data/api/server-server/definitions/edu.yaml b/data/api/server-server/definitions/edu.yaml index 0e4edcc6..1680bd60 100644 --- a/data/api/server-server/definitions/edu.yaml +++ b/data/api/server-server/definitions/edu.yaml @@ -15,8 +15,6 @@ type: object title: Ephemeral Data Unit description: An ephemeral data unit. -example: - $ref: "../examples/edu.json" properties: edu_type: type: string @@ -25,4 +23,4 @@ properties: content: type: object description: The content of the ephemeral message. -required: ['edu_type', 'content'] \ No newline at end of file +required: ['edu_type', 'content'] diff --git a/data/api/server-server/definitions/edu_with_example.yaml b/data/api/server-server/definitions/edu_with_example.yaml new file mode 100644 index 00000000..a5773fd1 --- /dev/null +++ b/data/api/server-server/definitions/edu_with_example.yaml @@ -0,0 +1,21 @@ +# Copyright 2022 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. + +# this file exists, separately to edu.yaml, so that the individual EDU +# type definitions can inherit from edu.yaml without inheriting the example. + +allOf: + - $ref: edu.yaml + - example: + $ref: "../examples/edu.json" diff --git a/data/api/server-server/definitions/send_join_response.yaml b/data/api/server-server/definitions/send_join_response.yaml deleted file mode 100644 index 12b020a2..00000000 --- a/data/api/server-server/definitions/send_join_response.yaml +++ /dev/null @@ -1,68 +0,0 @@ -# Copyright 2018 New Vector Ltd -# Copyright 2020 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: Room State -description: The state for the room. -properties: - origin: - type: string - description: The resident server's DNS name. - auth_chain: - type: array - description: |- - The auth chain for the entire current room state prior to the join event. - - Note that events have a different format depending on the room version - check the - [room version specification](/rooms) for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - example: - $ref: "../examples/minimal_pdu.json" - state: - type: array - description: |- - The resolved current room state prior to the join event. - - The event format varies depending on the room version - check the [room version specification](/rooms) - for precise event formats. - items: - type: object - title: PDU - description: |- - The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending - on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} - example: - $ref: "../examples/minimal_pdu.json" - event: - type: object - title: SignedMembershipEvent - x-addedInMatrixVersion: "1.2" - description: |- - Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed - copy of the membership event sent to other servers by the resident server, including the resident - server's signature. - example: - $ref: "../examples/minimal_pdu.json" -required: ["auth_chain", "state", "origin"] diff --git a/data/api/server-server/definitions/transaction.yaml b/data/api/server-server/definitions/transaction.yaml index e20204e0..25acda9e 100644 --- a/data/api/server-server/definitions/transaction.yaml +++ b/data/api/server-server/definitions/transaction.yaml @@ -11,6 +11,10 @@ # 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. + +# note that this definition excludes `edus`, which are typically included in +# a transaction; this is so that it can be referenced in single_pdu_transaction. + type: object title: Transaction description: Transaction diff --git a/data/api/server-server/events.yaml b/data/api/server-server/events.yaml index 4eef23b6..427978fb 100644 --- a/data/api/server-server/events.yaml +++ b/data/api/server-server/events.yaml @@ -1,4 +1,4 @@ -# Copyright 2018 New Vector Ltd +# Copyright 2018-2020 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -157,3 +157,89 @@ paths: description: A transaction containing a single PDU which is the event requested. schema: $ref: "definitions/single_pdu_transaction.yaml" + "/timestamp_to_event/{roomId}": + get: + summary: Get the closest event ID to the given timestamp + x-addedInMatrixVersion: "1.6" + description: |- + Get the ID of the event closest to the given timestamp, in the + direction specified by the `dir` parameter. + + This is primarily used when handling the corresponding + [client-server endpoint](/client-server-api/#get_matrixclientv1roomsroomidtimestamp_to_event) + when the server does not have all of the room history, and does not + have an event suitably close to the requested timestamp. + + The heuristics for deciding when to ask another homeserver for a closer + event if your homeserver doesn't have something close, are left up to + the homeserver implementation, although the heuristics will probably be + based on whether the closest event is a forward/backward extremity + indicating it's next to a gap of events which are potentially closer. + + A good heuristic for which servers to try first is to sort by servers + that have been in the room the longest because they're most likely to + have anything we ask about. + + After the local homeserver receives the response, it should determine, + using the `origin_server_ts` property, whether the returned event is + closer to the requested timestamp than the closest event that it could + find locally. If so, it should try to backfill this event via the + [`/event/{event_id}`](#get_matrixfederationv1eventeventid) endpoint so + that it is available to for a client to query. + operationId: getEventByTimestamp + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The ID of the room to search + required: true + x-example: "!636q39766251:matrix.org" + - in: query + type: integer + name: ts + description: |- + The timestamp to search from, as given in milliseconds + since the Unix epoch. + required: true + x-example: 1432684800000 + - in: query + type: string + enum: [f, b] + name: dir + description: |- + The direction in which to search. `f` for forwards, `b` for backwards. + required: true + x-example: f + responses: + 200: + description: |- + An event was found matching the search parameters. + schema: + type: object + properties: + event_id: + type: string + description: |- + The ID of the event found + origin_server_ts: + type: integer + description: |- + The event's timestamp, in milliseconds since the Unix epoch. + required: ['event_id', 'origin_server_ts'] + examples: + application/json: { + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653 + } + 404: + description: |- + No event was found. + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Unable to find event from 1432684800000 in forward direction" + } + schema: + "$ref": "../client-server/definitions/errors/error.yaml" diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index b45a49e2..1b850266 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -333,7 +333,46 @@ paths: - type: integer description: The value `200`. example: 200 - - $ref: "./definitions/send_join_response.yaml" + - type: object + title: Room State + description: The state for the room. + properties: + origin: + type: string + description: The resident server's DNS name. + auth_chain: + type: array + description: |- + The auth chain for the entire current room state prior to the join event. + + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + state: + type: array + description: |- + The resolved current room state prior to the join event. + + The event format varies depending on the room version - check the [room version specification](/rooms) + for precise event formats. + items: + type: object + title: PDU + description: |- + The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending + on the room version - check the [room version specification](/rooms) for precise event formats. + schema: + type: object + properties: {} + required: ["auth_chain", "state", "origin"] examples: application/json: [ 200, diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index 78560c86..1248c0c9 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -65,6 +65,14 @@ paths: description: The event ID for the join event. required: true x-example: "$abc123:example.org" + - in: query + name: omit_members + type: boolean + description: |- + If `true`, indicates that that calling server can accept a reduced + response, in which membership events are omitted from `state` and + redundant events are omitted from `auth_chain`. + x-addedInMatrixVersion: "1.6" - in: body name: body type: object @@ -186,11 +194,81 @@ paths: description: |- The join event has been accepted into the room. schema: - $ref: "./definitions/send_join_response.yaml" + type: object + properties: + origin: + type: string + description: The resident server's DNS name. + members_omitted: + type: boolean + description: "`true` if `m.room.member` events have been omitted from `state`." + x-addedInMatrixVersion: "1.6" + auth_chain: + type: array + description: |- + All events in the auth chain for the new join event, as well + as those in the auth chains for any events returned in + `state`. + + If the `omit_members` query parameter was set to `true`, then + any events that are returned in `state` may be omitted from + `auth_chain`, whether or not membership events are omitted + from `state`. + + Note that events have a different format depending on the room version - check the + [room version specification](/rooms) for precise event formats. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": |- + reworded to include only consider state events returned in + `state`, and to allow elision of redundant events. + state: + type: array + description: |- + The resolved current room state prior to the join event. + + If the request had `omit_members` set to `true`, events of + type `m.room.member` may be omitted from the response to + reduce the size of the response. If this is done, + `members_omitted` must be set to `true`. + items: + type: object + title: PDU + schema: + type: object + properties: {} + x-changedInMatrixVersion: + "1.6": |- + permit omission of membership events. + event: + type: object + title: SignedMembershipEvent + x-addedInMatrixVersion: "1.2" + description: |- + Required if the room version [supports restricted join rules](/rooms/#feature-matrix). The signed + copy of the membership event sent to other servers by the resident server, including the resident + server's signature. + servers_in_room: + type: array + x-addedInMatrixVersion: "1.6" + description: |- + **Required** if `members_omitted` is true. + + A list of the servers active in the room (ie, those with joined members) before the join. + items: + type: string + required: ["auth_chain", "state", "origin"] examples: application/json: { "origin": "matrix.org", "auth_chain": [{"$ref": "examples/minimal_pdu.json"}], "state": [{"$ref": "examples/minimal_pdu.json"}], - "event": {"$ref": "examples/pdu_v4_join_membership.json"} + "event": {"$ref": "examples/pdu_v4_join_membership.json"}, + "members_omitted": true, + "servers_in_room": ["matrix.org", "example.com"] } diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index cad6b882..5857ce31 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -25,7 +25,7 @@ consumes: produces: - application/json paths: - "/query/{serverName}/{keyId}": + "/query/{serverName}": get: summary: Query for another server's keys description: |- @@ -39,17 +39,6 @@ paths: description: The server's DNS name to query required: true x-example: matrix.org - - in: path - name: keyId - type: string - description: |- - **Deprecated**. Servers should not use this parameter and instead - opt to return all keys, not just the requested one. The key ID to - look up. - - When excluded, the trailing slash on this endpoint is optional. - required: false - x-example: "ed25519:abc123" - in: query name: minimum_valid_until_ts type: integer diff --git a/data/api/server-server/keys_server.yaml b/data/api/server-server/keys_server.yaml index 81b98b1e..bee520f3 100644 --- a/data/api/server-server/keys_server.yaml +++ b/data/api/server-server/keys_server.yaml @@ -23,7 +23,7 @@ basePath: /_matrix/key/v2 produces: - application/json paths: - "/server/{keyId}": + "/server": get: summary: Get the homeserver's public key(s) description: |- @@ -43,19 +43,6 @@ paths: from the server so that the signatures of old events can still be checked. operationId: getServerKey - parameters: - - in: path - name: keyId - type: string - description: |- - **Deprecated**. Servers should not use this parameter and instead - opt to return all keys, not just the requested one. The key ID to - look up. - - When excluded, the trailing slash on this endpoint is optional. - required: false - x-example: "ed25519:abc123" - deprecated: true responses: 200: description: The homeserver's keys diff --git a/data/api/server-server/transactions.yaml b/data/api/server-server/transactions.yaml index cb801ee8..d2aab20d 100644 --- a/data/api/server-server/transactions.yaml +++ b/data/api/server-server/transactions.yaml @@ -66,11 +66,7 @@ paths: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent. Must not include more than 100 EDUs. items: - $ref: "definitions/edu.yaml" - example: { - "$ref": "examples/transaction.json", - "edus": [{"$ref": "examples/edu.json"}] - } + $ref: "definitions/edu_with_example.yaml" responses: 200: description: |- diff --git a/data/api/server-server/user_devices.yaml b/data/api/server-server/user_devices.yaml index 9fb15777..1c127f9b 100644 --- a/data/api/server-server/user_devices.yaml +++ b/data/api/server-server/user_devices.yaml @@ -88,7 +88,6 @@ paths: The user\'s master cross-signing key. allOf: - $ref: ../client-server/definitions/cross_signing_key.yaml - # FIXME: why isn't the doc generator picking up this example? - example: { "user_id": "@alice:example.com", "usage": ["master"], @@ -102,7 +101,6 @@ paths: The user\'s self-signing key. allOf: - $ref: ../client-server/definitions/cross_signing_key.yaml - # FIXME: why isn't the doc generator picking up this example? - example: { "user_id": "@alice:example.com", "usage": ["self_signing"], diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html index 90620b72..ef626afd 100644 --- a/layouts/partials/json-schema/resolve-example.html +++ b/layouts/partials/json-schema/resolve-example.html @@ -13,21 +13,20 @@ {{ $example := $this_object.example }} -{{ if eq $this_object.type "object" }} - {{ if not $example }} +{{ if not $example }} + + {{ if eq $this_object.type "object" }} {{ $example = dict }} - {{ end }} - {{ range $key, $property := $this_object.properties}} - {{ $this_property_example := partial "json-schema/resolve-example" $property }} - {{ if $this_property_example }} - {{ $example = merge (dict $key $this_property_example) $example }} + {{ range $key, $property := $this_object.properties}} + {{ $this_property_example := partial "json-schema/resolve-example" $property }} + {{ if $this_property_example }} + {{ $example = merge (dict $key $this_property_example) $example }} + {{ end }} {{ end }} - {{ end }} -{{ else if eq $this_object.type "array" }} + {{ else if eq $this_object.type "array" }} - {{ if not $example }} {{/* the "items" within an array can either be an object (where we have a list of items which match the schema), or a list (for tuple validation, where each item has a different schema). diff --git a/scripts/proposals.js b/scripts/proposals.js index 42300b98..dc3f2895 100644 --- a/scripts/proposals.js +++ b/scripts/proposals.js @@ -100,7 +100,7 @@ async function getIssues() { const issuesForPage = await response.json(); issues = issues.concat(issuesForPage); const linkHeader = response.headers.get("link"); - pageLink = getNextLink(linkHeader); + pageLink = !!linkHeader ? getNextLink(linkHeader) : null; } }