chris/ruwuma
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add linebreaks at < 90, fix awkward phrasings

Browse Source
This commit is contained in:
Devin Ragotzy 2021-04-26 21:04:08 -04:00
parent ca01f334d7
commit d533c96502
1 changed files with 33 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
architecture.md
View File

@ -5,10 +5,16 @@ If you want to familiarize yourself with the code base, you are just in the righ
## Overview ## Overview
The state-res crate provides all the necessary algorithms to resolve the state of a room according to the Matrix spec. Given sets of state and the complete authorization chain, a final resolved state is calculated. The state-res crate provides all the necessary algorithms to resolve the state of a
room according to the Matrix spec. Given sets of state and the complete authorization
The state sets (`BTreeMap<(EventType, StateKey), EventId>`) can be the state of a room according to different servers or at different points in time. The authorization chain is the recursive set of all events that authorize the following events. Any event that can be referenced needs to be available in the `event_map` argument, or the call fails. The `StateResolution` struct keeps no state and is only a collection of associated functions. chain, a final resolved state is calculated.
The state sets (`BTreeMap<(EventType, StateKey), EventId>`) can be the state of a room
according to different servers or at different points in time. The authorization chain
is the recursive set of all events that authorize events that come after.
Any event that can be referenced needs to be available in the `event_map` argument,
or the call fails. The `StateResolution` struct keeps no state and is only a
collection of associated functions.
## Code Map ## Code Map
@ -16,31 +22,46 @@ This section talks briefly about important files and data structures.
### `error` ### `error`
An enum representing all possible error cases in state-res. An enum representing all possible error cases in state-res. Most of the variants are
Most of the variants are passing information of failures from other libraries except `Error::NotFound`. The `NotFound` variant is the error when an event used in state resolution was not in the `event_map`. passing information of failures from other libraries except `Error::NotFound`.
The `NotFound` variant is used whan an event was not in the `event_map`.
### `event_auth` ### `event_auth`
This module contains all the logic needed to authenticate and verify events. The main function for authentication is `auth_check`. There are a few checks that happen to every event and specific checks for some state events. This module contains all the logic needed to authenticate and verify events.
The main function for authentication is `auth_check`. There are a few checks
that happen to every event and specific checks for some state events.
Each event is authenticated against the state before the event.
The state is built iterativly with each event being applied to the state and
the next checked before being added.
**Note:** Any type of event can be check, not just state events. **Note:** Any type of event can be check, not just state events.
### `room_version` ### `room_version`
`RoomVersion` holds information about each room version and is generated from `RoomVersionId`. During authentication, an event may be verified differently based on the room version. The `RoomVersion` keeps track of these differences. `RoomVersion` holds information about each room version and is generated from
`RoomVersionId`. During authentication, an event may be verified differently based
on the room version. The `RoomVersion` keeps track of these differences.
### `state_event` ### `state_event`
A trait `Event` that allows the state-res library to abstract over the type of an event. This avoids a lot of unnecessary conversions and gives more flexibility to users. A trait `Event` that allows the state-res library to abstract over the type of an event.
This avoids a lot of unnecessary conversions and gives more flexibility to users.
### `lib` ### `lib`
All the associated functions of `StateResolution` that are needed to resolve state live here. Everything that is used by `resolve` is exported so users have access to the algorithms. All the associated functions of `StateResolution` that are needed to resolve state live
here. Everything that is used by `resolve` is exported giving users access to the pieces
of the algorithm.
**Note:** only state events (events that have a state_key field) are allowed to participate in resolution. **Note:** only state events (events that have a state_key field) are allowed to
participate in resolution.
## Testing ## Testing
state-res has three main test types, event sorting, event authentication, and state resolution. State resolution tests the whole system. Start by setting up a room with events and check the resolved state after adding conflicting events. Event authentication checks that an event passes or fails based on some initial state. Event sorting tests that given a DAG of events, the events can be predictably sorted. state-res has three main test types, event sorting, event authentication, and state
resolution. State resolution tests the whole system. Start by setting up a room with
events and check the resolved state after adding conflicting events.
Event authentication checks that an event passes or fails based on some initial state.
Event sorting tests that given a DAG of events, the events can be predictably sorted.