working POC - this is work in progress

.gitignore

+# build system
+
+.deps/
+.libs/
+autom4te.cache/
+build-aux/
+m4/
+
+*.la
+*.lo
+*.o
+*.tar.gz
+
+Makefile
+Makefile.in
+aclocal.m4
+config.h
+config.h.in
+config.log
+config.status
+configure
+libtool
+stamp-h1
+
+# test suite
+
+*.log
+*.trs
+
+# vmodtool
+
+vcc_*_if.[ch]
+vmod_*.rst
+
+# man
+
+*.1
+*_options.rst
+*_synopsis.rst
+vmod_*.3

LICENSE

+Copyright 2018 UPLEX Nils Goroll Systemoptimierung
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

Makefile.am

+ACLOCAL_AMFLAGS = -I m4 -I @VARNISHAPI_DATAROOTDIR@/aclocal
+
+DISTCHECK_CONFIGURE_FLAGS = RST2MAN=:
+
+SUBDIRS = src

README.rst

+working POC for a director to facilitate cache-clustering.
+
+This is work in progress.
+
+As of 2018-05-09, needs master.patch applied to varnish-cache master

bootstrap

+#!/bin/sh
+
+set -e
+set -u
+
+WORK_DIR=$(pwd)
+ROOT_DIR=$(dirname "$0")
+
+cd "$ROOT_DIR"
+
+if ! command -v libtoolize >/dev/null
+then
+	echo "libtoolize: command not found, falling back to glibtoolize" >&2
+	alias libtoolize=glibtoolize
+fi
+
+mkdir -p m4
+aclocal
+libtoolize --copy --force
+autoheader
+automake --add-missing --copy --foreign
+autoconf
+
+cd "$WORK_DIR"
+"$ROOT_DIR"/configure "$@"

configure.ac

