add getters, test config, rework docs

src/Makefile.am

@@ -25,6 +25,7 @@ AM_VTC_LOG_FLAGS = \
 	-p vmod_path="$(abs_builddir)/.libs:$(vmoddir)"
 
 TESTS = \
+	vtc/cfg.vtc	\
 	vtc/now.vtc	\
 	vtc/lazy.vtc
 

src/vmod_cluster.c

@@ -235,11 +235,11 @@ vmod_cluster__fini(struct vmod_cluster_cluster **vcp)
 }
 
 #define cluster_methods (VCL_MET_INIT | VCL_MET_BACKEND_FETCH)
-#define cluster_check(ctx, name) do {					\
+#define cluster_check(ctx, name, ret) do {				\
 		if ((ctx->method & cluster_methods) == 0) {		\
 			VRT_fail(ctx,					\
 			    "cluster." #name " can not be called here"); \
-			return;						\
+			return ret;					\
 		}							\
 	} while(0)
 
@@ -250,7 +250,7 @@ vmod_cluster_deny(VRT_CTX,
 	const struct vmod_cluster_cluster_param *pr;
 	struct vmod_cluster_cluster_param *pl;
 
-	cluster_check(ctx, deny);
+	cluster_check(ctx, deny, );
 
 	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
 
@@ -269,7 +269,7 @@ vmod_cluster_allow(VRT_CTX,
 	const struct vmod_cluster_cluster_param *pr;
 	struct vmod_cluster_cluster_param *pl;
 
-	cluster_check(ctx, allow);
+	cluster_check(ctx, allow, );
 
 	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
 
@@ -281,6 +281,20 @@ vmod_cluster_allow(VRT_CTX,
 	cluster_blacklist_del(pl, b);
 }
 
+VCL_BOOL
+vmod_cluster_is_denied(VRT_CTX,
+    struct vmod_cluster_cluster *vc, VCL_BACKEND b)
+{
+	const struct vmod_cluster_cluster_param *pr;
+
+	cluster_check(ctx, is_denied, 0);
+	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
+
+	pr = cluster_task_param_r(ctx, vc);
+
+	return (cluster_blacklisted(pr, b));
+}
+
 VCL_VOID
 vmod_cluster_set_real(VRT_CTX,
     struct vmod_cluster_cluster *vc, VCL_BACKEND b)
@@ -288,7 +302,7 @@ vmod_cluster_set_real(VRT_CTX,
 	const struct vmod_cluster_cluster_param *pr;
 	struct vmod_cluster_cluster_param *pl;
 
-	cluster_check(ctx, set_real);
+	cluster_check(ctx, set_real, );
 
 	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
 
@@ -300,6 +314,21 @@ vmod_cluster_set_real(VRT_CTX,
 	pl->real = b;
 }
 
+VCL_BACKEND
+vmod_cluster_get_real(VRT_CTX, struct vmod_cluster_cluster *vc)
+{
+	const struct vmod_cluster_cluster_param *pr;
+	struct vmod_cluster_cluster_param *pl;
+
+	cluster_check(ctx, get_real, NULL);
+
+	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
+
+	pr = cluster_task_param_r(ctx, vc);
+
+	return (pr->real);
+}
+
 VCL_VOID
 vmod_cluster_set_uncacheable_direct(VRT_CTX,
     struct vmod_cluster_cluster *vc, VCL_BOOL direct)
@@ -307,7 +336,7 @@ vmod_cluster_set_uncacheable_direct(VRT_CTX,
 	const struct vmod_cluster_cluster_param *pr;
 	struct vmod_cluster_cluster_param *pl;
 
-	cluster_check(ctx, set_uncacheable_direct);
+	cluster_check(ctx, set_uncacheable_direct, );
 
 	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
 
@@ -319,6 +348,20 @@ vmod_cluster_set_uncacheable_direct(VRT_CTX,
 	pl->uncacheable_direct = direct;
 }
 
+VCL_BOOL
+vmod_cluster_get_uncacheable_direct(VRT_CTX,
+    struct vmod_cluster_cluster *vc)
+{
+	const struct vmod_cluster_cluster_param *pr;
+
+	cluster_check(ctx, get_uncacheable_direct, 0);
+
+	CHECK_OBJ_NOTNULL(vc, VMOD_CLUSTER_CLUSTER_MAGIC);
+
+	pr = cluster_task_param_r(ctx, vc);
+	return (pr->uncacheable_direct);
+}
+
 static VCL_BACKEND
 cluster_resolve(VRT_CTX,
     const struct vmod_cluster_cluster_param *pr)

src/vmod_cluster.vcc

@@ -75,6 +75,32 @@ Differences between the two methods are:
   Simply put, when using the cluster director, the ``.set_real()``
   method effectively replaces ``set bereq.backend``.
 
+.. _meth_ctx:
+
+Method Behavior in Different VCL Subs
+-------------------------------------
+
+The :ref:`obj_cluster` object methods other than
+:ref:`func_cluster.backend` behave differently depending on the
+context they are being called from:
+
+* When used in ``vcl_init{}``, they change or return the director's
+  default.
+
+* When used in ``vcl_backend_fetch {}``, they change or return the
+  director's property for this backend request only.
+
+  When the :ref:`func_cluster.backend` method is used with
+  ``resolve=LAZY``, modifying methods change the behaviour
+  irrespecitve of being called before or after the
+  :ref:`func_cluster.backend` method.
+
+* Use in vcl subs other than ``vcl_init{}`` and
+  ``vcl_backend_fetch{}`` is invalid and will trigger a VCL error.
+
+:ref:`func_cluster.backend` has slightly different, specifically
+documented limitations.
+
 $Object cluster(BACKEND cluster, [ BACKEND deny ], [ BACKEND real ],
 	BOOL uncacheable_direct = 1)
 
@@ -83,61 +109,64 @@ Instantiate a cluster director on top of the director passed as the
 
 The optional `deny` argument allows to specify one backend for which
 the cluster director will resolve to a `real` backend (the blacklist)
-as if the `.deny(BACKEND)` method had been called.
+as if the :ref:`func_cluster.deny` method had been called.
 
 The optional `real` argument allows to specify the director which use
-if a denied backend would have been hit as if the `.set_real(BACKEND)`
-method had been called.
+if a denied backend would have been hit as if the
+:ref:`func_cluster.set_real` method had been called.
 
 With the default `uncacheable_direct` argument, the cluster director
 always selects a `real` backend for uncacheable backend requests (as
 the vcl example above illustrates). Seting this argument ``false``
 disables special handling of uncacheable backend requests.
 
-
 $Method VOID .deny(BACKEND)
 
 Add a backend to the list of backends for which the cluster director
 will resolve to a `real` backend (the blacklist).
 
-When used in ``vcl_init{}``, changes the director's default
-blacklist.
-
-When used in ``vcl_backend_fetch {}``, changes the director's backlist
-for this backend request only. When the `.backend()` method is used
-with ``resolve=LAZY``, this method changes the behaviour irrespecitve
-of being called before or after the `.backend()` method.
-
-Use in vcl subs other than ``vcl_init{}`` and ``vcl_backend_fetch {}``
-is invalid and will trigger a VCL error.
+See :ref:`meth_ctx` for limitations.
 
 $Method VOID .allow(BACKEND)
 
 Remove a backend to the list of backends for which the cluster
 director will resolve to a `real` backend (the blacklist).
 
-Otherwise identical to the `.deny()` method.
+See :ref:`meth_ctx` for limitations.
+
+$Method BOOL .is_denied(BACKEND)
+
+Return true if the argument is on list of backends for which the
+cluster director will resolve to a `real` backend (the blacklist).
+
+See :ref:`meth_ctx` for limitations.
 
 $Method VOID .set_real(BACKEND)
 
-Only valid in ``vcl_backend_fetch {}``: Use a diffrent backend for
-resolution of real backends.
+Change the real backend.
+
+See :ref:`meth_ctx` for limitations.
 
-When the `.backend()` method is used with ``resolve=LAZY``, this
-method changes the behaviour irrespecitve of being called before or
-after the `.backend()` method.
+$Method BACKEND .get_real()
+
+Return the currently configured real backend.
+
+See :ref:`meth_ctx` for limitations.
 
 $Method VOID .set_uncacheable_direct(BOOL)
 
-Only valid in ``vcl_backend_fetch {}``: If a ``true`` argument is
-given, a `real` backend is always returned for uncacheable backend
-requests (e.g. passes or cache lookups hitting hit-for-pass). For a
-``false`` argument, no difference is made with regard to the
-cacheability of the backend request.
+If a ``true`` argument is given, a `real` backend is always returned
+for uncacheable backend requests (e.g. passes or cache lookups hitting
+hit-for-pass). For a ``false`` argument, no difference is made with
+regard to the cacheability of the backend request.
+
+See :ref:`meth_ctx` for limitations.
+
+$Method BOOL .get_uncacheable_direct()
+
+Return the currently configured behaviour.
 
-When the `.backend()` method is used with ``resolve=LAZY``, this
-method changes the behaviour irrespecitve of being called before or
-after the `.backend()` method.
+See :ref:`meth_ctx` for limitations.
 
 $Method BACKEND .backend(ENUM {NOW, LAZY} resolve=LAZY,
 	[ BACKEND deny ], [ BACKEND real ],
@@ -149,11 +178,12 @@ documentation, either as a reference to cluster director for
 ``resolve=LAZY`` or immediately for ``resolve=NOW``.
 
 The optional `deny`, `real` and `uncacheable_direct` arguments have
-the same effect as calling the methods `.deny()`, `.set_real()` and
-`.set_uncacheable_direct()` methods before the `.backend()` method
-with ``resolve=LAZY``, but can also be used with ``resolve=NOW``. Use
-of these arguments with ``resolve=LAZY`` is only allowed in
-``vcl_backend_fetch {}`` and ``vcl_init {}``.
+the same effect as calling the methods :ref:`func_cluster.deny`,
+:ref:`func_cluster.set_real` and
+:ref:`func_cluster.set_uncacheable_direct` before the `.backend()`
+method with ``resolve=LAZY``, but can also be used with
+``resolve=NOW``. Use of these arguments with ``resolve=LAZY`` is only
+allowed in ``vcl_backend_fetch {}`` and ``vcl_init {}``.
 
 
 SEE ALSO

src/vtc/cfg.vtc

+varnishtest "vmod_cluster configuration"
+
+server s1 {
+    rxreq
+    txresp
+} -start
+
+server s2 {
+}
+
+server s3 {
+    rxreq
+    txresp
+} -start
+
+varnish v1 -vcl+backend {
+    import std;
+    import cluster;
+    import directors;
+
+    sub vcl_init {
+	new rr = directors.round_robin();
+	rr.add_backend(s1);
+	rr.add_backend(s2);
+	new cl = cluster.cluster(rr.backend(), deny=s2, real=s3);
+
+	std.log("1ds1 " + cl.is_denied(s1));
+	std.log("1ds2 " + cl.is_denied(s2));
+	std.log("1ds3 " + cl.is_denied(s3));
+	std.log("1rea " + cl.get_real());
+	std.log("1unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s1);
+	cl.set_real(s2);
+	cl.set_uncacheable_direct(false);
+	std.log("2ds1 " + cl.is_denied(s1));
+	std.log("2ds2 " + cl.is_denied(s2));
+	std.log("2ds3 " + cl.is_denied(s3));
+	std.log("2rea " + cl.get_real());
+	std.log("2unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s1);
+	cl.set_real(s2);
+	std.log("3ds1 " + cl.is_denied(s1));
+	std.log("3ds2 " + cl.is_denied(s2));
+	std.log("3ds3 " + cl.is_denied(s3));
+	std.log("3rea " + cl.get_real());
+	std.log("3unc " + cl.get_uncacheable_direct());
+
+	cl.allow(s1);
+	cl.allow(s2);
+	cl.allow(s3);
+	cl.set_uncacheable_direct(true);
+	std.log("4ds1 " + cl.is_denied(s1));
+	std.log("4ds2 " + cl.is_denied(s2));
+	std.log("4ds3 " + cl.is_denied(s3));
+	std.log("4rea " + cl.get_real());
+	std.log("4unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s2);
+	cl.set_real(s3);
+}
+    sub vcl_recv {
+	if (req.url == "/syn") {
+		return (synth(200));
+	}
+	return (pass);
+    }
+    sub vcl_synth {
+	set resp.http.b1 = cl.backend(resolve=NOW);
+	set resp.http.b2 = cl.backend(resolve=NOW);
+    }
+    sub vcl_backend_fetch {
+
+	std.log("1ds1 " + cl.is_denied(s1));
+	std.log("1ds2 " + cl.is_denied(s2));
+	std.log("1ds3 " + cl.is_denied(s3));
+	std.log("1rea " + cl.get_real());
+	std.log("1unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s1);
+	cl.set_real(s2);
+	cl.set_uncacheable_direct(true);
+	std.log("2ds1 " + cl.is_denied(s1));
+	std.log("2ds2 " + cl.is_denied(s2));
+	std.log("2ds3 " + cl.is_denied(s3));
+	std.log("2rea " + cl.get_real());
+	std.log("2unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s1);
+	cl.set_real(s2);
+	std.log("3ds1 " + cl.is_denied(s1));
+	std.log("3ds2 " + cl.is_denied(s2));
+	std.log("3ds3 " + cl.is_denied(s3));
+	std.log("3rea " + cl.get_real());
+	std.log("3unc " + cl.get_uncacheable_direct());
+
+	set bereq.backend = cl.backend();
+
+	cl.allow(s1);
+	cl.allow(s2);
+	cl.allow(s3);
+	cl.set_uncacheable_direct(false);
+	std.log("4ds1 " + cl.is_denied(s1));
+	std.log("4ds2 " + cl.is_denied(s2));
+	std.log("4ds3 " + cl.is_denied(s3));
+	std.log("4rea " + cl.get_real());
+	std.log("4unc " + cl.get_uncacheable_direct());
+
+	cl.deny(s2);
+	cl.set_real(s3);
+    }
+    sub vcl_backend_response {
+	set beresp.http.backend = beresp.backend;
+    }
+} -start
+
+logexpect l1 -v v1 -g raw -d 1 {
+
+	expect 0 0	CLI             {^Rd vcl.load}
+	expect 0 0	VCL_Log         {^1ds1 false}
+	expect 0 0	VCL_Log         {^1ds2 true}
+	expect 0 0	VCL_Log         {^1ds3 false}
+	expect 0 0	VCL_Log         {^1rea s3}
+	expect 0 0	VCL_Log         {^1unc true}
+
+	expect 0 0	VCL_Log         {^2ds1 true}
+	expect 0 0	VCL_Log         {^2ds2 true}
+	expect 0 0	VCL_Log         {^2ds3 false}
+	expect 0 0	VCL_Log         {^2rea s2}
+	expect 0 0	VCL_Log         {^2unc false}
+
+	expect 0 0	VCL_Log         {^3ds1 true}
+	expect 0 0	VCL_Log         {^3ds2 true}
+	expect 0 0	VCL_Log         {^3ds3 false}
+	expect 0 0	VCL_Log         {^3rea s2}
+	expect 0 0	VCL_Log         {^3unc false}
+
+	expect 0 0	VCL_Log         {^4ds1 false}
+	expect 0 0	VCL_Log         {^4ds2 false}
+	expect 0 0	VCL_Log         {^4ds3 false}
+	expect 0 0	VCL_Log         {^4rea s2}
+	expect 0 0	VCL_Log         {^4unc true}
+
+	# 2/3/4unc : intentonally differs from vcl_init
+	expect * 1003	VCL_call	{^BACKEND_FETCH}
+	expect 0 1003	VCL_Log         {^1ds1 false}
+	expect 0 1003	VCL_Log         {^1ds2 true}
+	expect 0 1003	VCL_Log         {^1ds3 false}
+	expect 0 1003	VCL_Log         {^1rea s3}
+	expect 0 1003	VCL_Log         {^1unc true}
+
+	expect 0 1003	VCL_Log         {^2ds1 true}
+	expect 0 1003	VCL_Log         {^2ds2 true}
+	expect 0 1003	VCL_Log         {^2ds3 false}
+	expect 0 1003	VCL_Log         {^2rea s2}
+	expect 0 1003	VCL_Log         {^2unc tru.}
+
+	expect 0 1003	VCL_Log         {^3ds1 true}
+	expect 0 1003	VCL_Log         {^3ds2 true}
+	expect 0 1003	VCL_Log         {^3ds3 false}
+	expect 0 1003	VCL_Log         {^3rea s2}
+	expect 0 1003	VCL_Log         {^3unc tru.}
+
+	expect 0 1003	VCL_Log         {^4ds1 false}
+	expect 0 1003	VCL_Log         {^4ds2 false}
+	expect 0 1003	VCL_Log         {^4ds3 false}
+	expect 0 1003	VCL_Log         {^4rea s2}
+	expect 0 1003	VCL_Log         {^4unc fals.}
+} -start
+
+client c1 {
+	txreq -url "/syn"
+	rxresp
+	expect resp.status == 200
+	expect resp.http.b1 == s1
+	expect resp.http.b2 == s3
+
+	txreq
+	rxresp
+	expect resp.status == 200
+	expect resp.http.backend == "s1"
+
+	txreq
+	rxresp
+	expect resp.status == 200
+	expect resp.http.backend == "s3"
+} -run
+
+logexpect l1 -wait
\ No newline at end of file