Linearized Matrix

3.2.1. Room Versions

TODO: We should consider naming this something else.¶

A room version is a set of algorithms which define how the room operates, identified by a single string. Room versions are immutable once specified, as otherwise a change in algorithms could cause a split-brain between participating servers.¶

Room versions prefixed with I. MUST only be used within the IETF specification process. Room versions consisting solely of 0-9 and . MUST only be used by the Matrix protocol.¶

There is no implicit ordering or hierarchy to room versions. Although there is a recommended default room version, some rooms might benefit from features of a different room version.¶

A room version has the following algorithms defined:¶

• Event authorization - Rules which govern when events are accepted, rejected, or soft-failed by a server.¶
• Redaction - Description of which fields to keep on an event during redaction. Redaction is used by the signing and hash algorithms, meaning they need to be consistent across implementations.¶
• Event format - Which fields are expected to be present on an event, and the schema for each.¶
• Canonical JSON - Specific details about how to canonicalize an event as JSON. This is used by the signing algorithm and must be consistent between implementations.¶
• Hub selection - Rules around picking the hub server and transferring to a new hub.¶
• Identifier grammar - All identifiers (room IDs, user IDs, event IDs, etc) can change grammar within a room version. As such, they SHOULD generally be treated as opaque as possible over a transport.¶

A server is capable of supporting multiple room versions at a time. The transport API decouples specific details regarding room versions from the wire formats. For example, events are treated as JSON blobs in this document's Server-Server API (Section 13).¶

Room versions are normally specified using a dedicated document. An example of this can be found in the existing Matrix Spec Change process as [MSC3820].¶

Each room version has a "stable" or "unstable" designation. Stable room versions SHOULD be used in production by messaging providers. Unstable room versions might contain bugs or are not yet fully specified and SHOULD NOT be used in production by messaging providers.¶

TODO: Matrix considers a version as stable once accepted through FCP. When would be the process equivalent for the IETF?¶

The ABNF [RFC5234] grammar for a room version is:¶

room_version = 1*128room_version_char
room_version_char = DIGIT
                  / %x61-7A         ; a-z
                  / "-" / "."

Examples:¶

• 1¶
• I.1¶
• org.example.my-room-version¶

Room versions not formally specified SHOULD be prefixed using reverse domain name notation, creating a sort of namespace. org.example.my-room-version is an example of this.¶

3.5.1. Linearized PDU

The hub server is responsible for ensuring events are linearly added to the room from all participants, which means participants cannot set fields such as prev_events on their events. Additionally, participant servers are not expected to store past conversation history or even "current state" for the room, further making participants unable to reliably populate auth_events and prev_events.¶

To avoid these problems, the participant server MUST NOT populate the following fields on events they are sending to the hub:¶

• auth_events - the participant cannot reliably determine what allows it to send the event.¶
• prev_events - the participant cannot reliably know what event precedes theirs.¶
• hashes (except hashes.lpdu) - top-level hashes cover the above two fields.¶

The participant server MUST populate the hashes.lpdu object, covering a content hash (Section 10.1) of the partial event, giving authenticity to the sender's contents. The participant server additionally signs this partial event before sending it to the hub.¶

The participant server will receive an echo of the fully-formed event from the hub once appended to the room.¶

3.5.2. State Events

State events track metadata for the room, such as name, topic, and members. State is keyed by a tuple of type and state_key, noting that an empty string is a valid state key. State in the room with the same key-tuple will be overwritten as "current state".¶

State events are otherwise processed like regular events in the room: they're appended to the room history and can be referenced by that room history.¶

"Current state" is the state at the time being considered (which is often the implied HEAD of the room). In Linearized Matrix, a simple approach to calculating current state is to iterate over all events in order, overwriting the key-tuple for state events in an adjacent map. That map becomes "current state" when the loop is finished.¶

{
   "type": "m.room.create",
   "sender": "@alice:example.org",
   "state_key": "",
   "content": {
      "room_version": "I.1"
   }
}

3.5.3. Event Types

Linearized Matrix defines the following event types. The section headers are the event type.¶

6.4.1. Auth Events Selection