+AC_PREREQ([2.68])
+AC_INIT([libvmod-cluster], [0.1])
+AC_CONFIG_MACRO_DIR([m4])
+AC_CONFIG_AUX_DIR([build-aux])
+AC_CONFIG_HEADER([config.h])
+
+AM_INIT_AUTOMAKE([1.12 -Wall -Werror foreign parallel-tests])
+AM_SILENT_RULES([yes])
+AM_PROG_AR
+
+LT_PREREQ([2.2.6])
+LT_INIT([dlopen disable-static])
+
+AC_ARG_WITH([rst2man],
+	AS_HELP_STRING(
+		[--with-rst2man=PATH],
+		[Location of rst2man (auto)]),
+	[RST2MAN="$withval"],
+	AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], []))
+
+VARNISH_PREREQ([5.2.0])
+VARNISH_VMODS([cluster])
+
+AC_CONFIG_FILES([
+	Makefile
+	src/Makefile
+])
+
+AC_OUTPUT
+
+AS_ECHO("
+	==== $PACKAGE_STRING ====
+
+	varnish:      $VARNISH_VERSION
+	prefix:       $prefix
+	vmoddir:      $vmoddir
+	vcldir:       $vcldir
+	pkgvcldir:    $pkgvcldir
+
+	compiler:     $CC
+	cflags:       $CFLAGS
+	ldflags:      $LDFLAGS
+")

master.patch

+diff --git a/bin/varnishd/cache/cache_director.c b/bin/varnishd/cache/cache_director.c
+index f5552fe5f..c1c60b895 100644
+--- a/bin/varnishd/cache/cache_director.c
++++ b/bin/varnishd/cache/cache_director.c
+@@ -76,7 +76,7 @@ VDI_Ahealth(const struct director *d)
+ 
+ /* Resolve director --------------------------------------------------*/
+ 
+-static VCL_BACKEND
++VCL_BACKEND
+ VDI_Resolve(VRT_CTX)
+ {
+ 	const struct director *d;
+diff --git a/include/vrt.h b/include/vrt.h
+index a0c142c52..d7eb04f76 100644
+--- a/include/vrt.h
++++ b/include/vrt.h
+@@ -461,6 +461,7 @@ VCL_BACKEND VRT_AddDirector(VRT_CTX, const struct vdi_methods *,
+ void VRT_SetHealth(VCL_BACKEND d, int health);
+ void VRT_DisableDirector(VCL_BACKEND);
+ void VRT_DelDirector(VCL_BACKEND *);
++VCL_BACKEND VDI_Resolve(VRT_CTX);
+ 
+ /* Suckaddr related */
+ int VRT_VSA_GetPtr(const struct suckaddr *sua, const unsigned char ** dst);

src/Makefile.am

+AM_CFLAGS = $(VARNISHAPI_CFLAGS)
+
+# Modules
+
+vmod_LTLIBRARIES = \
+	libvmod_cluster.la
+
+libvmod_cluster_la_LDFLAGS = $(VMOD_LDFLAGS)
+libvmod_cluster_la_SOURCES = vmod_cluster.c
+nodist_libvmod_cluster_la_SOURCES = \
+	vcc_cluster_if.c \
+	vcc_cluster_if.h
+
+@BUILD_VMOD_CLUSTER@
+
+# Test suite
+
+AM_TESTS_ENVIRONMENT = \
+	PATH="$(abs_builddir):$(VARNISH_TEST_PATH):$(PATH)" \
+	LD_LIBRARY_PATH="$(VARNISH_LIBRARY_PATH)"
+TEST_EXTENSIONS = .vtc
+VTC_LOG_COMPILER = varnishtest -v
+AM_VTC_LOG_FLAGS = \
+	-p vcl_path="$(abs_top_srcdir)/vcl" \
+	-p vmod_path="$(abs_builddir)/.libs:$(vmoddir)"
+
+TESTS = \
+	vtc/vmod_cluster.vtc
+
+# Documentation
+
+dist_doc_DATA = \
+	vmod_cluster.vcc \
+	$(TESTS)
+
+dist_man_MANS = \
+	vmod_cluster.3
+
+
+.rst.1:
+	$(AM_V_GEN) $(RST2MAN) $< $@

src/vmod_cluster.vcc

+#-
+# Copyright 2018 UPLEX Nils Goroll Systemoptimierung
+# All rights reserved
+#
+# Author: Nils Goroll <nils.goroll@uplex.de>
+#
+# See LICENSE
+#
+
+$Module cluster 3 Varnish cluster Module
+
+DESCRIPTION
+===========
+
+This director facilitates the implementation of varnish cache
+clustering, in particular in combination with the shard director. The
+basic design idea is to shard objects among a number of varnish caches
+configured in the director passed as the `cluster` argument: If the
+local cache is the shard member designated for serving the respective
+object, a backend request is to be made with a real
+backend. Otherwise, the request is to be forwarded to another node
+from the `cluster` argument, which, in turn, will either serve the
+object from its cache or issue a request against a `real` backend.
+
+For a shard director argument ``shard``, the following examples are
+roughly equivalent if ``myself`` resolves to the local node
+
+* explicit VCL code with shard director ``resolve=now``::
+
+	sub vcl_init {
+		new shard = directors.shard();
+		shard.add_backend(other_node);
+		shard.add_backend(myself);
+		shard.reconfigure();
+		new real = directors.whatever();
+		real.add_backend(...)
+		# ...
+	}
+
+	sub vcl_backend_fetch {
+		if (bereq.uncacheable || shard.backend() == myself) {
+			set bereq.backend = real.backend();
+		} else {
+			set bereq.backend = shard.backend();
+		}
+	}
+
+* use of the cluster director::
+
+	sub vcl_init {
+		# same as above, plus
+		new cluster = cluster.cluster(shard,
+			deny = myself,
+			real = real.backend());
+	}
+
+	sub vcl_backend_fetch {
+		set bereq.backend = cluster.backend();
+	}
+
+
+Differences between the two methods are:
+
+* the cluster director works with lazy resolution where a director
+  does not return one of its configured backends, but rather a
+  reference to itself (as do all the varnish bundled directors except
+  for the shard director, which supports lazy resolution with the
+  ``resolve=LAZY`` argument).
+
+* when different ``deny`` or, in particular, ``real`` backends are to
+  be used, the cluster director can save substantial amounts of VCL
+  code: Using the ``.real()`` method, the director of real backends
+  can be changed in ``vcl_backend_fetch {}``.
+
+  Simply put, when using the cluster director, the ``.real()`` method
+  effectively replaces ``set bereq.backend``.
+
+$Object cluster(BACKEND cluster, [ BACKEND deny ], [ BACKEND real ],
+	BOOL uncacheable_direct = 1)
+
+Instantiate a cluster director on top of the director passed as the
+`cluster` argument.
+
+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.
+
+The optional `real` argument allows to specify the director which use
+if a denied backend would have been hit as if the `.real(BACKEND)`
+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.
+
+$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.
+
+$Method VOID .real(BACKEND)
+
+Only valid in ``vcl_backend_fetch {}``: Use a diffrent backend for
+resolution of real backends.
+
+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 VOID .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.
+
+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 .backend(ENUM {NOW, LAZY} resolve=LAZY,
+	[ BACKEND deny ], [ BACKEND real ],
+	[ BOOL uncacheable_direct ])
+
+
+Return a backend by the method described in the rest of this
+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()`, `.real()` and
+`.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 {}``.
+
+
+SEE ALSO
+========
+vcl\(7),varnishd\(1)

src/vtc/vmod_cluster.vtc

+varnishtest "vmod_cluster toy example with round-robin"
+
+varnish v1 -vcl {
+    import cluster;
+    import directors;
+
+    backend s1 { .host = "${bad_backend}";}
+    backend s2 { .host = "${bad_backend}";}
+    backend s3 { .host = "${bad_backend}";}
+
+    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);
+    }
+    sub vcl_recv {
+	return (synth(200));
+    }
+    sub vcl_synth {
+	set resp.http.b1 = cl.backend(resolve=NOW);
+	set resp.http.b2 = cl.backend(resolve=NOW);
+    }
+} -start
+
+client c1 {
+	txreq
+	rxresp
+	expect resp.status == 200
+	expect resp.http.b1 == s1
+	expect resp.http.b2 == s3
+} -run