wownero/external/unbound/pythonmod/doc/examples/example6.rst

Inplace callbacks
=================

This example shows how to register and use inplace callback functions. These
functions are going to be called just before unbound replies back to a client.
They can perform certain actions without interrupting unbound's execution flow
(e.g. add/remove EDNS options, manipulate the reply).

Two different scenarios will be shown:

- If answering from cache and the client used EDNS option code ``65002`` we
  will answer with the same code but with data ``0xdeadbeef``;
- When answering with a SERVFAIL we also add an empty EDNS option code
  ``65003``.


Key parts
~~~~~~~~~

This example relies on the following functionalities:


Registering inplace callback functions
--------------------------------------

There are four types of inplace callback functions:

- `inplace callback reply functions`_
- `inplace callback reply_cache functions`_
- `inplace callback reply_local functions`_
- `inplace callback reply_servfail functions`_


Inplace callback reply functions
................................

Called when answering with a *resolved* query.

The callback function's prototype is the following:

.. code-block:: python

    def inplace_reply_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
        """Function that will be registered as an inplace callback function.
        It will be called when answering with a resolved query.
        :param qinfo: query_info struct;
        :param qstate: module qstate. It contains the available opt_lists; It
                       SHOULD NOT be altered;
        :param rep: reply_info struct;
        :param rcode: return code for the query;
        :param edns: edns_data to be sent to the client side. It SHOULD NOT be
                     altered;
        :param opt_list_out: the list with the EDNS options that will be sent as a
                             reply. It can be populated with EDNS options;
        :param region: region to allocate temporary data. Needs to be used when we
                       want to append a new option to opt_list_out.
        :return: True on success, False on failure.
        """

.. note:: The function's name is irrelevant.

We can register such function as:

.. code-block:: python

    if not register_inplace_cb_reply(inplace_reply_callback, env, id):
        log_info("python: Could not register inplace callback function.")


Inplace callback reply_cache functions
......................................

Called when answering *from cache*.

The callback function's prototype is the following:

.. code-block:: python

    def inplace_cache_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
        """Function that will be registered as an inplace callback function.
        It will be called when answering from the cache.
        :param qinfo: query_info struct;
        :param qstate: module qstate. None;
        :param rep: reply_info struct;
        :param rcode: return code for the query;
        :param edns: edns_data sent from the client side. The list with the EDNS
                     options is accesible through edns.opt_list. It SHOULD NOT be
                     altered;
        :param opt_list_out: the list with the EDNS options that will be sent as a
                             reply. It can be populated with EDNS options;
        :param region: region to allocate temporary data. Needs to be used when we
                       want to append a new option to opt_list_out.
        :return: True on success, False on failure.
        """

.. note:: The function's name is irrelevant.

We can register such function as:

.. code-block:: python

    if not register_inplace_cb_reply_cache(inplace_cache_callback, env, id):
        log_info("python: Could not register inplace callback function.")


Inplace callback reply_local functions
......................................

Called when answering with *local data* or a *Chaos(CH) reply*.

The callback function's prototype is the following:

.. code-block:: python

    def inplace_local_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
        """Function that will be registered as an inplace callback function.
        It will be called when answering from local data.
        :param qinfo: query_info struct;
        :param qstate: module qstate. None;
        :param rep: reply_info struct;
        :param rcode: return code for the query;
        :param edns: edns_data sent from the client side. The list with the
                     EDNS options is accesible through edns.opt_list. It
                     SHOULD NOT be altered;
        :param opt_list_out: the list with the EDNS options that will be sent as a
                             reply. It can be populated with EDNS options;
        :param region: region to allocate temporary data. Needs to be used when we
                       want to append a new option to opt_list_out.
        :return: True on success, False on failure.
        """

.. note:: The function's name is irrelevant.

We can register such function as:

.. code-block:: python

    if not register_inplace_cb_reply_local(inplace_local_callback, env, id):
        log_info("python: Could not register inplace callback function.")


Inplace callback reply_servfail functions
.........................................

Called when answering with *SERVFAIL*.

The callback function's prototype is the following:

.. code-block:: python

    def inplace_servfail_callback(qinfo, qstate, rep, rcode, edns, opt_list_out, region):
        """Function that will be registered as an inplace callback function.
        It will be called when answering with SERVFAIL.
        :param qinfo: query_info struct;
        :param qstate: module qstate. If not None the relevant opt_lists are
                       available here;
        :param rep: reply_info struct. None;
        :param rcode: return code for the query. LDNS_RCODE_SERVFAIL;
        :param edns: edns_data to be sent to the client side. If qstate is None
                     edns.opt_list contains the EDNS options sent from the client
                     side. It SHOULD NOT be altered;
        :param opt_list_out: the list with the EDNS options that will be sent as a
                             reply. It can be populated with EDNS options;
        :param region: region to allocate temporary data. Needs to be used when we
                       want to append a new option to opt_list_out.
        :return: True on success, False on failure.
        """