The auth_events on an event MUST consist of the following state events, with the exception of an m.room.create event which has no auth_events.¶

1. The m.room.create state event.¶
2. The current m.room.power_levels state event, if any.¶
3. The sender's current m.room.member state event, if any.¶

4. If the type is m.room.member:¶

   1. The target's (state_key) current m.room.member state event, if any.¶
   2. If content.membership is join or invite, the current m.room.join_rules state event, if any.¶

TODO: Talk about restricted room joins here?¶

6.4.2. Auth Rules Algorithm

With consideration for default/calculated power levels (Section 3.5.3.4.1), the ordered rules which affect authorization of a given event are as follows.¶

See Section 6.2 for a description of "reject".¶

TODO: should we reference m.federate?¶

1. Events must be signed (Section 7.3) by the server denoted by the sender field. Note that this may be an LPDU if the hub_server is specified and not the same server.¶
2. If hub_server is present, events must be signed (Section 7.3) by that server.¶

3. If type is m.room.create:¶

   1. If it has any prev_events, reject.¶
   2. If the domain of the room_id is not the same domain as the sender, reject.¶
   3. If content.room_version is not I.1, reject.¶
   4. Otherwise, allow.¶

4. Considering the event's auth_events:¶

   1. If there are duplicate entries for a given type and state_key pair, reject.¶
   2. If there are entries whose type and state_key do not match those specified by the auth events selection algorithm (Section 6.4.1), reject.¶
   3. If there are entries where the referenced event was rejected during receipt (Section 6.2), reject.¶
   4. If there is no m.room.create event among the entries, reject.¶

5. If type is m.room.member:¶

   1. If there is no state_key property, or no membership in content, reject.¶

   2. If membership is join:¶

      1. If the previous event is an m.room.create event and the state_key is the creator, allow.¶
      2. If sender does not match state_key, reject.¶
      3. If the sender is banned, reject.¶
      4. If the join_rule for m.room.join_rules is invite or knock, then allow if the current membership state is invite or join.¶
      5. If the join_rule for m.room.join_rules is public, allow.¶
      6. Otherwise, reject.¶

   3. If membership is invite:¶

      1. If the sender's current membership state is not join, reject.¶
      2. If the target user's (state_key) membership is join or ban, reject.¶
      3. If the sender's power level is greater than or equal to the power level needed to send invites, allow.¶
      4. Otherwise, reject.¶

   4. If membership is leave:¶

      1. If the sender matches the state_key, allow if and only if that user's current membership state is knock, join, or invite.¶
      2. If the sender's current membership state is not join, reject.¶
      3. If the target user's (state_key) current membership state is ban, and the sender's power level is less than the power level needed to ban other users, reject.¶
      4. If the sender's power level is greater than or equal to the power level needed to kick users, and the target user's (state_key) power level is less than the sender's, allow.¶
      5. Otherwise, reject.¶

   5. If membership is ban:¶

      1. If the sender's current membership state is not join, reject.¶
      2. If the sender's power level is greater than or equal to the power level needed to ban users, and the target user's (state_key) power level is less than the sender's power level, allow.¶
      3. Otherwise, reject.¶

   6. If membership is knock:¶

      1. If the join_rule for m.room.join_rules is anything other than knock, reject.¶
      2. If the sender does not match the state_key, reject.¶
      3. If the sender's current membership state is not ban or join, allow.¶
      4. Otherwise, reject.¶
   7. Otherwise, the membership is unknown. Reject.¶
6. If the sender's current membership state is not join, reject.¶
7. If the event type's required power level is greater than the sender's power level, reject.¶
8. If the event has a state_key which starts with an @ and does not match the sender, reject.¶

