document the two new ffi functions

diff --git a/pdns/recursordist/docs/lua-scripting/ffi.rst b/pdns/recursordist/docs/lua-scripting/ffi.rst
new file mode 100644 (file)
index 0000000..df9264e
--- /dev/null
+++ b/pdns/recursordist/docs/lua-scripting/ffi.rst
@@ -0,0 +1,143 @@
+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.
+
+Functions
+---------
+
+.. function:: pdns_ffi_param_get_qname(pdns_ffi_param_t* ref) -> const char*
+
+   Get the query's qualified name
+
+.. function:: pdns_ffi_param_get_qtype(const pdns_ffi_param_t* ref) -> uint16_t
+
+   Get the query's type
+
+.. function:: pdns_ffi_param_get_remote(pdns_ffi_param_t* ref) -> const char*
+
+   Get the sender's IP address
+
+.. function:: pdns_ffi_param_get_remote_port(const pdns_ffi_param_t* ref) -> uint16_t
+
+   Get the sender's port
+
+.. function:: pdns_ffi_param_get_local(pdns_ffi_param_t* ref) -> const char*
+
+   Get the local IP address the query was received on
+
+.. function:: pdns_ffi_param_get_local_port(const pdns_ffi_param_t* ref) -> uint16_t
+
+   Get the local port the query was received on
+
+.. function:: pdns_ffi_param_get_edns_cs(pdns_ffi_param_t* ref) -> const char*
+
+   Get query's EDNS client subnet
+
+.. function:: pdns_ffi_param_get_edns_cs_source_mask(const pdns_ffi_param_t* ref) -> uint8_t
+
+   Get query's EDNS client subnet mask
+
+.. function:: pdns_ffi_param_get_edns_options(pdns_ffi_param_t* ref, const pdns_ednsoption_t** out) -> size_t
+
+   Get query's EDNS options. Returns the length of the resulting `out` array
+
+.. function:: pdns_ffi_param_get_edns_options_by_code(pdns_ffi_param_t* ref, uint16_t optionCode, const pdns_ednsoption_t** out) -> size_t
+
+   Get query's EDNS option for a given code. Returns the length of the resulting `out` array
+
+.. function:: pdns_ffi_param_get_proxy_protocol_values(pdns_ffi_param_t* ref, const pdns_proxyprotocol_value_t** out) -> size_t
+
+   Get query's proxy protocol values. Returns the length of the resulting `out` array
+
+.. function:: pdns_ffi_param_get_edns_cs_raw(pdns_ffi_param_t* ref, const void** net, size_t* netSize) -> void
+
+   Fill out `net` with query's EDNS client subnet
+
+.. function:: pdns_ffi_param_get_remote_raw(pdns_ffi_param_t* ref, const void** addr, size_t* addrSize) -> void
+
+   Fill out `addr` with sender's IP address
+
+.. function:: pdns_ffi_param_get_qname_raw(pdns_ffi_param_t* ref, const char** qname, size_t* qnameSize) -> void
+
+   Fill out `qname` with query's qualified name
+
+.. function:: pdns_ffi_param_get_local_raw(pdns_ffi_param_t* ref, const void** addr, size_t* addrSize) -> void
+
+   Fill out `addr` with local IP address the query was received on
+
+.. function:: pdns_ffi_param_set_tag(pdns_ffi_param_t* ref, unsigned int tag) -> void
+
+   Tag the query with the given number
+
+.. function:: pdns_ffi_param_add_policytag(pdns_ffi_param_t* ref, const char* name) -> void
+
+   Add the given tag to the query
+
+.. function:: pdns_ffi_param_set_requestorid(pdns_ffi_param_t* ref, const char* name) -> void
+
+   Set query's requestor ID
+
+.. function:: pdns_ffi_param_set_devicename(pdns_ffi_param_t* ref, const char* name) -> void
+
+   Set query's device name
+
+.. function:: pdns_ffi_param_set_deviceid(pdns_ffi_param_t* ref, size_t len, const void* name) -> void
+
+   Set query's device ID
+
+.. function:: pdns_ffi_param_set_routingtag(pdns_ffi_param_t* ref, const char* name) -> void
+
+   Set routing tag which is used as an extra name to identify records in the record cache, see :func:`gettag`
+
+.. function:: pdns_ffi_param_set_variable(pdns_ffi_param_t* ref, bool variable) -> void
+
+   Mark as variable and ensure it’s not inserted into the packetcache
+
+.. function:: pdns_ffi_param_set_ttl_cap(pdns_ffi_param_t* ref, uint32_t ttl) -> void
+
+   Cap the max TTL of the returned records
+
+.. function:: pdns_ffi_param_set_log_query(pdns_ffi_param_t* ref, bool logQuery) -> void
+
+   Turn on/off query logging
+
+.. function:: pdns_ffi_param_set_log_response(pdns_ffi_param_t* ref, bool logResponse) -> void
+
+   Turn on/off response logging
+
+.. function:: pdns_ffi_param_set_rcode(pdns_ffi_param_t* ref, int rcode) -> void
+
+   Set response RCode
+
+.. function:: pdns_ffi_param_set_follow_cname_records(pdns_ffi_param_t* ref, bool follow) -> void
+
+   Instruct the recursor to do a proper resolution in order to follow any CNAME records added
+
+.. function:: pdns_ffi_param_set_extended_error_code(pdns_ffi_param_t* ref, uint16_t code) -> void
+
+   Set extended DNS error info code
+
+.. function:: pdns_ffi_param_set_extended_error_extra(pdns_ffi_param_t* ref, size_t len, const char* extra) -> void
+
+   Set extended DNS error extra text
+
+.. function:: pdns_ffi_param_set_padding_disabled(pdns_ffi_param_t* ref, bool disabled) -> void
+
+   Disable padding
+
+.. function:: pdns_ffi_param_add_record(pdns_ffi_param_t* ref, const char* name, uint16_t type, uint32_t ttl, const char* content, size_t contentSize, pdns_record_place_t place) -> bool
+
+   Adds a record. Returns true if it was correctly added, false otherwise
+
+.. function:: pdns_ffi_param_add_meta_single_string_kv(pdns_ffi_param_t* ref, const char* key, const char* val) -> void
+
+    .. versionadded:: 4.5.3
+
+   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.5.3
+
+   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

