An eturnal module adds functionality to the eturnal server. It is to be named mod_foo, where foo describes the added functionality. The module may export start/0, stop/0, handle_event/2, and options/0 functions.

If a start/0 callback is exported, it must return ok or {ok, Events}, where Events is either a single event() or a list of events() the module is interested in. Currently, the following events may be triggered: stun_query, turn_session_start, turn_session_stop, and protocol_error.

If a start/0 function is exported and subscribes to one or more events, a handle_event/2 callback must be exported as well. It is called with the event() name as the first argument and an info() map with related data as the second. The contents of that map depend on the event. Note that the handle_event/2 function is executed in the context of the process handling the STUN/TURN session, so it should never block. If it might, and/or if it needs some state, one or more handler processes must be created.

The options/0 callback returns an options() tuple with two elements. The first is a map of module configuration options, where the keys are the option() names and the values are functions that validate the option values. Those functions are returned by the yval library, see the documentation for the list of available validators. The second element is a list of optional tuples to specify any {required, [Options]} and/or {defaults, #{Option => Value}}. For example:

   options() ->
       {#{threshold => yval:pos_int()},
        [{defaults,
         #{threshold => 42}}]}.

The option values are queried by calling eturnal_module:get_opt/2 with the module name as the first and the option() name as the second argument. Note that the lookup is very efficient, so there's no point in saving option values into some state. If the module has no configuration options, the options/0 function may be omitted.

The optional stop/0 callback must return ok. Note that the start/0 and stop/0 functions might not just be called on eturnal startup and shutdown, but also on configuration reloads.

If the module depends on other applications, those must be added to the rebar.config file, but not to the app file. They are to be started by calling eturnal_module:ensure_deps/2, where the first argument is the module name and the second is a list of dependency names. Note that there's no need to list transitive dependencies.

The module is enabled by adding its configuration to the modules section of eturnal's configuration file as described in doc/overview.edoc. The module configuration options are to be documented in that file as well.