9. If type is m.room.power_levels:¶

   1. If any of the fields users_default, events_default, state_default, ban, redact, kick, or invite in content are present and not an integer, reject.¶
   2. If events in content is present and not an object with values that are integers, reject.¶
   3. If the users in content is present and not an object with valid user IDs as keys and integers as values, reject.¶
   4. If there is no previous m.room.power_levels event in the room, allow.¶

   5. For the fields users_default, events_default, state_default, ban, redact, kick, and invite, check if they were added, changed, or removed. For each found alteration:¶

      1. If the current value is higher than the sender's current power level, reject.¶
      2. If the new value is higher than the sender's current power level, reject.¶

   6. For each entry being changed in or removed from events:¶

      1. If the current value is higher than the sender's current power level, reject.¶

   7. For each entry being added to or changed in events:¶

      1. If the new value is greater than the sender's current power level, reject.¶

   8. For each entry being changed in or removed from users, other than the sender's own entry:¶

      1. If the current value is higher than the sender's current power level, reject.¶

   9. For each entry being added to or changed in users:¶

      1. If the new value is greater than the sender's current power level, reject.¶
   10. Otherwise, allow.¶
10. Otherwise, allow.¶

There are some consequences to these rules:¶

• Unless you are already a member of the room, the only permitted operations (aside from the initial create/join) are being able to join public rooms, accept invites to rooms, and reject invites to rooms.¶
• To unban another user, the sender must have a power level greater than or equal to both the kick and ban power levels, and greater than the target user's power level.¶

TODO: If we want to enforce a single hub in a room, we'd do so here with auth rules.¶

13.2.1. Requests and Responses

All HTTP POST and PUT endpoints require the sending server to supply a (potentially empty) JSON object as the request body. Requesting servers SHOULD supply a Content-Type header of application/json for such requests.¶

All endpoints which require a server to respond with a JSON object MUST include a Content-Type header of application/json.¶

All JSON data, in requests or responses, MUST be encoded using UTF-8 [RFC3629].¶

All endpoints in this document do not support trailing slashes on them. When such a request is encountered, it MUST be handled as an unknown endpoint (Section 13.2.3). Examples include:¶

• https://example.org/_matrix/path - valid.¶
• https://example.org/_matrix/path/ - unknown/invalid.¶
• https://example.org//_matrix/path - unknown/invalid (domain also can't have a trailing slash).¶
• https://example.org//_matrix/path/ - doubly unknown/invalid.¶

Servers (both hub and participants) MUST implement all endpoints unless otherwise specified.¶

Most endpoints have a version number as part of the path. This version number is that endpoint's version, allowing for breaking changes to be made to the schema of that endpoint. For clarity, the version number is not representative of an API version.¶

13.2.2. Errors

All errors are represented by an error code defined by this document and an accompanied HTTP status code. It is possible for a HTTP status code to map to multiple error codes, and it's possible for an error code to map to multiple HTTP status codes.¶

When a server is returning an error to a caller, it MUST use the most appropriate error response defined by the endpoint. If no appropriate error response is specified, the server SHOULD use M_UNKNOWN as the error code and 500 Internal Server Error as the HTTP status code.¶

Errors are represented as JSON objects, requiring a Content-Type: application/json response header:¶

{
  "errcode": "M_UNKNOWN",
  "error": "Something went wrong."
}

errcode is required and denotes the error code. error is an optional human-readable description of the error. error can be as precise or vague as the responding server desires - the strings in this document are suggestions.¶

Some common error codes are:¶

• M_UNKNOWN - An unknown error has occurred.¶
• M_FORBIDDEN - The caller is not permitted to access the resource. For example, trying to join a room the user does not have an invite for.¶
• M_NOT_JSON - The request did not contain valid JSON. Must be accompanied by a 400 Bad Request HTTP status code.¶
• M_BAD_JSON - The request did contain valid JSON, but it was missing required keys or was malformed in another way. Must be accompanied by a 400 Bad Request HTTP status code.¶
• M_LIMIT_EXCEEDED - Too many requests have been sent. The caller should wait before trying the request again.¶
• M_TOO_LARGE - The request was too large for the receiver to handle.¶

13.2.3. Unsupported Endpoints

If a server receives a request for an unsupported or otherwise unknown endpoint, the server MUST respond with an HTTP 404 Not Found status code and M_UNRECOGNIZED error code. If the request was for a known endpoint, but wrong HTTP method, a 405 Method Not Allowed HTTP status code and M_UNRECOGNIZED error code (Section 13.2.2).¶