.. note:: The function's name is irrelevant.

We can register such function as:

.. code-block:: python

    if not register_inplace_cb_reply_servfail(inplace_servfail_callback, env, id):
        log_info("python: Could not register inplace callback function.")


Testing
~~~~~~~

Run the Unbound server: ::

    root@localhost$ unbound -dv -c ./test-inplace_callbacks.conf

In case you use your own configuration file, don't forget to enable the Python
module::

    module-config: "validator python iterator"

and use a valid script path ::

    python-script: "./examples/inplace_callbacks.py"

On the first query for the nlnetlabs.nl A record we get no EDNS option back:

::

    root@localhost$ dig @localhost nlnetlabs.nl +ednsopt=65002

    ; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost nlnetlabs.nl +ednsopt=65002
    ; (1 server found)
    ;; global options: +cmd
    ;; Got answer:
    ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48057
    ;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 4, ADDITIONAL: 3

    ;; OPT PSEUDOSECTION:
    ; EDNS: version: 0, flags:; udp: 4096
    ;; QUESTION SECTION:
    ;nlnetlabs.nl.                  IN      A

    ;; ANSWER SECTION:
    nlnetlabs.nl.           10200   IN      A       185.49.140.10

    ;; AUTHORITY SECTION:
    nlnetlabs.nl.           10200   IN      NS      ns.nlnetlabs.nl.
    nlnetlabs.nl.           10200   IN      NS      sec2.authdns.ripe.net.
    nlnetlabs.nl.           10200   IN      NS      anyns.pch.net.
    nlnetlabs.nl.           10200   IN      NS      ns-ext1.sidn.nl.

    ;; ADDITIONAL SECTION:
    ns.nlnetlabs.nl.        10200   IN      A       185.49.140.60
    ns.nlnetlabs.nl.        10200   IN      AAAA    2a04:b900::8:0:0:60

    ;; Query time: 813 msec
    ;; SERVER: 127.0.0.1#53(127.0.0.1)
    ;; WHEN: Mon Dec 05 16:15:32 CET 2016
    ;; MSG SIZE  rcvd: 204

When we issue the same query again we get a cached response and the expected
``65002: 0xdeadbeef`` EDNS option:

::

    root@localhost$ dig @localhost nlnetlabs.nl +ednsopt=65002

    ; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost nlnetlabs.nl +ednsopt=65002
    ; (1 server found)
    ;; global options: +cmd
    ;; Got answer:
    ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 26489
    ;; flags: qr rd ra ad; QUERY: 1, ANSWER: 1, AUTHORITY: 4, ADDITIONAL: 3

    ;; OPT PSEUDOSECTION:
    ; EDNS: version: 0, flags:; udp: 4096
    ; OPT=65002: de ad be ef ("....")
    ;; QUESTION SECTION:
    ;nlnetlabs.nl.                  IN      A

    ;; ANSWER SECTION:
    nlnetlabs.nl.           10197   IN      A       185.49.140.10

    ;; AUTHORITY SECTION:
    nlnetlabs.nl.           10197   IN      NS      ns.nlnetlabs.nl.
    nlnetlabs.nl.           10197   IN      NS      sec2.authdns.ripe.net.
    nlnetlabs.nl.           10197   IN      NS      anyns.pch.net.
    nlnetlabs.nl.           10197   IN      NS      ns-ext1.sidn.nl.

    ;; ADDITIONAL SECTION:
    ns.nlnetlabs.nl.        10197   IN      AAAA    2a04:b900::8:0:0:60
    ns.nlnetlabs.nl.        10197   IN      A       185.49.140.60

    ;; Query time: 0 msec
    ;; SERVER: 127.0.0.1#53(127.0.0.1)
    ;; WHEN: Mon Dec 05 16:50:04 CET 2016
    ;; MSG SIZE  rcvd: 212

By issuing a query for a bogus domain unbound replies with SERVFAIL and an
empty EDNS option code ``65003``. *For this example to work unbound needs to be
validating*:

::

    root@localhost$ dig @localhost bogus.nlnetlabs.nl txt

    ; <<>> DiG 9.10.3-P4-Ubuntu <<>> @localhost bogus.nlnetlabs.nl txt
    ; (1 server found)
    ;; global options: +cmd
    ;; Got answer:
    ;; ->>HEADER<<- opcode: QUERY, status: SERVFAIL, id: 19865
    ;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1

    ;; OPT PSEUDOSECTION:
    ; EDNS: version: 0, flags:; udp: 4096
    ; OPT=65003
    ;; QUESTION SECTION:
    ;bogus.nlnetlabs.nl.            IN      TXT

    ;; Query time: 11 msec
    ;; SERVER: 127.0.0.1#53(127.0.0.1)
    ;; WHEN: Mon Dec 05 17:06:01 CET 2016
    ;; MSG SIZE  rcvd: 51


Complete source code
~~~~~~~~~~~~~~~~~~~~
.. literalinclude:: ../../examples/inplace_callbacks.py
    :language: python