rec: postresolve_ffi docs

Plus fix a formatting issue in policyEventFilter docs.

diff --git a/pdns/recursordist/docs/lua-scripting/ffi.rst b/pdns/recursordist/docs/lua-scripting/ffi.rst
index dd14b6f3609ec602779a339f6208dc0b04d1f8c7..f64eeff30928e894dc85cc21569a1ccbdf76cd91 100644 (file)
--- a/pdns/recursordist/docs/lua-scripting/ffi.rst
+++ b/pdns/recursordist/docs/lua-scripting/ffi.rst
@@ -1,10 +1,10 @@
 Lua FFI API
 ===========
 
-We provide a set of functions available through the LUA FFI library that allow you to interact with the the :func:`gettag_ffi` parameter.
+PowerDNS Recursor provides a set of functions available through the LUA FFI library that allow you to interact with handle passed to :func:`gettag_ffi` and :func:`postresolve_ffi`.
 
-Functions
----------
+Functions for :func:`gettag_ffi`
+--------------------------------
 
 .. function:: pdns_ffi_param_get_qname(pdns_ffi_param_t* ref) -> const char*
 
@@ -132,12 +132,74 @@ Functions
 
 .. function:: pdns_ffi_param_add_meta_single_string_kv(pdns_ffi_param_t* ref, const char* key, const char* val) -> void
 
-    .. versionadded:: 4.6.0
+   .. versionadded:: 4.6.0
 
    This function allows you to add an arbitrary string value for a given key in the ``meta`` field of the produced :doc:`protobuf <../lua-config/protobuf>` log message
 
 .. function:: pdns_ffi_param_add_meta_single_int64_kv(pdns_ffi_param_t *ref, const char* key, int64_t val) -> void
 
-    .. versionadded:: 4.6.0
+   .. versionadded:: 4.6.0
 
    This function allows you to add an arbitrary int value for a given key in the ``meta`` field of the produced :doc:`protobuf <../lua-config/protobuf>` log message
+
+Functions for :func:`postresolve_ffi`
+-------------------------------------
+
+.. versionadded:: 4.7.0
+
+All functions below were added in version 4.7.0.
+
+.. function::  pdns_postresolve_ffi_handle_get_qname(pdns_postresolve_ffi_handle_t* ref) -> const char*
+
+    Get the name queried as a string.
+
+.. function::  pdns_postresolve_ffi_handle_get_qname_raw(pdns_postresolve_ffi_handle_t* ref, const char** qname, size_t* qnameSize) -> void
+
+    Get the name queried (and its size) in DNS wire format.
+
+.. function::  pdns_postresolve_ffi_handle_get_qtype(const pdns_postresolve_ffi_handle_t* ref) -> uint16
+
+    Get the qtype of the query.
+
+.. function::  pdns_postresolve_ffi_handle_get_rcode(const pdns_postresolve_ffi_handle_t* ref) -> uint16
+
+    Get the rcode returned by the resolving process.
+
+.. function::  pdns_postresolve_ffi_handle_set_rcode(const pdns_postresolve_ffi_handle_t* ref, uint16_t rcode) -> void
+
+    Set the rcode to be returned.
+
+.. function::  pdns_postresolve_ffi_handle_get_appliedpolicy_kind(const pdns_postresolve_ffi_handle_t* ref) -> pdns_policy_kind_t
+
+    Get the applied policy.
+
+.. function::  pdns_postresolve_ffi_handle_set_appliedpolicy_kind(pdns_postresolve_ffi_handle_t* ref, pdns_policy_kind_t kind) -> void
+
+    Set the applied policy.
+
+.. function::  pdns_postresolve_ffi_handle_get_record(pdns_postresolve_ffi_handle_t* ref, unsigned int i, pdns_ffi_record_t* record, bool raw) -> bool
+
+    Get a record indexed by i.
+    Returns false if no record is available at index i.
+
+.. function::  pdns_postresolve_ffi_handle_set_record(pdns_postresolve_ffi_handle_t* ref, unsigned int i, const char* content, size_t contentLen, bool raw) -> bool
+
+    Set the record at index i.
+
+.. function::  pdns_postresolve_ffi_handle_clear_records(pdns_postresolve_ffi_handle_t* ref) -> void
+
+    Clear all records.
+
+.. function::  pdns_postresolve_ffi_handle_add_record(pdns_postresolve_ffi_handle_t* ref, const char* name, uint16_t type, uint32_t ttl, const char* content, size_t contentLen, pdns_record_place_t place, bool raw) -> bool
+
+    Add a record to the existing records.
+
+.. function::  pdns_postresolve_ffi_handle_get_authip(pdns_postresolve_ffi_handle_t* ref) -> const char*
+
+    Get a string representation of the IP address of the authoritative server that answered the query.
+    The string might by empty if the address is not available.
+
+.. function::  pdns_postresolve_ffi_handle_get_authip_raw(pdns_postresolve_ffi_handle_t* ref, const void** addr, size_t* addrSize) -> void
+
+    Get the raw IP address (in network byte order) and size of the raw IP address of the authoritative server that answered the query.
+    The string might be empty if the address is not available.

