|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
# Backend hooks
|
|
|
|
|
|
|
|
We decided that we need support for hooks in Stork similar to the solution in Kea.
|
|
|
|
|
|
|
|
## Kea hooks - state of the art
|
|
|
|
|
|
|
|
Kea hook is a shared library. Each hook is composed of the following symbols:
|
|
|
|
|
|
|
|
- version - defines the version of Kea code with which the user-library is built, mandatory
|
|
|
|
- load - called when the library is loaded by the server, optional
|
|
|
|
- unload - called when the library is unloaded by the server, optional
|
|
|
|
- multi_threading_compatible - defines the compatibility (or not) of the user-library and a multi-threaded DHCP service, optional
|
|
|
|
|
|
|
|
Additionally, the hook may contain one or more "callout". The "callout" is a function that the Kea calls out.
|
|
|
|
Each callout function has the same signature. It accepts a reference to a `CalloutHandle` object and returns an integer. A value of 0 indicates success; anything else signifies an error. The status return does not affect server processing; the only difference between a success and error code is that if the latter is returned, the server will log an error, specifying both the library and hook that generated it. Effectively the return status provides a quick way for a callout to log error information to the Kea logging system.
|
|
|
|
|
|
|
|
The `CalloutHandle` object provides two methods to get and set the arguments passed to the callout. These methods are called (naturally enough) getArgument and setArgument.
|
|
|
|
|
|
|
|
The hook libraries provide their own log messages and logger instances.
|
|
|
|
|
|
|
|
The `LibraryManager` manages a single hook. It is responsible for calling the main hook functions. Additionally, it registers the callouts in the `HooksManager`. Available hook names are first recorded in the `HookManager` by the `*Hooks` structures. These structures contain the hook indices that are used to call the specific hook. The `LibraryManager` iterates over the hook names and checks if they are available in the shared library. If yes, the hook is added to the list in the `HooksManager`.
|
|
|
|
|
|
|
|
The hooks are independent of the main Kea codebase. There is a single common module. It contains some constants, signatures of primary functions, and `CalloutHandle` class.
|
|
|
|
|
|
|
|
### Strengths and weaknesses
|
|
|
|
|
|
|
|
The main advantage of the Kea design is a separation between the main codebase and hooks. It allows writing hook code without knowledge about the Kea itself. Kea also separates the log messages that making any troubleshooting easier. Another beneficial feature is the easy and bidirectional data exchange between core and hook.
|
|
|
|
A significant disadvantage is weak typing. The compiler cannot test the correctness of the hook signatures because the hook name is stored as a string and the arguments are dynamically retrieved and cast. It is tough to detect if something changed in a complex structure used as an argument. |