Clarify event format text in room version specs (#3501)

Split the text about event IDs and event formats into separate sections. This
is largely to make it easier to link to, but I think the resulting text makes
more sense too.
pull/977/head
Richard van der Hoff 3 years ago committed by GitHub
parent 92b29cf8e6
commit f4a0c1aac5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -0,0 +1 @@
Clarifications to sections on event IDs and event formats.

@ -1,19 +0,0 @@
---
toc_hide: true
---
The event ID is the [reference
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using a variation of [Unpadded
Base64](/appendices#unpadded-base64) which replaces the 62nd and
63rd characters with `-` and `_` instead of using `+` and `/`. This
matches [RFC4648's definition of URL-safe
base64](https://tools.ietf.org/html/rfc4648#section-5). Event IDs are
still prefixed with `$` and may result in looking like
`$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.
Just like in room version 3, 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. Room version 3 also changes the format of `auth_events`
and `prev_events` in a PDU.

@ -0,0 +1,7 @@
---
toc_hide: true
---
Events in rooms of this version have the following structure:
{{% definition path="api/server-server/definitions/pdu_v4" %}}

@ -0,0 +1,14 @@
---
toc_hide: true
---
{{% added-in this=true %}} The event ID is the [reference
hash](/server-server-api#calculating-the-reference-hash-for-an-event) of
the event encoded using a variation of [Unpadded
Base64](/appendices#unpadded-base64) which replaces the 62nd and
63rd characters with `-` and `_` instead of using `+` and `/`. This
matches [RFC4648's definition of URL-safe
base64](https://tools.ietf.org/html/rfc4648#section-5).
Event IDs are still prefixed with `$` and may result in looking like
`$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.

@ -49,35 +49,33 @@ 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
{{% added-in this=true %}} 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.
### Event format
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.
When events are sent over federation, the `event_id` field is no longer
included. A server receiving an event should compute the relevant
event ID for itself.
{{% definition path="api/server-server/definitions/pdu_v3" %}}
Additionally, the format of the `auth_events` and `prev_events` fields are
changed: instead of lists of `(event_id, hash)` pairs, they are now plain lists
of event IDs.
These changes to the format of an event mean that servers must be aware of the
version of the room containing an incoming event, so that the event can be
correctly parsed and handled. This is facilitated via changes to the
server-server API (such as the inclusion of `room_version` in the response to
[`GET /_matrix/federation/v1/make_join/{roomId}/{userId}`](/server-server-api/#get_matrixfederationv1make_joinroomiduserid).)
### Changes to APIs
The complete structure of a event in a v3 room is shown below.
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.
{{% definition path="api/server-server/definitions/pdu_v3" %}}
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

@ -46,7 +46,7 @@ being interpretted differently by some reverse proxy software, and
generally made administration harder.
{{% /boxes/rationale %}}
{{% rver-fragment name="v4-event-explainer" %}}
{{% rver-fragment name="v4-event-ids" withVersioning="true" %}}
## Unchanged from v3
@ -75,8 +75,8 @@ completeness.
### Event format
The event format is the same as [room version 3](/rooms/v3#event-ids),
The event format is the same as [room version 3](/rooms/v3#event-format),
however the event IDs in the following example are updated to reflect
the changes in this room version.
{{% definition path="api/server-server/definitions/pdu_v4" %}}
{{% rver-fragment name="v4-event-format" %}}

@ -47,11 +47,13 @@ completeness.
{{% rver-fragment name="v3-handling-redactions" %}}
### Event format
### Event IDs
{{% rver-fragment name="v4-event-ids" %}}
{{% rver-fragment name="v4-event-explainer" %}}
### Event format
{{% definition path="api/server-server/definitions/pdu_v4" %}}
{{% rver-fragment name="v4-event-format" %}}
### Canonical JSON

@ -204,12 +204,14 @@ completeness.
{{% rver-fragment name="v2-state-res" %}}
### Event format
### Event IDs
{{% rver-fragment name="v4-event-ids" %}}
{{% rver-fragment name="v4-event-explainer" %}}
### Event format
{{% definition path="api/server-server/definitions/pdu_v4" %}}
{{% rver-fragment name="v4-event-format" %}}
### Handling redactions
{{% rver-fragment name="v3-handling-redactions" %}}
{{% rver-fragment name="v3-handling-redactions" %}}

@ -191,11 +191,13 @@ completeness.
{{% rver-fragment name="v2-state-res" %}}
### Event format
### Event IDs
{{% rver-fragment name="v4-event-ids" %}}
{{% rver-fragment name="v4-event-explainer" %}}
### Event format
{{% definition path="api/server-server/definitions/pdu_v4" %}}
{{% rver-fragment name="v4-event-format" %}}
### Canonical JSON

Loading…
Cancel
Save