mirror of
https://github.com/matrix-construct/construct
synced 2024-09-05 16:25:26 +02:00
124 lines
6.2 KiB
Markdown
124 lines
6.2 KiB
Markdown
# IRCd Module Tree
|
|
|
|
This directory contains dynamically loadable functionality to libircd. These
|
|
modules are not mere extensions -- they provide essential application
|
|
functionality, but are not always required to be directly linked in libircd
|
|
proper. Most application-specific functionality (i.e "business logic") is
|
|
contained in modules within this tree. At the time of this writing, a
|
|
significant amount of matrix functionality is still contained within libircd
|
|
proper, but it is intended that as many definitions as possible are pushed out
|
|
into modules.
|
|
|
|
#### Layout
|
|
|
|
The `modules/` directory is primarily shaped the same as the HTTP resource
|
|
tree in which most of its modules register themselves in. This is **not**
|
|
automatic and the mere inclusion of files/directories in `modules/`
|
|
does not automatically expose them over HTTP.
|
|
|
|
Note that the installation layout is not the same as the development source
|
|
layout (i.e in git). Upon installation, the module tree is collapsed into a
|
|
single directory and installed into `$prefix/lib/modules/construct/$directory_$module.so`;
|
|
this may be subject to improvement.
|
|
|
|
- `client/` contains resource handlers for the `/_matrix/client/` API
|
|
- `federation/` contains resource handlers for the `/_matrix/federation/` API
|
|
- `key/` contains resource handlers for the `/_matrix/key/` API
|
|
- `media/` contains resource handlers for the `/_matrix/media/` API
|
|
- `js/` contains modules specific to the unreleased javascript embedding.
|
|
- `s_` modules provide utility to the server's operation.
|
|
- `m_` modules implement protocol logic for matrix event types.
|
|
- `vm_` modules provide the processing logic for matrix events.
|
|
|
|
#### Approach
|
|
|
|
We use a hybrid system to build modules with two techniques:
|
|
|
|
- Self-contained shared objects loaded for explicit import and export
|
|
of their symbols. This is the classical module which is safely loaded, unloaded
|
|
and accessed at any time via the `ircd::mods::import` system. This approach is
|
|
preferred for the majority of module and extension cases. Definitions in these
|
|
modules are not declared in `include/ircd` unless a "thunk" definition inside
|
|
libircd contains am `ircd::mods::import` calling out to the module (this is not
|
|
generated; developer must place this).
|
|
|
|
- "core" modules which directly implement symbols declared in `include/ircd`
|
|
headers. When this type of module is not loaded those headers declare an
|
|
undefined symbol and accesses will immediately crash. This approach is used
|
|
when large interfaces are implemented by modules and individual imports
|
|
defined in libircd are too cumbersome. This involves global binding made
|
|
possible by the dynamic linker. This approach is satisfactory because of
|
|
C++ symbol namespacing and modern compiler and linker controls. These modules
|
|
*can* still be unloaded (and are during shutdown) but only after every other
|
|
module which has accessed its symbols has also been unloaded. At this time,
|
|
we have no access or control over that reference system and the reasons for
|
|
a failure to unload may not be immediately clear or easy to trace.
|
|
|
|
#### Loading
|
|
|
|
Modules may be automatically loaded based on their prefix. Certain prefixes
|
|
are sought by libircd for auto-loading, arbitrarily (i.e there is no magic
|
|
autoloading prefix; see: `ircd/m/m.cc` for explicit prefixes). A module may
|
|
also be loaded when an attempt is made to call into it (i.e with `m::import`
|
|
or low-level with `ircd::mods::*`). Furthermore, a module may be loaded by
|
|
the console `mod` command suite, specifically `mod load`. Otherwise the
|
|
module is not loaded.
|
|
|
|
#### Unloading
|
|
|
|
Unlike previous incarnations of IRCd, every module is [eventually] "unloadable"
|
|
and the notion of a "core" module is modernized based on the dynamic linker
|
|
technology available.
|
|
|
|
Many central linkages within libircd (and direct links made by other modules)
|
|
are imports which tolerate the unavailability of a module by using weak-pointers
|
|
and throwing exceptions. Unlike the Atheme approach as well, importing from a
|
|
module does not prevent unloading due to dependency; the unloading of a module is
|
|
propagated to linksites through the weak_ptr's dependency graph and exceptions
|
|
are thrown from the link upon next use.
|
|
|
|
Furthermore, modules are free to leverage the ircd::ctx system to wait
|
|
synchronously for events which are essential for a clean load or unload, even
|
|
during static initialization and destruction. This is a useful feature which
|
|
allows all modules to be robustly loadable and unloadable at **any time**
|
|
and **every time** in an intuitive manner.
|
|
|
|
No modules used through imports in this system "stick" whether by accident or
|
|
on purpose upon unload. Though we all know that dlclose() does not guarantee
|
|
a module is actually unloaded, we expend the extra effort to ensure there is
|
|
no reason why dlclose() would not unload the module. This static destruction
|
|
of a module is verified and alarms will go off if it is actually "stuck" and
|
|
the developer *must* fix this.
|
|
|
|
## Getting started
|
|
|
|
The header `mods/mapi.h` is specific to modules and included for modules in
|
|
addition to the core `ircd.h`. Both of these are included automatically
|
|
via the compiler's command-line and the developer does not have to `#include`
|
|
either in the module.
|
|
|
|
Every loadable module requires a static `ircd::mapi::header` with the explicit
|
|
name of `IRCD_MODULE`. This is an object which will be sought by the module
|
|
loader in libircd. Nothing else is required.
|
|
|
|
#### Developer's Approach
|
|
|
|
The ideal module in this system is one that is self-contained in that its only
|
|
interface is through "registrations" to various facilities provided by libircd.
|
|
The module can still freely read and write to state within libircd or other
|
|
modules.
|
|
|
|
- An example of such is an HTTP resource (see: ircd/resource.h) registration
|
|
of a URL to handle incoming HTTP requests.
|
|
|
|
- Another example is a Matrix Event Hook (see: ircd/m/hook.h) to process
|
|
matrix events.
|
|
|
|
Next is a module providing definitions and making them available through
|
|
exposition (i.e `extern "C"`). In this approach, function definitions are
|
|
provided in the module but a "central interface" may be provided by libircd.
|
|
That central interface is tolerant of the function call failing when the module
|
|
is not available (or automatically tries to load it, see: ircd/m/import.h and
|
|
ircd/mods/*.h etc).
|
|
|
|
Note that many modules use any of these approaches at the same time.
|