13.2.4. Malformed Requests

If a server is expecting JSON in the request body but receives something else, it MUST respond with an HTTP status code of 400 Bad Request and error code M_NOT_JSON (Section 13.2.2). If the request contains JSON, and is for a known endpoint, but otherwise missing required keys or is malformed, the server MUST respond with an HTTP status code of 400 Bad Request and error code M_BAD_JSON (Section 13.2.2). Where possible, error for M_BAD_JSON should describe the missing keys or other parsing error.¶

13.2.5. Transaction Identifiers

Where endpoints use HTTP PUT, it is typical for a "transaction ID" to be specified in the path parameters. This transaction ID MUST ONLY be used for making requests idempotent - if a server receives two (or more) requests with the same transaction ID, it MUST return the same response for each and only process the request body once. It is assumed that requests using the same transaction ID also contain the same request body between calls.¶

A transaction ID only needs to be unique per-endpoint and per-sending server. A server's transaction IDs do not affect requests made by other servers or made to other endpoints by the same server.¶

13.2.6. Rate Limiting

Servers SHOULD implement rate limiting semantics to reduce the risk of being overloaded. Endpoints which support being rate limited are annotated in this document.¶

If a rate limit is encountered, the server MUST respond with an HTTP 429 Too Many Requests status code and M_LIMIT_EXCEEDED error code (Section 13.2.2). If applicable, the server should additionally include a retry_after_ms integer field on the error response to denote how long the caller should wait before retrying, in milliseconds.¶

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "Too many requests. Try again later.",
  "retry_after_ms": 10254
}

The exact rate limit mechanics are left as an implementation detail. A potential approach may be to prevent repeated requests for the same resource at a high rate and ensuring a remote server does not request more than a defined number of resources at a time.¶

13.3.1. GET /.well-known/matrix/server

Used by the server name resolution approach to determine a delegated hostname for a given server. 30x HTTP redirection MUST be followed, though loops SHOULD be avoided. Normal X.509 certificate validation is applied to this endpoint (not the specific validation required by the server name resolution steps) [RFC5280].¶

This endpoint MAY be implemented by servers (it is optional).¶

Rate-limited: No.¶

Authentication required: No.¶

This HTTP endpoint does not specify any request parameters or body.¶

200 OK response:¶

{
   "m.server": "delegated.example.org:8448"
}

m.server is a required response field. Responses SHOULD have a Content-Type HTTP header of application/json, however servers parsing the response should assume that the body is JSON regardless of Content-Type header. Failures in parsing the JSON or otherwise invalid data that prevents parsing MUST NOT result in discovery failure. Instead, the caller is expected to move on to the next step of the name resolution approach.¶

Cache control headers SHOULD be respected on a 200 OK response. Callers SHOULD impose a maximum cache time of 48 hours, regardless of cache control headers. A default of 24 hours SHOULD be used when no cache control headers are present.¶

Error responses (non-200) SHOULD be cached for no longer than 1 hour. Callers SHOULD exponentially back off (to a defined limit) upon receiving repeated error responses.¶

13.4.1. Retrieving Server Keys

A server's signing keys are published under /_matrix/key/v2/server (Section 13.4.1.2) and can be queried through notary servers in two ways: Section 13.4.1.3 and Section 13.4.1.4. Notary servers implicitly call /_matrix/key/v2/server when queried, signing and caching the response for some time. This allows the target server to offline without affecting their previously sent events.¶

The approach used here is borrowed from the Perspectives Project [PerspectivesProject], modified to cover the server's ed25519 keys and to use JSON instead of XML. The advantage of this system is it allows each server to pick which notaries it trusts, and can contact multiple notaries to corroborate the keys returned by any given notary.¶

Servers SHOULD attempt to contact the target server directly before using a notary server.¶

Note that these endpoints operate outside the context of a room: a server does not need to participate in any shared rooms to be used as a notary by another server, and does not need to use the hub as a notary.¶

