Zeek Table<->Brokerstore: cleanup, documentation, small fixes

This commit adds script/c++ documentation and fixes a few loose ends.
It also adds tests for corner cases and massively improves error
messages.

This also actually introduces type-compatibility checking and introduces
a new attribute that lets a user override this if they really know what
they are doing. I am not quite sure if we should really let that stay in
- but it can be very convenient to have this functionality.

One test is continuing to fail - the expiry test is very flaky. This is,
I think, caused by delays of the broker store forwarding. I am unsure if
we can actually do anything about that.

scripts/base/frameworks/broker/store.zeek

@@ -25,8 +25,14 @@ export {
 	## A negative/zero value indicates to never buffer commands.
 	const default_clone_mutation_buffer_interval = 2min &redef;
 
+	## If set to true, the current node is the master node for broker stores
+	## backing zeek tables. By default this value will be automatically set to
+	## true in standalone mode, or on the manager node of a cluster. This value
+	## should not typically be changed manually.
 	const auto_store_master = T &redef;
 
+	## The directory used for storing persistent database files when using brokerstore
+	## backed zeek tables.
 	const auto_store_db_directory = "." &redef;
 
 	## Whether a data store query could be completed or not.

scripts/base/frameworks/cluster/broker-stores.zeek

@@ -1,11 +1,23 @@
+##! This script deals with the cluster parts of broker backed zeek tables.
+##! It makes sure that the master store is set correctly and that clones
+##! are automatically created on the non-manager nodes.
+
+# Note - this script should become unnecessary in the future, when we just can
+# speculatively attach clones. This should be possible once the new ALM broker
+# transport becomes available.
+
 @load ./main
 
 module Broker;
 
 export {
+	## Event that is used by the manager to announce the master stores for zeek backed
+	## tables that is uses.
 	global announce_masters: event(masters: set[string]);
 }
 
+# If we are not the manager - disable automatically generating masters. We will attach
+# clones instead.
 @if ( Cluster::is_enabled() && Cluster::local_node_type() != Cluster::MANAGER )
 redef Broker::auto_store_master = F;
 @endif
@@ -24,6 +36,7 @@ event zeek_init()
 		}
 	}
 
+# Send the auto masters we created to the newly connected node
 event Broker::peer_added(endpoint: Broker::EndpointInfo, msg: string) &priority=1
 	{
 	if ( ! Cluster::is_enabled() )
@@ -39,6 +52,7 @@ event Broker::announce_masters(masters: set[string])
 	{
 	for ( i in masters )
 		{
+		# this magic name for the store is created in broker/Manager.cc for the manager.
 		local name = "___sync_store_" + i;
 		Broker::create_clone(name);
 		}