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

Add more info to lib and state_event sections, fix english bugs

Browse Source
This commit is contained in:
Devin Ragotzy 2021-04-27 15:39:20 -04:00
parent d533c96502
commit 29fd085de7
1 changed files with 18 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
architecture.md
View File

@ -16,6 +16,13 @@ Any event that can be referenced needs to be available in the `event_map` argume
or the call fails. The `StateResolution` struct keeps no state and is only a or the call fails. The `StateResolution` struct keeps no state and is only a
collection of associated functions. collection of associated functions.
## Important Terms
- **event** In state-res this refers to a **P**ersistent **D**ata **U**nit which
represents the event and keeps metadata used for resolution
- **state resolution** The process of calculating the final state of a DAG from
conflicting input DAGs
## Code Map ## Code Map
This section talks briefly about important files and data structures. This section talks briefly about important files and data structures.
@ -24,7 +31,7 @@ This section talks briefly about important files and data structures.
An enum representing all possible error cases in state-res. Most of the variants are An enum representing all possible error cases in state-res. Most of the variants are
passing information of failures from other libraries except `Error::NotFound`. passing information of failures from other libraries except `Error::NotFound`.
The `NotFound` variant is used whan an event was not in the `event_map`. The `NotFound` variant is used when an event was not in the `event_map`.
### `event_auth` ### `event_auth`
@ -32,8 +39,8 @@ 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 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. that happen to every event and specific checks for some state events.
Each event is authenticated against the state before the event. 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 state is built iteratively with each successive event being checked against
the next checked before being added. the current state then 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.
@ -45,22 +52,24 @@ 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. A trait called `Event` that allows the state-res library to take any PDU type the user
This avoids a lot of unnecessary conversions and gives more flexibility to users. supplies. The main `StateResolution::resolve` function can resolve any user-defined
type that satisfies `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 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 here. The focus is `StateResolution::resolve`, given a DAG and new events
of the algorithm. `resolve` calculates the end state of the DAG. 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 **Note:** only state events (events that have a state_key field) are allowed to
participate in resolution. participate in resolution.
## Testing ## Testing
state-res has three main test types, event sorting, event authentication, and state 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 resolution. State resolution tests the whole system. Start by setting up a room with
events and check the resolved state after adding conflicting events. 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 authentication checks that an event passes or fails based on some initial state.