Updated documentation of cookies module.

doc/modules.rst

@@ -21,4 +21,4 @@ Knot DNS Resolver modules
 .. include:: ../modules/ketcd/README.rst
 .. include:: ../modules/dns64/README.rst
 .. include:: ../modules/renumber/README.rst
-.. include:: ../modules/cookiectl/README.rst
+.. include:: ../modules/cookies/README.rst

modules/cookies/README.rst

-.. _mod-cookiectl:
+.. _mod-cookies:
 
 DNS Cookies
 -----------
 
-The module is used for configuring the :rfc:`7873` DNS cookies functionality behaviour.
+The module performs most of the :rfc:`7873` DNS cookies functionality. Its main purpose is to check the cookies of inbound queries and responses. It is also used to alter the behaviour of the cookie functionality.
 
 Example Configuration
 ^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: lua
 
-	-- Load the module.
-	modules = { 'cookiectl' }
+	-- Load the module before the 'iterate' layer.
+	modules = {
+	        'cookies < iterate'
+	}
 
 	-- Configure the client part of the resolver. Set 8 bytes of the client
 	-- secret and choose the hashing algorithm to be used.
-	cookiectl.config( { ['client_secret'] = { 0, 1, 2, 3, 4, 5, 6, 7 },
-	                    ['client_cookie_alg'] = 'FNV-64' } )
+	cookies.config( { ['client_secret'] = { 0, 1, 2, 3, 4, 5, 6, 7 },
+	                  ['client_cookie_alg'] = 'FNV-64' } )
 
 	-- Configure the server part of the resolver. Sets a string to be used
 	-- as server secret. Also chooses the hashing algorithm to be used.
-	cookiectl.config( { ['server_secret'] = 'secret key',
-	                    ['server_cookie_alg'] = 'FNV-64' } )
+	cookies.config( { ['server_secret'] = 'secret key',
+	                  ['server_cookie_alg'] = 'FNV-64' } )
 
 	-- Enable client cookie functionality. (Add cookies into outbound
 	-- queries.)
-	cookiectl.config( { ['client_enabled'] = true } )
+	cookies.config( { ['client_enabled'] = true } )
 
 	-- Enable server cookie functionliaty. (Handle cookies in inbound
 	-- requests.)
-	cookiectl.config( { ['server_enabled'] = true } )
+	cookies.config( { ['server_enabled'] = true } )
 
-.. tip:: If you want to change several parameters regarding the client or server configuration then do it within a single ``cookiectl.config()`` invocation.
+.. tip:: If you want to change several parameters regarding the client or server configuration then do it within a single ``cookies.config()`` invocation.
+
+.. warning:: The module must be loaded before any other module that has direct influence on query processing and response generation. The module must be able to intercept an incoming query before the processing of the actual query starts. It must also be able to check the cookies of inbound responses and eventually discard them before they are handled by other functional units.
 
 Properties
 ^^^^^^^^^^
@@ -47,6 +51,6 @@ Dependencies
 ^^^^^^^^^^^^
 
 * `Nettle <https://www.lysator.liu.se/~nisse/nettle/>`_ required for HMAC-SHA256
-* `dns-cookies-wip branch of libknot <https://gitlab.labs.nic.cz/labs/knot/tree/dns-cookies-wip>`_ for DNS cookies handling
+* development version of `libknot (master branch) <https://gitlab.labs.nic.cz/labs/knot/tree/master>`_ for DNS cookies handling
 
 .. warning:: Libknot is dropping its processing API in latest development versions. However, this should not be a big deal as only some structures have been in usage by the resolver code.