Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 21:14:09 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'main' into openapi-patch

Browse source
This commit is contained in:
Dylan Hackworth 2023-01-13 16:15:37 -06:00
parent 5bdf99fe81 fdd3d94a94
commit 7857df23b1
36 changed files with 487 additions and 203 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
changelogs/client_server/newsfragments/1366.feature Normal file
View file

@ -0,0 +1 @@
Add `/rooms/<roomID>/timestamp_to_event` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).

1
changelogs/client_server/newsfragments/1381.clarification Normal file
View file

@ -0,0 +1 @@
Clarify parts of the end-to-end encryption sections.

1
changelogs/client_server/newsfragments/1382.clarification Normal file
View file

@ -0,0 +1 @@
Move login API definitions to the right heading. Contributed by @HarHarLinks.

1
changelogs/internal/newsfragments/1368.clarification Normal file
View file

@ -0,0 +1 @@
Improve safety of the proposals retrieval script in the event of failure.

1
changelogs/internal/newsfragments/1384.clarification Normal file
View file

@ -0,0 +1 @@
Stop autogenerating examples where we already have an example.

1
changelogs/room_versions/newsfragments/1397.feature Normal file
View file

@ -0,0 +1 @@
Update the default room version to 10, as per [MSC3904](https://github.com/matrix-org/matrix-spec-proposals/pull/3904).

1
changelogs/server_server/newsfragments/1350.breaking Normal file
View file

@ -0,0 +1 @@
Remove `keyId` from the server `/keys` endpoints, as per [MSC3938](https://github.com/matrix-org/matrix-spec-proposals/pull/3938).

1
changelogs/server_server/newsfragments/1366.feature Normal file
View file

@ -0,0 +1 @@
Add `/timestamp_to_event/<roomID>` endpoint, as per [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030).

1
changelogs/server_server/newsfragments/1371.clarification Normal file
View file

@ -0,0 +1 @@
Correct the default invite level definition in the "Checks performed on receipt of a PDU" section.

1
changelogs/server_server/newsfragments/1376.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that CNAMEs are permissible for server names.

1
changelogs/server_server/newsfragments/1383.clarification Normal file
View file

@ -0,0 +1 @@
Fix `edu_type` in EDU examples.

1
changelogs/server_server/newsfragments/1393.feature Normal file
View file

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

1
changelogs/server_server/newsfragments/1398.feature Normal file
View file

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

16
content/client-server-api/_index.md
View file

@ -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" >}}
{{< cs-module name="reference_relations" >}}

83
content/client-server-api/modules/end_to_end_encryption.md
View file

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

2
content/rooms/_index.md
View file

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

2
content/rooms/fragments/v5-signing-requirements.md
View file

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

64
content/server-server-api.md
View file

@ -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://<hostname>/.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 `<delegated_hostname>` is not an IP literal, and
`<delegated_port>` is present, an IP address is discovered by
looking up an AAAA or A record for `<delegated_hostname>`. The
looking up CNAME, AAAA or A records for `<delegated_hostname>`. The
resulting IP address is used, alongside the `<delegated_port>`.
Requests must be made with a `Host` header of
`<delegated_hostname>:<delegated_port>`. The target server must
@ -153,11 +156,12 @@ to send. The process overall is as follows:
a `Host` header containing the `<delegated_hostname>`. The
target server must present a valid certificate for
`<delegated_hostname>`.
- 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
`<delegated_hostname>`. The target server must present a valid
certificate for `<delegated_hostname>`.
4. If the `/.well-known` request resulted in an error response, a
server is found by resolving an SRV record for
`_matrix._tcp.<hostname>`. 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 `<hostname>`. The target server must present a
valid certificate for `<hostname>`.
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 `<hostname>`. The target
server must present a valid certificate for `<hostname>`.
@ -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

6
data/api/client-server/administrative_contact.yaml
View file

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

5
data/api/client-server/cross_signing.yaml
View file

@ -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"],

123
data/api/client-server/room_event_by_timestamp.yaml Normal file
View file

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

5
data/api/identity/definitions/request_email_validation.yaml
View file

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

6
data/api/identity/definitions/request_msisdn_validation.yaml
View file

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

4
data/api/server-server/definitions/edu.yaml
View file

@ -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']
required: ['edu_type', 'content']

21
data/api/server-server/definitions/edu_with_example.yaml Normal file
View file

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

68
data/api/server-server/definitions/send_join_response.yaml
View file

@ -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"]

4
data/api/server-server/definitions/transaction.yaml
View file

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

88
data/api/server-server/events.yaml
View file

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

41
data/api/server-server/joins-v1.yaml
View file

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

82
data/api/server-server/joins-v2.yaml
View file

@ -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"]
}

13
data/api/server-server/keys_query.yaml
View file

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

15
data/api/server-server/keys_server.yaml
View file

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

6
data/api/server-server/transactions.yaml
View file

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

2
data/api/server-server/user_devices.yaml
View file

@ -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"],

19
layouts/partials/json-schema/resolve-example.html
View file

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

2
scripts/proposals.js
View file

@ -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;
}
}