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.