{
   "server_name": "example.org",
   "valid_until_ts": 1686776437176,
   "m.linearized": true,
   "verify_keys": {
      "ed25519:0": {
         "key": "<unpadded base64 encoded public key>"
      }
   },
   "old_verify_keys": {
      "ed25519:bad": {
         "expired_ts": 1586776437176,
         "key": "<unpadded base64 encoded public key>"
      }
   },
   "signatures": {
      "example.org": {
         "ed25519:0": "<unpadded base64 encoded signature>"
      }
   }
}

{
   "server_keys": [
      {/* server key */}
   ]
}

{
   "server_keys": {
      "example.org": {
         "ed25519:0": {
            "minimum_valid_until_ts": 1686783382189
         }
      }
   }
}

13.5.1. PUT /_matrix/federation/v2/send/:txnId

Sends (L)PDUs (Section 3.5, Section 3.5.1) to another server. The sending server MUST wait for a 200 OK response from the receiver before sending another request with a different :txnId.¶

Implementation note: Currently this endpoint doesn't actually exist. Use PUT /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/send/:txnId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: No.¶

Authentication required: Yes.¶

Path parameters:¶

• :txnId - the transaction ID (Section 13.2.5) for the request.¶

Query parameters: None applicable.¶

Request body:¶

{
   "edus": [{/* TODO: Define EDUs */}],
   "pdus": [
      {/* Either an LPDU or PDU */}
   ]
}

TODO: Describe EDUs.¶

edus are the Ephemeral Data Units to send. If no EDUs are being sent, this field MAY be excluded from the request body. There MUST NOT be more than 100 entries in edus.¶

pdus are the events/PDUs (Section 3.5) and LPDUs (Section 3.5.1) to send to the server. Whether it's an LPDU or PDU depends on the sending server's role in that room: if they are a non-hub server, it will be an LPDU. There MUST NOT be more than 50 entries in pdus.¶

Each event in the pdus array gets processed as such:¶

1. Identify the room ID for the event. The exact format of the event can differ between room versions, however currently this would be done by extracting the room_id property.¶

   1. If that room ID is invalid/not found, the event is rejected.¶
   2. If the server is not participating in the room, the event is dropped/skipped.¶
2. If the event is an LPDU and the receiving server is the hub, the additional PDU fields are appended before continuing.¶
3. If the event is an LPDU and the receiving server is not the hub, the event is dropped/skipped.¶
4. The checks defined by Section 6.1 are performed.¶
5. If the event still hasn't been dropped/rejected, it is appended to the room. For participant servers, this may mean it's queued for sending to local clients.¶

Server implementation authors should note that these steps can be condensed, but are expanded here for specification purposes. For example, an LPDU's signature can/will fail without ever needing to append the PDU fields first - the server can skip some extra work this way.¶

200 OK response:¶

{
   "failed_pdus": {
      "$eventid": {
         "error": "Invalid event format"
      },
      "$eventid": {
         "error": "@alice:example.org cannot send m.room.power_levels"
      }
   }
}

The receiving server MUST NOT send a 200 OK response until all events have been processed. Servers SHOULD NOT block responding to this endpoint on sending accepted events to local clients or other participant servers, as doing so could lead to a lengthy backlog of events waiting to be sent.¶

Sending servers SHOULD apply/expect a timeout and retry the exact same request with the same transaction ID until they see a 200 OK response. If the sending server attempts to send a different transaction ID from the one already in flight, the receiving server MUST respond with a 400 Bad Request HTTP status code and M_BAD_STATE error code (Section 13.2.2). Receiving servers SHOULD continue processing requests to this endpoint event after the sender has disconnected/timed out, but SHOULD NOT process the request multiple times due to the transaction ID (Section 13.2.5).¶

failed_pdus is an object mapping event ID (Section 3.5) to error string. Event IDs are based upon the received object, not the final/complete object. For example, if an LPDU is sent, gets its PDU fields appended, and fails event authorization, then the error would be for the event ID of the LPDU, not the fully-formed PDU. This is to allow the sender to correlate what they sent with errors.¶

The object for each event ID MUST contain an error string field, representing the human-readable reason for an event being rejected.¶

Events which are dropped/ignored or accepted do not appear in failed_pdus.¶

TODO: Should we also return fully-formed PDUs for the LPDUs we received?¶

