mirror of
https://github.com/matrix-construct/construct
synced 2024-10-31 10:58:54 +01:00
99 lines
5 KiB
Markdown
99 lines
5 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 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 (with one exception) and the mere inclusion of files/directories in
|
|
`modules/` does not automatically expose them over HTTP. The exception is
|
|
`modules/static` which is pre-read by the `webroot` module and served 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. The `static` tree is installed to
|
|
`$prefix/share/construct/static`.
|
|
|
|
- `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
|
|
- `static/` contains web assets which are gathered and served under `/`
|
|
- `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.
|
|
|
|
#### 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 "unloadable" and there are
|
|
no "core" modules. All central linkages within libircd (and direct links made
|
|
by other modules) tolerate the unavailability of a module by using weak-pointers
|
|
and throwing exceptions. Unlike the Atheme approach as well, linkage into 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 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.
|
|
|
|
#### 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.
|