construct/include/ircd/m/room/README.md

## 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::events`.

- 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.