Self sign-up has been disabled due to increased spam activity. If you want to get access, please send an email to a project owner (preferred) or at gitlab(at)nic(dot)cz. We apologize for the inconvenience.
The resolver library[^lib] leverages the [processing API][processing] from the libknot to separate packet processing code
The resolver [library][lib] leverages the [processing API][processing] from the libknot to separate packet processing code
into layers. In order to keep the core library sane and coverable, there are only two built-in layers:
the [iterator](lib/layer/iterate.c), and the [cache](lib/layer/itercache.c). The resolver context however can
load shared libraries on runtime, which allows us to build and register external modules as well.
...
...
@@ -14,13 +14,224 @@ There is a plan for Lua scriptables, but it's not implemented yet.
## Available services
*Note*— This is only crash-course in the library internals, see the resolver [library][lib] documentation for the complete overview of the services.
<aname="services"></a>
The library offers following services:
-[cache](lib/cache.h) - MVCC cache interface for retrieving/storing resource records.
-[rplan](lib/rplan.h) - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query.
This contains information about the queries, nameserver choice, timing information, answer and its class.
-[nsrep](lib/nsrep.h) - Reputation database of nameservers, this serves as an aid for nameserver choice.
If you're going to publish a layer in your module, it's going to be called by the query resolution driver for each query,
so you're going to work with [`struct kr_layer_param`](lib/layer.h) as your per-query context. This structure contains pointers to
resolution context, resolution plan and also the final answer. You're likely to retrieve currently solved query from the query plan:
This is only passive processing of the incoming answer. If you want to change the course of resolution, say satisfy a query from a local cache before the library issues a query to the nameserver, you can use states (see the [modules/hints](lib/layer/itercache.c) for example).
The `module_` corresponds to the module name, if the module name is `hints`, then the prefix for constructor would be `hints_init()`.
This doesn't apply for Go, as it for now always implements `main` and requires capitalized first letter in order to export its symbol.
### How does the module get loaded
The [resolution context](lib/context.h) holds loaded modules for current context. A module can be registered with `kr_context_register()`, which triggers module constructor *immediately* after the load. Module destructor is automatically called when the resolution context closes.
If the module exports a layer implementation, it is automatically discovered by [resolver](lib/resolve.h) on resolution init and plugged in. The order in which the modules are registered corresponds to the call order of layers.
### Writing a module in C
As almost all the functions are optional, the minimal module looks like this:
```c
#include"lib/module.h"
/* Convenience macro to declare module API. */
KR_MODULE_EXPORT(mymodule);
```
Let's define an observer thread for the module as well. It's going to be stub for the sake of brevity,
but you can for example create a condition, and notify the thread from query processing by declaring
module layer (see the [Available services](#services)).
```c
staticvoid*observe(void*arg)
{
/* ... do some observing ... */
}
intmymodule_init(structkr_module*module)
{
/* Create a thread and start it in the background. */
This example shows how a module can run in the background, this enables you to, for example, observe
and publish data about query resolution.
### Writing a module in Go
[^lib]:See the Knot DNS Resolver library [documentation](lib/README.md).
*Note*— At the moment only a limited subset of Go is supported. The reason is that the Go functions must run inside the goroutines, and *presume* the garbage collector and scheduler are running in the background.
[GCCGO][gccgo] compiler can build dynamic libraries, and also allow us to bootstrap basic Go runtime, including a trampoline to call Go functions.
The problem with the `layer()` and callbacks is that they're called from C threads, that Go runtime has no knowledge of.
Thus neither garbage collection or spawning routines can work. The solution could be to register C threads to Go runtime,
or have each module to run inside its world loop and use IPC instead of callbacks — alas neither is implemented at the moment, but may be in the future.
The Go modules also use CGO to interface C resolver library, and to declare layers with function pointers, which are [not present in Go][golang-syntax]. Each module must be the `main` package, here's a minimal example:
```go
packagemain
/*
#include "lib/module.h"
*/
import"C"
import"unsafe"
funcApi()C.uint32_t{
returnC.KR_MODULE_API
}
```
In order to integrate with query processing, you have to declare a helper function with function pointers to the
the layer implementation. Since the code prefacing `import "C"` is expanded in headers, you need the `static inline` trick
to avoid multiple declarations. Here's how the preface looks like:
```go
/*
#include "lib/module.h"
#include "lib/layer.h"
//! Trampoline for Go callbacks, note that this is going to work
//! with ELF only, this is hopefully going to change in the future
extern int Begin(knot_layer_t *, void *) __asm__ ("main.Begin");
extern int Finish(knot_layer_t *) __asm__ ("main.Finish");