13.6.1. GET /_matrix/federation/v2/event/:eventId

Retrieves a single event.¶

Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/event/:eventId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :eventId - the event ID (Section 3.5) to retrieve. Note that event IDs are typically reference hashes (Section 10.2) of the event itself, which includes the room ID. This makes event IDs globally unique.¶

Query parameters: None applicable.¶

Request body: None applicable.¶

200 OK response:¶

{
   /* the event */
}

The response body is simply the event (Section 3.5) itself, if the requesting server has reasonable visibility of the event (Section 3.5.3.5.1). When the server can see an event but not the contents, the event is served redacted (Section 9) instead.¶

If the event isn't known to the server, or the requesting server has no reason to know that the event even exists, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 13.2.2) is returned.¶

The returned event MUST be checked before being used by the requesting server (Section 6.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

13.6.2. GET /_matrix/federation/v1/state/:roomId

Retrieves a snapshot of the room state (Section 3.5.2) at the given event. This is typically most useful when a participant server prefers to store minimal information about the room, but still needs to offer context to its clients.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve state in.¶

Query parameters:¶

• event_id (string; required) - The event ID (Section 3.5) to retrieve state at.¶

Request body: None applicable.¶

200 OK response:¶

{
   "auth_chain": [
      {/* event */}
   ],
   "pdus": [
      {/* event */}
   ]
}

The returned room state is in two parts: the pdus, consisting of the events which represent "current state" (Section 3.5.2) prior to considering state changes induced by the event in the original request, and auth_chain, consisting of the events which make up the auth_events (Section 6.4.1) for the pdus and the auth_events of those events, recursively.¶

The auth_chain will eventually stop recursing when it reaches the m.room.create event, as it cannot have any auth_events.¶

For example, if the requested event ID was an m.room.power_levels event, the returned state would be as if the new power levels were not applied.¶

Both auth_chain and pdus contain event objects (Section 3.5).¶

If the requesting server does not have reasonable visibility on the room (Section 3.5.3.5.1), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 13.2.2) is returned. The same error is returned if the event ID doesn't exist in the requested room ID.¶

Note that the requesting server will generally always have visibility of the auth_chain and pdu events, but may not be able to see their contents. In this case, they are redacted (Section 9) before being served.¶

