mirror of
https://github.com/matrix-construct/construct
synced 2024-12-11 08:02:59 +01:00
88 lines
4 KiB
Markdown
88 lines
4 KiB
Markdown
## Matrix Room Interface
|
|
|
|
The headers in this directory as well as `../room.h` comprise the API for
|
|
Matrix rooms. These interfaces may conduct IO for both the local database
|
|
and the network; many calls may block an ircd::ctx for these purposes.
|
|
|
|
A room is composed from a timeline of events. We use several key-value
|
|
tables as the database for room in addition to the raw event data itself.
|
|
|
|
- room_events
|
|
This is the timeline for room events. We sort the keys of this table by
|
|
an event's `depth`. This table allows us to scan the room's events as
|
|
a collection. See: `m::room::messages`.
|
|
|
|
- room_state
|
|
This is the present state table for a room. We sort the keys of this table
|
|
by `(type,state_key)`. See: `m::room::state`.
|
|
|
|
- room_joined
|
|
This is the present joined members list. It is technically redundant to that
|
|
aspect of the room_state table but it is more efficient for us to maintain
|
|
a separate table. See: `m::room::origins` which uses this table. Other
|
|
interfaces are internally optimized by this table for some calls.
|
|
|
|
- room_head
|
|
This is the collection of forward extremities (unreferenced) for a room. This
|
|
is a fast-moving table that would otherwise be just a list in RAM; however
|
|
persisting this through the database prevents recalculating it on startup.
|
|
|
|
- state_node
|
|
This is a key-value store of nodes in a b-tree which is how we efficiently
|
|
represent the state of a room at any past event. See: `m::state` subsystem.
|
|
Note that `m::state` should not be confused with `m::room::state`. The latter
|
|
is the user interface to room state which you are probably looking for; the
|
|
former is the actual implementation of the b-tree and low-level details.
|
|
|
|
|
|
### Sending & Transmission
|
|
|
|
The write interface for rooms is aggregated almost entirely in the index
|
|
header `../room.h`. These calls all converge on a single function `commit`
|
|
which sends a partial event to a room via `m::vm` evaluation.
|
|
|
|
These calls all take a `room` structure as an argument which will be further
|
|
explained in the Reading section. For now know that the `room` argument is
|
|
lightweight and trivially constructed from a `room_id`. It can take a pointer
|
|
to `m::vm::eval` options which offer extensive control over the transmission
|
|
process.
|
|
|
|
All of the transmitting calls will block an `ircd::ctx` but the extent to
|
|
which they do is configurable via the eval options. All of the calls return
|
|
an `event::id::buf` of the event which they just committed to the room.
|
|
|
|
Above the lowest-level `commit()` function there are two mid-level `send()`
|
|
suites. One suite creates and sends a state event to the room, the other
|
|
creates and sends a non-state event. The overloads are distinguished by an
|
|
extra state_key argument for the former.
|
|
|
|
Above the mid-level `send()` suites there is an accumulation of higher-level
|
|
convenience functions, like `message()` and `join()` et al.
|
|
|
|
### Reading & Access
|
|
|
|
The rest of these interfaces are read-only interfaces which present aspects of
|
|
the room as efficiently as possible.
|
|
|
|
##### m::room
|
|
|
|
The principal structure is `m::room` in `room/room.h`. There are no ways to
|
|
change an actual room through this interface, but an instance can be used with
|
|
calls that do. Instances of `room` are lightweight, maintaining a reference to
|
|
a `room_id` and an optional `event_id`. The data behind those references must
|
|
stay in scope for the duration of the `room` instance.
|
|
|
|
When a `room` instance is used either for reading or writing, the `event_id`
|
|
indicates a cursory position in the room to conduct operations. The room will
|
|
be represented at that `event_id`. If no `event_id` is specified, the room
|
|
will be represented at the latest "present" state; note the present state of
|
|
a room is subject to change between calls.
|
|
|
|
The `room` class interface offers a convenience frontend which brings together
|
|
the basic elements of the `room::messages` and `room::state` interfaces. These
|
|
have different characteristics.
|
|
|
|
#### Other interfaces
|
|
|
|
The remainder of `room/` is comprised of specialized interfaces which operate
|
|
efficiently and friendly for their specific purpose.
|