doc/lib: updated library doc

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
 

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 <lib_index>` 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 <lib_index>` documentation for the complete overview of the services.
+
+The library offers following services:
+
+- :ref:`Cache <lib_cache>` - MVCC cache interface for retrieving/storing resource records.
+- :ref:`Resolution plan <lib_rplan>` - 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 <lib_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 <lib_api_rplan>` 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 <mod-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