From: Marek VavruĊĦa Date: Sun, 12 Apr 2015 19:55:20 +0000 (+0200) Subject: doc/lib: updated library doc X-Git-Tag: v1.0.0-beta1~250^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=14780a2d0d6ea3bf781df942738fde1608a2e17a;p=thirdparty%2Fknot-resolver.git doc/lib: updated library doc --- diff --git a/doc/lib.rst b/doc/lib.rst index 9091a70e2..e61cb2066 100644 --- a/doc/lib.rst +++ b/doc/lib.rst @@ -2,43 +2,8 @@ .. include:: ../lib/README.rst -Library layout --------------- - -The library as described provides basic services for name resolution, which should cover the usage. -The following part is for those who are planning to hack on the library or develop modules, to give -you an idea about the API and the library layout. - -Name resolution -~~~~~~~~~~~~~~~ - -.. _lib_rplan: - -Resolution plan -~~~~~~~~~~~~~~~ - -.. _lib_cache: - -Cache -~~~~~ - -.. _lib_nameservers: - -Nameservers -~~~~~~~~~~~ - -.. _lib_modules: - -Modules -~~~~~~~ - -Utilities -~~~~~~~~~ - -.. _lib_api: - API reference -------------- +============= .. doxygengroup:: resolution :project: libkresolve @@ -54,6 +19,8 @@ API reference .. doxygengroup:: nameservers :project: libkresolve +.. _lib_api_modules: + .. doxygengroup:: modules :project: libkresolve diff --git a/lib/README.rst b/lib/README.rst index 7213951fb..7af22e492 100644 --- a/lib/README.rst +++ b/lib/README.rst @@ -3,22 +3,126 @@ Knot DNS Resolver library ************************* Requirements ------------- +============ * libknot_ 2.0 (Knot DNS high-performance DNS library.) -Overview --------- +Library layout +============== + +.. contents:: + :depth: 1 + :local: + +The library as described provides basic services for name resolution, which should cover the usage. +The following part is for those who are planning to hack on the library or develop modules, to give +you an idea about the API and the library layout. + +Name resolution +--------------- + +.. _lib_rplan: + +Resolution plan +--------------- + +.. _lib_cache: + +Cache +----- + +.. _lib_nameservers: + +Nameservers +----------- + +Utilities +~~~~~~~~~ + +.. warning:: Work in progress. Resolving a name -~~~~~~~~~~~~~~~~ +---------------- .. note:: Migrating from ``getaddrinfo`` -Using cache -~~~~~~~~~~~ +Using getdns API +---------------- + +.. note:: These are not the droids you're looking for, move along. + +.. _lib-layers: + +Writing layers +============== + +The resolver :ref:`library ` leverages the `processing API`_ 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 :c:func:`iterate_layer`, and the :c:func:`itercache_layer`. -Loading modules -~~~~~~~~~~~~~~~ +*Note* |---| This is only crash-course in the library internals, see the resolver :ref:`library ` documentation for the complete overview of the services. + +The library offers following services: + +- :ref:`Cache ` - MVCC cache interface for retrieving/storing resource records. +- :ref:`Resolution plan ` - 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. +- :ref:`Nameservers ` - Reputation database of nameservers, this serves as an aid for nameserver choice. + +A processing layer is going to be called by the query resolution driver for each query, +so you're going to work with :ref:`struct kr_layer_param ` 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: + +.. code-block:: c + + int consume(knot_layer_t *ctx, knot_pkt_t *pkt) + { + struct kr_layer_param *param = ctx->data; + struct kr_query *query = kr_rplan_current(param->rplan); + } + +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 :ref:`Static hints ` for example). + +.. code-block:: c + + int produce(knot_layer_t *ctx, knot_pkt_t *pkt) + { + struct kr_layer_param *param = ctx->data; + struct kr_query *cur = kr_rplan_current(param->rplan); + + /* Query can be satisfied locally. */ + if (can_satisfy(cur)) { + /* This flag makes the resolver move the query + * to the "resolved" list. */ + query->resolved = true; + return KNOT_STATE_DONE; + } + + /* Pass-through. */ + return ctx->state; + } + +It is possible to not only act during the query resolution, but also to view the complete resolution plan afterwards. +This is useful for analysis-type tasks, or *"on-resolution"* hooks. + +.. code-block:: c + + int finish(knot_layer_t *ctx) + { + struct kr_layer_param *param = ctx->data; + struct kr_rplan *rplan = param->rplan; + + /* Print the query sequence with start time. */ + char qname_str[KNOT_DNAME_MAXLEN]; + struct kr_query *qry = NULL + WALK_LIST(qry, rplan->resolved) { + knot_dname_to_str(qname_str, qry->sname, sizeof(qname_str)); + printf("%s at %u\n", qname_str, qry->timestamp); + } + + return ctx->state; + } .. _libknot: https://gitlab.labs.nic.cz/labs/knot/tree/master/src/libknot +.. _`processing API`: https://gitlab.labs.nic.cz/labs/knot/tree/master/src/libknot/processing + +.. |---| unicode:: U+02014 .. em dash