From: Petr Špaček <petr.spacek@nic.cz>
Date: Thu, 16 Aug 2018 17:41:44 +0000 (+0200)
Subject: WIP: docs
X-Git-Tag: v3.0.0~1^2~6
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=14a4d8cdfbf33092063f5edaefc9f2ba3ff099e2;p=thirdparty%2Fknot-resolver.git

WIP: docs
---

diff --git a/daemon/README.rst b/daemon/README.rst
index 935a4f360..46a8a0785 100644
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -866,9 +866,22 @@ daemons or manipulated from other processes, making for example synchronised loa
 
 .. function:: cache.clear([name], [exact_name], [rr_type], [chunk_size], [callback])
 
-  Purge cache records.
+     Purge cache records matching specified criteria. There are two specifics:
 
-  :return: ``bool`` (success of removing all in one go)
+     * To reliably remove **negative** cache entries you need to clear subtree with the whole zone. E.g. to clear negative cache entries for (formerly non-existing) record `www.example.com. A` you need to flush whole subtree starting at zone apex, e.g. `example.com.` [#]_.
+     * This operation is an asynchonous and might not be yet finished when call to ``cache.clear()`` function returns. Result is indicated return value. You can use custom callback to wait for operation to finish.
+
+  :rtype: table
+  :return: ``count`` field is always present, other fields are optional.
+
+  =========== ===========
+  Key         Description
+  =========== ===========
+  count       number of items removed from cache by this call
+  not_apex    indicates that cleared subtree is not cached as zone apex; proofs of non-existence were not removed
+  subtree     hint where zone apex lies (this is guess from cache content, might not be accurate)
+  chunk_limit indicates that more than ``chunk_size`` needs to be cleared, clearing will continue in callback
+  =========== ===========
 
   :param string name: if the name isn't provided, whole cache is purged
         (and any other parameters are disregarded).
@@ -902,6 +915,7 @@ daemons or manipulated from other processes, making for example synchronised loa
      (which are used for aggressive non-existence proofs)
      will be removed only for zones whose **apex** is at or below the specified name.
 
+.. [#] This is a consequence of DNSSEC negative cache which relies on proofs of non-existence on various owner nodes. It is impossible to efficiently flush part of DNS zones signed with NSEC3.
 
 Timers and events
 ^^^^^^^^^^^^^^^^^
diff --git a/daemon/lua/sandbox.lua b/daemon/lua/sandbox.lua
index 7280bce1a..13914718c 100644
--- a/daemon/lua/sandbox.lua
+++ b/daemon/lua/sandbox.lua
@@ -226,6 +226,8 @@ cache.clear = function (name, exact_name, rr_type, chunk_size, callback)
 				event.after(1, function ()
 						cache.clear(cbname, cbexact_name, cbrr_type, cbchunk_size, cbself)
 					end)
+			else
+				log('[cache] asynchonous clear finished: ' .. table_print(cberrors))
 			end
 			return cberrors
 		end