diff --git a/pdns/recursordist/docs/lua-scripting/hooks.rst b/pdns/recursordist/docs/lua-scripting/hooks.rst
index 3eddb15d6bc0dfd4d45ef7bcecfee9fec7666733..3805163b1ecd00cd99a632050ea623947d75e6b8 100644 (file)
--- a/pdns/recursordist/docs/lua-scripting/hooks.rst
+++ b/pdns/recursordist/docs/lua-scripting/hooks.rst
@@ -10,7 +10,7 @@ Queries can be intercepted in many places:
 -  before any filtering policy have been applied (:func:`prerpz`)
 -  before the resolving logic starts to work (:func:`preresolve`)
 -  after the resolving process failed to find a correct answer for a domain (:func:`nodata`, :func:`nxdomain`)
--  after the whole process is done and an answer is ready for the client (:func:`postresolve`)
+-  after the whole process is done and an answer is ready for the client (:func:`postresolve` and its FFI counterpart, :func:`postresolve_ffi`).
 -  before an outgoing query is made to an authoritative server (:func:`preoutquery`)
 -  after a filtering policy hit has occurred (:func:`policyEventFilter`)
 
@@ -151,6 +151,14 @@ Interception Functions
 
   :param DNSQuestion dq: The DNS question to handle
 
+.. function:: postresolve_ffi(handle) -> bool
+
+  .. versionadded:: 4.7.0
+
+  This is the FFI counterpart of :func:`postresolve`.
+  It accepts a single parameter which can be passed to the functions listed in :doc:`ffi`.
+  The accessor functions retrieve and modify various aspects of the answer returned to the client.
+
 .. function:: nxdomain(dq) -> bool
 
   is called after the DNS resolution process has run its course, but ended in an 'NXDOMAIN' situation, indicating that the domain does not exist.
@@ -176,12 +184,14 @@ Interception Functions
 
 .. function:: policyEventFilter(event) -> bool
 
-    .. versionadded:: 4.4.0
+  .. versionadded:: 4.4.0
 
   This hook is called when a filtering policy has been hit, before the decision has been applied, making it possible to change a policy decision by altering its content or to skip it entirely.
   Using the :meth:`event:discardPolicy() <PolicyEvent:discardPolicy>` function, it is also possible to selectively disable one or more filtering policy, for example RPZ zones.
   The return value indicates whether the policy hit should be completely ignored (true) or applied (false), possibly after editing the action to take in that latter case (see :ref:`modifyingpolicydecisions` below). when true is returned, the resolution process will resume as if the policy hit never took place.
 
+  :param PolicyEvent event: The event to handle
+
   As an example, to ignore the result of a policy hit for the example.com domain:
 
   .. code-block:: Lua
@@ -209,9 +219,7 @@ Interception Functions
         return false
       end
 
-  :param :class:`PolicyEvent` event: The event to handle
-
- .. _hook-semantics:
+.. _hook-semantics:
 
 Callback Semantics
 ^^^^^^^^^^^^^^^^^^