The returned events MUST be checked before being used by the requesting server (Section 6.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

13.6.3. GET /_matrix/federation/v1/state_ids/:roomId

This performs the same function as Section 13.6.2 but returns just the event IDs instead.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve state in.¶

Query parameters:¶

• event_id (string; required) - The event ID (Section 3.5) to retrieve state at.¶

Request body: None applicable.¶

200 OK response:¶

{
   "auth_chain_ids": ["$event1", "$event2"],
   "pdu_ids": ["$event3", "$event4"]
}

See Section 13.6.2 for behaviour. Note that auth_chain becomes auth_chain_ids when using this endpoint, and pdus becomes pdu_ids.¶

13.6.4. GET /_matrix/federation/v2/backfill/:roomId

Retrieves a sliding window history of previous events in a given room.¶

Implementation note: Currently this endpoint doesn't actually exist. Use GET /_matrix/federation/unstable/org.matrix.i-d.ralston-mimi-linearized-matrix.02/backfill/:roomId when testing against other Linearized Matrix implementations. This string may be updated later to account for breaking changes.¶

TODO: Remove implementation notes.¶

Rate-limited: Yes.¶

Authentication required: Yes.¶

Path parameters:¶

• :roomId - the room ID (Section 3.2) to retrieve events from.¶

Query parameters:¶

• v (string; required) - The event ID (Section 3.5) to start backfilling from.¶
• limit (integer; required) - The maximum number of events to return, including v.¶

Request body: None applicable.¶

200 OK response:¶

{
   "pdus": [
      {/* event */}
   ]
}

The number of returned pdus MUST NOT exceed the limit provided by the caller. limit SHOULD have a maximum value imposed by the receiving server. pdus contains the events (Section 3.5) preceeding the requested event ID (v), including v. pdus is ordered from oldest to newest.¶

If the requesting server does not have reasonable visibility on the room (Section 3.5.3.5.1), or either the room ID or event ID don't exist, a 404 Not Found HTTP status code and M_NOT_FOUND error code (Section 13.2.2) is returned. The same error is returned if the event ID doesn't exist in the requested room ID.¶

If the requesting server does have visibility on the returned events, but not their contents, they are redacted (Section 9) before being served.¶

The returned events MUST be checked before being used by the requesting server (Section 6.1). This endpoint MUST NOT return LPDUs (Section 3.5.1), instead treating such events as though they didn't exist.¶

13.7.1. Make and Send Handshake

When a server is already participating in a room, it can use m.room.member (Section 3.5.3.3) events and the /send API (Section 13.5.1) to directly change membership. When the server is not already involved in the room, such as when being invited for the first time, the server needs to "make" an event and "send" it through the hub server to append it to the room.¶

The different processes which use this handshake are:¶

• Rejecting Invites (Section 13.7.2.2)¶
• Joins (Section 13.7.3)¶
• Knocks (Section 13.7.4)¶

The "make" portion of the endpoints take the shape of GET /_matrix/federation/v1/make_CHANGE/:roomId/:userId, where CHANGE is leave, join, or knock (respective to the list above). This endpoint will return a partial LPDU (Section 3.5.1) which needs to be turned into a full LPDU and signed before being sent using POST /_matrix/federation/v3/send_CHANGE/:txnId.¶

The flow for this handshake appears as such:¶

Note that the send_CHANGE step re-checks the event against the auth rules: any amount of time could have passed between the make_CHANGE and send_CHANGE calls.¶

TODO: Describe how the external server is meant to find the hub. Invites work by (usually) trying to contact the server which sent the invite, but knocking is a guess.¶

13.7.2. Invites

When inviting a user belonging to a server already in the room, senders SHOULD use m.room.member (Section 3.5.3.3) events and the /send API (Section 13.5.1). This section's endpoints SHOULD only be used when the target server is not participating in the room already.¶

Note that being invited does not count as the server "participating" in the room. This can mean that while a server has a user with a pending invite in the room, this section's endpoints are needed to send additional invites to other users on the same server.¶

The full invite sequence is:¶

POST /invite is shorthand for Section 13.7.2.1.¶

What causes a user to be considered "ineligible" for an invite is left as an implementation detail. See Section 14 and Section 15 for suggestions on handling user-level privacy controls and spam invites.¶

{
   "event": {/* the event */},
   "invite_room_state": [/* stripped state events */],
   "room_version": "I.1"
}

{
   "pdu": {/* signed fully-formed event */}
}

{
   "event": {/* partial LPDU */},
   "room_version": "I.1"
}

{
   /* LPDU created from make_leave template */
}

{/* deliberately empty object */}

13.7.3. Joins

Joins for users SHOULD be sent directly whenever possible, and otherwise use the "make and send" handshake (Section 13.7.1) approach described here.¶

{
   /* partial LPDU */
}

{
   /* LPDU created from make_join template */
}

{
   "state": [/* events */],
   "auth_chain": [/* events */],
   "event": {/* fully-formed event */}
}

13.7.4. Knocks

To knock on a room is to request an invite to that room. It is not a join, nor is it an invite itself. "Approving" the knock is done by inviting the user, which is typically only allowed by moderators in these rooms. "Denying" the knock is done through kicking (sending a leave membership) or banning the user. If the user is kicked, they may re-send their knock.¶

Senders should note the reason field on m.room.member events (Section 3.5.3.3) to provide context for their knock.¶

To retract a knock, the sending server uses the same APIs as rejecting an invite (Section 13.7.2.2).¶

Where possible, knocks from users SHOULD be sent directly, otherwise using the "make and send" handshake (Section 13.7.1) approach described here.¶

{
   /* partial LPDU */
}

{
   /* LPDU created from make_knock template */
}

{
   "stripped_state": [
      /* stripped state events */
   ]
}

13.9.1. Open Questions

• Should we include /_matrix/federation/v1/version in here? It's used by federation testers, but not really anything else.¶