diff --git a/pdns/recursordist/docs/lua-scripting/hooks.rst b/pdns/recursordist/docs/lua-scripting/hooks.rst
index 471c355680ab37eadb5ab7132aac81ed77221270..68d1e18f0893a9c85d1fd5104313929ab38bfa79 100644 (file)
--- a/pdns/recursordist/docs/lua-scripting/hooks.rst
+++ b/pdns/recursordist/docs/lua-scripting/hooks.rst
@@ -115,8 +115,8 @@ Interception Functions
       The ability to craft answers was added.
 
     This function is the FFI counterpart of the :func:`gettag` function, and offers the same functionality.
-    It accepts a single, scalable parameter which can be accessed using FFI accessors.
-    Like the non-FFI version, it has the ability to set a tag for the packetcache, policy tags, a routing tag, the :attr:`DNSQuestion.requestorId` and :attr:`DNSQuestion.deviceId`values and to fill the :attr:`DNSQuestion.data` table. It also offers ways to mark the answer as variable so it's not inserted into the packetcache, to set a cap on the TTL of the returned records, and to generate a response by adding records and setting the RCode. It can also instruct the recursor to do a proper resolution in order to follow any `CNAME` records added in this step.
+    It accepts a single, scalable parameter which can be accessed using :doc:`FFI accessors <ffi>`.
+    Like the non-FFI version, it has the ability to set a tag for the packetcache, policy tags, a routing tag, the :attr:`DNSQuestion.requestorId` and :attr:`DNSQuestion.deviceId` values and to fill the :attr:`DNSQuestion.data` table. It also offers ways to mark the answer as variable so it's not inserted into the packetcache, to set a cap on the TTL of the returned records, and to generate a response by adding records and setting the RCode. It can also instruct the recursor to do a proper resolution in order to follow any `CNAME` records added in this step.
 
 .. function:: prerpz(dq) -> bool
 

diff --git a/pdns/recursordist/docs/lua-scripting/index.rst b/pdns/recursordist/docs/lua-scripting/index.rst
index d11c4da8bc201ae6372de67f1aed710c52a30b8b..a93d215055bbe4f9d24b721b04e5b5ddd9c7b232 100644 (file)
--- a/pdns/recursordist/docs/lua-scripting/index.rst
+++ b/pdns/recursordist/docs/lua-scripting/index.rst
@@ -26,6 +26,7 @@ For extra performance, a Just In Time compiled version of Lua called `LuaJIT <ht
     statistics
     logging
     hooks
+    ffi
     functions
     features