State resolution and checks on incoming PDUs according to the Matrix specification.

When creating or receiving a PDU (or event), a server must check whether it is valid and how it affects the room state. The purpose of this crate is to provide functions that solve that.

Supported room versions

Only room versions enforcing canonical JSON (introduced with room version 6) are supported.

Room versions 1 through 5 are supported on a best effort basis:

• The authorization rules should work for most events but some unconventional JSON encoding of values might fail to deserialize while still considered to be valid by other implementations.
• The state resolution algorithm from room version 1 is not implemented.

Homeservers using this crate should not advertise support for those room versions.

Checks performed on receipt of a PDU

This crate used with ruma-signatures should allow to perform all the necessary checks on receipt of a PDU.

To respect the Matrix specification, the following functions should be called for a PDU:

1. [check_pdu_format()] - The event should be dropped on error.
2. [ruma_signatures::verify_event()] - The event should be dropped on error. The PDU should be redacted before checking the authorization rules if the result is Verified::Signatures.
3. [check_state_independent_auth_rules()] - The event should be rejected on error.
4. [check_state_dependent_auth_rules()] - This function must be called 3 times:
   1. With the auth_events for the state, the event should be rejected on error.
   2. With the state before the event, the event should be rejected on error.
   3. With the current state of the room, the event should be "soft failed" on error.

Room State Resolution

Because of the distributed nature of Matrix, homeservers might not receive all events in the same order, which might cause the room state to diverge temporarily between homeservers. The purpose of [state resolution] is to make sure that all homeservers arrive at the same room state given the same events.

The [resolve()] function allows to do that. It takes an iterator of state maps and applies the proper state resolution algorithm for the current room version to output the map of events in the current room state.

Event helper types

The types from ruma-events use strict deserialization rules according to their definition in the specification, which means that they also validate fields that are not checked when receiving a PDU. Since it is not appropriate for servers to reject an event that passes those checks, this crate provides helper types in the events module, built around the Event trait, to deserialize lazily a handful of fields from the most common state events. Since these are the same types used for checking the authorization rules, they are guaranteed to not perform extra validation on unvalidated fields.

The types from ruma-events are still appropriate to be used to create a new event, or to validate an event received from a client.

ruma-state-res

State resolution and checks on incoming PDUs according to the Matrix specification that can be used by server code.