You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
---
|
|
title: Room Version 3
|
|
type: docs
|
|
weight: 30
|
|
---
|
|
|
|
This room version builds on [version 2](/rooms/v2) with an improved event
|
|
format.
|
|
|
|
## Client considerations
|
|
|
|
This room version changes the format for event IDs sent to clients.
|
|
Clients should be aware that these event IDs may contain slashes and
|
|
other potentially problematic characters. Clients should be treating
|
|
event IDs as opaque identifiers and should not be attempting to parse
|
|
them into a usable form, just like with other room versions.
|
|
|
|
Clients should expect to see event IDs changed from the format of
|
|
`$randomstring:example.org` to something like
|
|
`$acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk` (note the lack of domain
|
|
and the potentially problematic slash).
|
|
|
|
## Server implementation components
|
|
|
|
{{% boxes/warning %}}
|
|
The information contained in this section is strictly for server
|
|
implementors. Applications which use the Client-Server API are generally
|
|
unaffected by the intricacies contained here. The section above
|
|
regarding client considerations is the resource that Client-Server API
|
|
use cases should reference.
|
|
{{% /boxes/warning %}}
|
|
|
|
Room version 3 uses the state resolution algorithm defined in [room
|
|
version 2](/rooms/v2), and the event format defined here.
|
|
|
|
### Event IDs
|
|
|
|
{{% boxes/rationale %}}
|
|
In other room versions (namely version 1 and 2) the event ID is a
|
|
distinct field from the remainder of the event, which must be tracked as
|
|
such. This leads to complications where servers receive multiple events
|
|
with the same ID in either the same or different rooms where the server
|
|
cannot easily keep track of which event it should be using. By removing
|
|
the use of a dedicated event ID, servers are required to track the
|
|
hashes on an event to determine its ID.
|
|
{{% /boxes/rationale %}}
|
|
|
|
The event ID is the [reference
|
|
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
|
|
the event encoded using [Unpadded
|
|
Base64](/appendices#unpadded-base64), prefixed with `$`. A
|
|
resulting event ID using this approach should look similar to
|
|
`$CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o`.
|
|
|
|
Event IDs should not be sent over federation to servers when the room
|
|
uses this room version. On the receiving end of an event, the server
|
|
should compute the relevant event ID for itself.
|
|
|
|
Additionally, the `auth_events` and `prev_events` have had a format
|
|
change compared to other room versions to make it easier to handle.
|
|
Instead of a tuple of values, they are now plain lists of events.
|
|
|
|
{{% definition path="api/server-server/definitions/pdu_v3" %}}
|
|
|
|
### Changes to APIs
|
|
|
|
Due to the event ID being removed from the event, some APIs need to
|
|
change. All APIs which currently accept an event ID must do so with the
|
|
new format. Servers must append the calculated event ID to all events
|
|
sent to clients where an event ID would normally be expected.
|
|
|
|
Because the format of events has changed, servers must be aware of the
|
|
room version where the event resides so that the server may parse and
|
|
handle the event. The federation API has taken this concern into
|
|
consideration by ensuring that servers are aware of (or can find) the
|
|
room version during a request.
|
|
|
|
### Authorization rules for events
|
|
|
|
The authorization rules for a given event have changed in this room
|
|
version due to the change in event format:
|
|
|
|
- The event no longer needs to be signed by the domain of the event ID
|
|
(as there is no domain in the event ID), but still needs to be
|
|
signed by the sender's domain.
|
|
- In past room versions, redactions were only permitted to enter the
|
|
DAG if the sender's domain matched the domain in the event ID being
|
|
redacted, or the sender had appropriate permissions per the power
|
|
levels. Due to servers now not being able to determine where an
|
|
event came from during event authorization, redaction events are
|
|
always accepted (provided the event is allowed by `events` and
|
|
`events_default` in the power levels). However, servers should not
|
|
apply or send redactions to clients until both the redaction event
|
|
and original event have been seen, and are valid. Servers should
|
|
only apply redactions to events where the sender's domains match, or
|
|
the sender of the redaction has the appropriate permissions per the
|
|
power levels.
|
|
|
|
The remaining rules are the same as [room version
|
|
1](/rooms/v1#authorization-rules).
|