Hooks, handlers and accumulators
The hooks and handlers mechanism is one of the core architectural features of MongooseIM. It allows for loose coupling between components of the system by calling only those which are available and configured to be used at runtime.
It can be thought of as a simple eventing mechanism notifying about certain things happening in the server. That results in an extensible system with pluggable extra functionality.
To focus our attention, we'll analyze
mod_offline which is responsible for storing messages for delivery to users unavailable at the time of sending.
mod_offline is an implementation of XEP-0203: Delayed Delivery.
Running a hook
ejabberd_sm (ejabberd/MongooseIM session manager) is the module discovering whether the recipient of a message is available or not.
That's where storing the message for later delivery takes place.
It is possible, but not recommended, to save a message in an offline storage by calling
Note that in this example
ejabberd_sm is coupled with
mod_offline was not available, the code would simply crash; if it was misconfigured or turned off, the behaviour would be undefined.
To avoid that coupling and also to enable other (possibly yet to be written) code to carry out some action at this particular moment,
ejabberd_sm would instead call:
1 2 3 4
The extra level of indirection introduced by this call gives the flexibility to determine at runtime what code actually gets run at this point.
offline_message_hook is just the name of the hook (in other words of the event that is being signalled);
Packet are the arguments passed to the handler just as they would in case of the function being called directly;
LServer is the XMPP domain for which this hook is signalled.
Notice: For the clarity of the explanation of the hooks mechanism, the provided code snippets are not exactly taken from the current code. The reasons for it will be described later.
Getting results from handlers
Hook handlers are called by "folding". This means that each handler on a list is passed a set of arguments and an initial value that it then modifies, returns and hands over to the next handler in line.
A simple example would look like this:
1 2 3 4 5
The initial value of the accumulator being passed through the sequence of handlers (in this case an empty list
) is inserted between the XMPP domain
StateData#state.server and handler arguments.
In between the XMPP domain (
StateData#state.server) and handler arguments is the initial value of the accumulator being passed through the sequence of handlers is inserted - in this case an empty list (
If you haven't encountered the term fold before, think of it as reduce (like
Array.reduce) in Ruby-speak, roughly equivalent to the Reduce step in MapReduce, sometimes called accumulate, aggregate or compress.
See Wikipedia for more.
MongooseIM uses a dedicated data structure to accumulate data related to stanza processing (see "Accumulators"). It is instantiated with an incoming stanza, passed along throughout the processing chain, supplied to and returned from certain hook calls, and terminated when stanza is leaving MongooseIM.
If a Mongoose accumulator is passed to a hook, handlers should store their return values in one of 3 ways:
- If it is a one-off value which doesn't need to be passed on along with the accumulator (can be overwritten any time), use
mongoose_acc:set(hook, result, Value, Acc).
- If the value is to be passed on to be reused within the current processing context, use
mongoose_acc:set(Namespace, Key, Value, Acc).
- If the value should be passed on to the recipient's session, pubsub node etc. use
mongoose_acc:set_permanent(Namespace, Key, Value, Acc).
A real life example, then, with regard to
mod_offline is the
resend_offline_messages_hook run in
1 2 3 4 5
Sidenote: something deprecated
In the past you may have found some calls to
ejabberd_hooks:run/3 in the MongooseIM source code.
Under the hood it called the same handlers with
ok as the initial accumulator.
This is deprecated and some day will be removed.
Error handling in hooks
Hooks are meant to decouple modules; in other words, the caller signals that some event took place or that it intends to use a certain feature or a set of features, but how and if those features are implemented is beyond its interest.
For that reason hooks don't use the "let it crash" approach. Instead it is rather like "fire-and-forget", more similar in principle to the
Pid ! signal way.
In practical terms: if a handler throws an error the hook machine logs a message and proceeds to the next handler with an unmodified accumulator.
If there are no handlers registered for a given hook, the
run_fold call simply has no effect.
Sidenote: Code yet to be written
Let's imagine, that when building a minimum viable product we settle on using
mod_offline for delayed delivery of messages to unavailable clients.
However, while the product evolves (or the relevant client software catches up) we might drop
mod_offline in favour of a more sophisticated solution like Message Archive Management which would require a different action to be taken at the same point.
Thanks to loose coupling and
ejabberd_hooks it's possible to turn off
mod_offline and turn on
mod_mam without changing
a single line of code in
The only required change is to the configuration (apart from deploying the new module) which can even be performed at runtime - without restarting the server.
Sidenote: Multiple Domains
A MongooseIM cluster may serve more than one domain at the same time. E.g. it is quite common that services like Multi User Chat or Publish-Subscribe are available as subdomains of the main XMPP domain served by an installation.
Registering hook handlers
In order to store a packet when
offline_message_hook the relevant module must register a handler for this hook.
To attain the runtime configurability the module should register the handlers when it's loaded and unregister them when
That's usually done in, respectively,
Here is the relevant snippet from
It is clearly visible that the handler is added to the
Host corresponds to the
LServer used in the aforementioned call to the
ejabberd_hooks:run_fold, i.e. it's the XMPP domain for which the handler is to be executed.
The handler itself is specified as a module-function pair;
the arity of the function is not specified at the registration nor verified when calling the handler.
This may change in the future, but for now we recommend calling the hooks through the
mongoose_hooks module and checking the arity there when writing a handler.
If the handler expects an incorrect number of arguments it will simply crash.
Multiple handlers may be registered for the same hook. The last argument, 50, is the sequence number of this handler in the handler chain. The higher the number, the later in the sequence the handler will be executed. It's reasonable to keep this number small (e.g. in the range 0-100), though there's no real limit other than the size of the integer type in the Erlang VM.
Pluggability also requires the components to be unpluggable at will.
For that purpose there's the option to unregister a hook handler.
It's done in
mod_offline:stop/1 in a similar fashion to:
The arguments are exactly the same as passed to
Every time a hook is run, a corresponding metric of the same name in the same host is incremented by one.
There are some exceptions though as some metrics were implemented before the generic hook metrics.
List of hooks not updating generic metrics can be found in the
Such skipped hooks update metrics defined in the
The signature of a handler has to follow three rules:
- Correct arity (the number of args passed to
- The first arg is a mutable accumulator (may be
- Returns an accumulator of the same type as the input one.
Let's look at this example, from MongooseIM codebase:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
As seen in this example, a handler receives an accumulator, puts some value into it and returns it for further processing.
There's also one important feature to note: in some cases our handler returns a tuple
This skips calling the latter actions in the handler sequence, while the call to
run_fold returns the Acc.
If a handler returns just an atom
stop, then all later actions are skipped and
Watch out! Different handlers may be registered for the same hook - the priority mechanism orders their execution.
If a handler returns
stop but runs early in the handler chain, it may prevent some other handler from running at all!
That might or might not be intentional.
It may be especially surprising in case of handlers from different modules registered for the same hook.
Always ensure what handlers are registered for a given hook (
grep is your friend) and that you understand their interdependencies.
Hooks list and how to extract it
The following command should give you a list of all the hooks available in MongooseIM:
1 2 3 4 5 6 7 8
ack to find where they're used.
Here are the contents of
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Creating your own hooks
There's no special function or any setup necessary to create a new hook.
The only thing that needs to be done is calling
ejabberd_hooks:run_fold/4 with the name of the new hook and relevant arguments.
However, if you want static code analysis, you should put the new hook inside
mongoose_hooks with a correct type specification.
We've added this module to provide some security and type checking in places where the hooks are run.
This is the way all hooks are called in MongooseIM (see the examples in the hooks description).
Of course, as long as no module registers handlers for a hook, running a
run_fold won't have any effects.
Similar is the case when a module registers handlers for some hook, but that hook is never run in the code. That won't have an effect either.
The following is a self-contained example of a module which both runs and registers a few handlers for a completely new hook.
The handlers are run sequentially using disparate priorities and passing over an accumulator value.
One of the handlers stops the handler execution chain prematurely by returning
It's also possible to try out what happens when the same hook is run with different XMPP domains by passing an argument to
run_custom_hook/1 - we'll see that the handlers are registered for a particular domain only.
At the end, you can see a printout of an accumulator with some debugging info.
To cut the long story short:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
The module is intended to be used from the shell for educational purposes:
1 2 3 4 5 6 7 8 9 10 11 12 13