Commit b52fb759 authored by Petr Špaček's avatar Petr Špaček

Merge branch 'bindings-split' into 'master'

split code and docs for lua bindings into smaller files

See merge request !765
parents 0f962b7b 9b5a9c1a
Pipeline #45191 failed with stages
in 11 minutes and 12 seconds
This diff is collapsed.
/* Copyright (C) 2019 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
#pragma once
#include <lua.h>
/** Make all the bindings accessible from the lua state,
* .i.e. define those lua tables. */
void kr_bindings_register(lua_State *L);
This diff is collapsed.
Cache configuration
^^^^^^^^^^^^^^^^^^^
The default cache in Knot Resolver is persistent with LMDB backend, this means that the daemon doesn't lose
the cached data on restart or crash to avoid cold-starts. The cache may be reused between cache
daemons or manipulated from other processes, making for example synchronized load-balanced recursors possible.
.. function:: cache.open(max_size[, config_uri])
:param number max_size: Maximum cache size in bytes.
:return: ``true`` if cache was opened
Open cache with a size limit. The cache will be reopened if already open.
Note that the max_size cannot be lowered, only increased due to how cache is implemented.
.. tip:: Use ``kB, MB, GB`` constants as a multiplier, e.g. ``100*MB``.
As of now, the built-in backend with URI ``lmdb://`` allows you to change the cache directory.
Example:
.. code-block:: lua
cache.open(100 * MB, 'lmdb:///var/cache/knot-resolver')
.. envvar:: cache.size
Set the cache maximum size in bytes. Note that this is only a hint to the backend,
which may or may not respect it. See :func:`cache.open()`.
.. code-block:: lua
cache.size = 100 * MB -- equivalent to `cache.open(100 * MB)`
.. envvar:: cache.current_size
Get the maximum size in bytes.
.. code-block:: lua
print(cache.current_size)
.. envvar:: cache.storage
Set the cache storage backend configuration, see :func:`cache.backends()` for
more information. If the new storage configuration is invalid, it is not set.
.. code-block:: lua
cache.storage = 'lmdb://.'
.. envvar:: cache.current_storage
Get the storage backend configuration.
.. code-block:: lua
print(cache.storage)
.. function:: cache.backends()
:return: map of backends
The cache supports runtime-changeable backends, using the optional :rfc:`3986` URI, where the scheme
represents backend protocol and the rest of the URI backend-specific configuration. By default, it
is a ``lmdb`` backend in working directory, i.e. ``lmdb://``.
Example output:
.. code-block:: lua
[lmdb://] => true
.. function:: cache.count()
:return: Number of entries in the cache. Meaning of the number is an implementation detail and is subject of change.
.. function:: cache.close()
:return: ``true`` if cache was closed
Close the cache.
.. note:: This may or may not clear the cache, depending on the cache backend.
.. function:: cache.stats()
.. warning:: Cache statistics are being reworked. Do not rely on current behavior.
Return table of statistics, note that this tracks all operations over cache, not just which
queries were answered from cache or not.
Example:
.. code-block:: lua
print('Insertions:', cache.stats().insert)
.. function:: cache.max_ttl([ttl])
:param number ttl: maximum cache TTL in seconds (default: 6 days)
.. KR_CACHE_DEFAULT_TTL_MAX ^^
:return: current maximum TTL
Get or set maximum cache TTL.
.. note:: The `ttl` value must be in range `(min_ttl, 4294967295)`.
.. warning:: This settings applies only to currently open cache, it will not persist if the cache is closed or reopened.
.. code-block:: lua
-- Get maximum TTL
cache.max_ttl()
518400
-- Set maximum TTL
cache.max_ttl(172800)
172800
.. function:: cache.min_ttl([ttl])
:param number ttl: minimum cache TTL in seconds (default: 5 seconds)
.. KR_CACHE_DEFAULT_TTL_MIN ^^
:return: current maximum TTL
Get or set minimum cache TTL. Any entry inserted into cache with TTL lower than minimal will be overridden to minimum TTL. Forcing TTL higher than specified violates DNS standards, use with care.
.. note:: The `ttl` value must be in range `<0, max_ttl)`.
.. warning:: This settings applies only to currently open cache, it will not persist if the cache is closed or reopened.
.. code-block:: lua
-- Get minimum TTL
cache.min_ttl()
0
-- Set minimum TTL
cache.min_ttl(5)
5
.. function:: cache.ns_tout([timeout])
:param number timeout: NS retry interval in milliseconds (default: :c:macro:`KR_NS_TIMEOUT_RETRY_INTERVAL`)
:return: current timeout
Get or set time interval for which a nameserver address will be ignored after determining that it doesn't return (useful) answers.
The intention is to avoid waiting if there's little hope; instead, kresd can immediately SERVFAIL or immediately use stale records (with :ref:`serve_stale <mod-serve_stale>` module).
.. warning:: This settings applies only to the current kresd process.
.. function:: cache.get([domain])
This function is not implemented at this moment.
We plan to re-introduce it soon, probably with a slightly different API.
.. function:: cache.clear([name], [exact_name], [rr_type], [chunk_size], [callback], [prev_state])
Purge cache records matching specified criteria. There are two specifics:
* To reliably remove **negative** cache entries you need to clear subtree with the whole zone. E.g. to clear negative cache entries for (formerly non-existing) record `www.example.com. A` you need to flush whole subtree starting at zone apex, e.g. `example.com.` [#]_.
* This operation is asynchronous and might not be yet finished when call to ``cache.clear()`` function returns. Return value indicates if clearing continues asynchronously or not.
:param string name: subtree to purge; if the name isn't provided, whole cache is purged
(and any other parameters are disregarded).
:param bool exact_name: if set to ``true``, only records with *the same* name are removed;
default: false.
:param kres.type rr_type: you may additionally specify the type to remove,
but that is only supported with ``exact_name == true``; default: nil.
:param integer chunk_size: the number of records to remove in one round; default: 100.
The purpose is not to block the resolver for long.
The default ``callback`` repeats the command after one millisecond
until all matching data are cleared.
:param function callback: a custom code to handle result of the underlying C call.
Its parameters are copies of those passed to `cache.clear()` with one additional
parameter ``rettable`` containing table with return value from current call.
``count`` field contains a return code from :func:`kr_cache_remove_subtree()`.
:param table prev_state: return value from previous run (can be used by callback)
:rtype: table
:return: ``count`` key is always present. Other keys are optional and their presence indicate special conditions.
* **count** *(integer)* - number of items removed from cache by this call (can be 0 if no entry matched criteria)
* **not_apex** - cleared subtree is not cached as zone apex; proofs of non-existence were probably not removed
* **subtree** *(string)* - hint where zone apex lies (this is estimation from cache content and might not be accurate)
* **chunk_limit** - more than ``chunk_size`` items needs to be cleared, clearing will continue asynchronously
Examples:
.. code-block:: lua
-- Clear whole cache
> cache.clear()
[count] => 76
-- Clear records at and below 'com.'
> cache.clear('com.')
[chunk_limit] => chunk size limit reached; the default callback will continue asynchronously
[not_apex] => to clear proofs of non-existence call cache.clear('com.')
[count] => 100
[round] => 1
[subtree] => com.
> worker.sleep(0.1)
[cache] asynchonous cache.clear('com', false) finished
-- Clear only 'www.example.com.'
> cache.clear('www.example.com.', true)
[round] => 1
[count] => 1
[not_apex] => to clear proofs of non-existence call cache.clear('example.com.')
[subtree] => example.com.
.. [#] This is a consequence of DNSSEC negative cache which relies on proofs of non-existence on various owner nodes. It is impossible to efficiently flush part of DNS zones signed with NSEC3.
/* Copyright (C) 2015-2019 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
#include "daemon/bindings/impl.h"
#include "daemon/worker.h"
#include <unistd.h>
#include <uv.h>
static void event_free(uv_timer_t *timer)
{
struct worker_ctx *worker = timer->loop->data;
lua_State *L = worker->engine->L;
int ref = (intptr_t) timer->data;
luaL_unref(L, LUA_REGISTRYINDEX, ref);
free(timer);
}
static void event_callback(uv_timer_t *timer)
{
struct worker_ctx *worker = timer->loop->data;
lua_State *L = worker->engine->L;
/* Retrieve callback and execute */
lua_rawgeti(L, LUA_REGISTRYINDEX, (intptr_t) timer->data);
lua_rawgeti(L, -1, 1);
lua_pushinteger(L, (intptr_t) timer->data);
int ret = execute_callback(L, 1);
/* Free callback if not recurrent or an error */
if (ret != 0 || (uv_timer_get_repeat(timer) == 0 && uv_is_active((uv_handle_t *)timer) == 0)) {
if (!uv_is_closing((uv_handle_t *)timer)) {
uv_close((uv_handle_t *)timer, (uv_close_cb) event_free);
}
}
}
static void event_fdcallback(uv_poll_t* handle, int status, int events)
{
struct worker_ctx *worker = handle->loop->data;
lua_State *L = worker->engine->L;
/* Retrieve callback and execute */
lua_rawgeti(L, LUA_REGISTRYINDEX, (intptr_t) handle->data);
lua_rawgeti(L, -1, 1);
lua_pushinteger(L, (intptr_t) handle->data);
lua_pushinteger(L, status);
lua_pushinteger(L, events);
int ret = execute_callback(L, 3);
/* Free callback if not recurrent or an error */
if (ret != 0) {
if (!uv_is_closing((uv_handle_t *)handle)) {
uv_close((uv_handle_t *)handle, (uv_close_cb) event_free);
}
}
}
static int event_sched(lua_State *L, unsigned timeout, unsigned repeat)
{
uv_timer_t *timer = malloc(sizeof(*timer));
if (!timer) {
format_error(L, "out of memory");
lua_error(L);
}
/* Start timer with the reference */
uv_loop_t *loop = uv_default_loop();
uv_timer_init(loop, timer);
int ret = uv_timer_start(timer, event_callback, timeout, repeat);
if (ret != 0) {
free(timer);
format_error(L, "couldn't start the event");
lua_error(L);
}
/* Save callback and timer in registry */
lua_newtable(L);
lua_pushvalue(L, 2);
lua_rawseti(L, -2, 1);
lua_pushlightuserdata(L, timer);
lua_rawseti(L, -2, 2);
int ref = luaL_ref(L, LUA_REGISTRYINDEX);
/* Save reference to the timer */
timer->data = (void *) (intptr_t)ref;
lua_pushinteger(L, ref);
return 1;
}
static int event_after(lua_State *L)
{
/* Check parameters */
int n = lua_gettop(L);
if (n < 2 || !lua_isnumber(L, 1) || !lua_isfunction(L, 2)) {
format_error(L, "expected 'after(number timeout, function)'");
lua_error(L);
}
return event_sched(L, lua_tonumber(L, 1), 0);
}
static int event_recurrent(lua_State *L)
{
/* Check parameters */
int n = lua_gettop(L);
if (n < 2 || !lua_isnumber(L, 1) || !lua_isfunction(L, 2)) {
format_error(L, "expected 'recurrent(number interval, function)'");
lua_error(L);
}
return event_sched(L, 0, lua_tonumber(L, 1));
}
static int event_cancel(lua_State *L)
{
int n = lua_gettop(L);
if (n < 1 || !lua_isnumber(L, 1)) {
format_error(L, "expected 'cancel(number event)'");
lua_error(L);
}
/* Fetch event if it exists */
lua_rawgeti(L, LUA_REGISTRYINDEX, lua_tointeger(L, 1));
if (!lua_istable(L, -1)) {
lua_pushboolean(L, false);
return 1;
}
/* Close the timer */
lua_rawgeti(L, -1, 2);
uv_handle_t *timer = lua_touserdata(L, -1);
if (!uv_is_closing(timer)) {
uv_close(timer, (uv_close_cb) event_free);
}
lua_pushboolean(L, true);
return 1;
}
static int event_reschedule(lua_State *L)
{
int n = lua_gettop(L);
if (n < 2 || !lua_isnumber(L, 1) || !lua_isnumber(L, 2)) {
format_error(L, "expected 'reschedule(number event, number timeout)'");
lua_error(L);
}
/* Fetch event if it exists */
lua_rawgeti(L, LUA_REGISTRYINDEX, lua_tointeger(L, 1));
if (!lua_istable(L, -1)) {
lua_pushboolean(L, false);
return 1;
}
/* Reschedule the timer */
lua_rawgeti(L, -1, 2);
uv_handle_t *timer = lua_touserdata(L, -1);
if (!uv_is_closing(timer)) {
if (uv_is_active(timer)) {
uv_timer_stop((uv_timer_t *)timer);
}
int ret = uv_timer_start((uv_timer_t *)timer, event_callback, lua_tointeger(L, 2), 0);
if (ret != 0) {
event_cancel(L);
lua_pushboolean(L, false);
return 1;
}
}
lua_pushboolean(L, true);
return 1;
}
static int event_fdwatch(lua_State *L)
{
/* Check parameters */
int n = lua_gettop(L);
if (n < 2 || !lua_isnumber(L, 1) || !lua_isfunction(L, 2)) {
format_error(L, "expected 'socket(number fd, function)'");
lua_error(L);
}
uv_poll_t *handle = malloc(sizeof(*handle));
if (!handle) {
format_error(L, "out of memory");
lua_error(L);
}
/* Start timer with the reference */
int sock = lua_tonumber(L, 1);
uv_loop_t *loop = uv_default_loop();
#if defined(__APPLE__) || defined(__FreeBSD__)
/* libuv is buggy and fails to create poller for
* kqueue sockets as it can't be fcntl'd to non-blocking mode,
* so we pass it a copy of standard input and then
* switch it with real socket before starting the poller
*/
int decoy_fd = dup(STDIN_FILENO);
int ret = uv_poll_init(loop, handle, decoy_fd);
if (ret == 0) {
handle->io_watcher.fd = sock;
}
close(decoy_fd);
#else
int ret = uv_poll_init(loop, handle, sock);
#endif
if (ret == 0) {
ret = uv_poll_start(handle, UV_READABLE, event_fdcallback);
}
if (ret != 0) {
free(handle);
format_error(L, "couldn't start event poller");
lua_error(L);
}
/* Save callback and timer in registry */
lua_newtable(L);
lua_pushvalue(L, 2);
lua_rawseti(L, -2, 1);
lua_pushlightuserdata(L, handle);
lua_rawseti(L, -2, 2);
int ref = luaL_ref(L, LUA_REGISTRYINDEX);
/* Save reference to the timer */
handle->data = (void *) (intptr_t)ref;
lua_pushinteger(L, ref);
return 1;
}
int kr_bindings_event(lua_State *L)
{
static const luaL_Reg lib[] = {
{ "after", event_after },
{ "recurrent", event_recurrent },
{ "cancel", event_cancel },
{ "socket", event_fdwatch },
{ "reschedule", event_reschedule },
{ NULL, NULL }
};
register_lib(L, "event", lib);
return 1;
}
Timers and events
^^^^^^^^^^^^^^^^^
The timer represents exactly the thing described in the examples - it allows you to execute closures
after specified time, or event recurrent events. Time is always described in milliseconds,
but there are convenient variables that you can use - ``sec, minute, hour``.
For example, ``5 * hour`` represents five hours, or 5*60*60*100 milliseconds.
.. function:: event.after(time, function)
:return: event id
Execute function after the specified time has passed.
The first parameter of the callback is the event itself.
Example:
.. code-block:: lua
event.after(1 * minute, function() print('Hi!') end)
.. function:: event.recurrent(interval, function)
:return: event id
Similar to :func:`event.after()`, periodically execute function after ``interval`` passes.
Example:
.. code-block:: lua
msg_count = 0
event.recurrent(5 * sec, function(e)
msg_count = msg_count + 1
print('Hi #'..msg_count)
end)
.. function:: event.reschedule(event_id, timeout)
Reschedule a running event, it has no effect on canceled events.
New events may reuse the event_id, so the behaviour is undefined if the function
is called after another event is started.
Example:
.. code-block:: lua
local interval = 1 * minute
event.after(1 * minute, function (ev)
print('Good morning!')
-- Halven the interval for each iteration
interval = interval / 2
event.reschedule(ev, interval)
end)
.. function:: event.cancel(event_id)
Cancel running event, it has no effect on already canceled events.
New events may reuse the event_id, so the behaviour is undefined if the function
is called after another event is started.
Example:
.. code-block:: lua
e = event.after(1 * minute, function() print('Hi!') end)
event.cancel(e)
Watch for file descriptor activity. This allows embedding other event loops or simply
firing events when a pipe endpoint becomes active. In another words, asynchronous
notifications for daemon.
.. function:: event.socket(fd, cb)
:param number fd: file descriptor to watch
:param cb: closure or callback to execute when fd becomes active
:return: event id
Execute function when there is activity on the file descriptor and calls a closure
with event id as the first parameter, status as second and number of events as third.
Example:
.. code-block:: lua
e = event.socket(0, function(e, status, nevents)
print('activity detected')
end)
e.cancel(e)
Asynchronous function execution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `event` package provides a very basic mean for non-blocking execution - it allows running code when activity on a file descriptor is detected, and when a certain amount of time passes. It doesn't however provide an easy to use abstraction for non-blocking I/O. This is instead exposed through the `worker` package (if `cqueues` Lua package is installed in the system).
.. function:: worker.coroutine(function)
Start a new coroutine with given function (closure). The function can do I/O or run timers without blocking the main thread. See cqueues_ for documentation of possible operations and synchronization primitives. The main limitation is that you can't wait for a finish of a coroutine from processing layers, because it's not currently possible to suspend and resume execution of processing layers.
Example:
.. code-block:: lua
worker.coroutine(function ()
for i = 0, 10 do
print('executing', i)
worker.sleep(1)
end
end)
.. function:: worker.sleep(seconds)
Pause execution of current function (asynchronously if running inside a worker coroutine).
When daemon is running in forked mode, each process acts independently. This is good because it reduces software complexity and allows for runtime scaling, but not ideal because of additional operational burden.
For example, when you want to add a new policy, you'd need to add it to either put it in the configuration, or execute command on each process independently. The daemon simplifies this by promoting process group leader which is able to execute commands synchronously over forks.
Example:
.. code-block:: lua
worker.sleep(1)
.. function:: map(expr)
Run expression synchronously over all forks, results are returned as a table ordered as forks. Expression can be any valid expression in Lua.
Example:
.. code-block:: lua
-- Current instance only
hostname()
localhost
-- Mapped to forks
map 'hostname()'
[1] => localhost
[2] => localhost
-- Get worker ID from each fork
map 'worker.id'
[1] => 0
[2] => 1
-- Get cache stats from each fork
map 'cache.stats()'
[1] => {
[hit] => 0
[delete] => 0
[miss] => 0
[insert] => 0
}
[2] => {
[hit] => 0
[delete] => 0
[miss] => 0
[insert] => 0
}
/* Copyright (C) 2019 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
#include <lua.h>
#include <string.h>
/* Each of these just creates the correspondingly named lua table of functions. */
int kr_bindings_cache (lua_State *L); /* ./cache.c */
int kr_bindings_event (lua_State *L); /* ./event.c */
int kr_bindings_modules (lua_State *L); /* ./modules.c */
int kr_bindings_net (lua_State *L); /* ./net.c */
int kr_bindings_worker (lua_State *L); /* ./worker.c */
static void lualib(lua_State *L, const char *name, lua_CFunction lib_cb)
{
#if LUA_VERSION_NUM >= 502
luaL_requiref(L, name, lib_cb, 1);
lua_pop(L, 1);
#else
lib_cb(L);
#endif
}
void kr_bindings_register(lua_State *L)
{
lualib(L, "modules", kr_bindings_modules);
lualib(L, "net", kr_bindings_net);
lualib(L, "cache", kr_bindings_cache);
lualib(L, "event", kr_bindings_event);
lualib(L, "worker", kr_bindings_worker);
}
int format_error(lua_State* L, const char *err)
{
lua_Debug d;
lua_getstack(L, 1, &d);
/* error message prefix */
lua_getinfo(L, "Sln", &d);
if (strncmp(d.short_src, "[", 1) != 0) {
lua_pushstring(L, d.short_src);
lua_pushstring(L, ":");
lua_pushnumber(L, d.currentline);
lua_pushstring(L, ": error: ");
lua_concat(L, 4);
} else {
lua_pushstring(L, "error: ");
}
/* error message */
lua_pushstring(L, err);
lua_concat(L, 2);
return 1;
}
/* Copyright (C) 2015-2017 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
/* Copyright (C) 2015-2019 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
......@@ -14,18 +14,17 @@
along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
/**
* Bindings to engine services, see \a https://www.lua.org/manual/5.2/manual.html#luaL_newlib for the reference.
*/
#pragma once