README.rst, LICENSE

LICENSE

+Copyright 2017,2019 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

@@ -3,3 +3,8 @@ ACLOCAL_AMFLAGS = -I m4 -I @VARNISHAPI_DATAROOTDIR@/aclocal
 DISTCHECK_CONFIGURE_FLAGS = RST2MAN=:
 
 SUBDIRS = src
+
+dist_doc_DATA = README.rst LICENSE
+
+README.rst: src/vmod_etag.man.rst
+	cp $< $@

README.rst

+..
+.. NB:  This file is machine generated, DO NOT EDIT!
+..
+.. Edit vmod.vcc and run make instead
+..
+
+.. role:: ref(emphasis)
+
+=========
+VMOD etag
+=========
+
+-------------------
+Varnish ETag Module
+-------------------
+
+:Manual section: 3
+
+SYNOPSIS
+========
+
+::
+
+        import etag;
+
+        sub vetag_backend_fetch {
+            if (bereq.http.If-None-Match ~ {"^(W/)?"vetag"}) {
+                unset bereq.http.If-None-Match;
+            }
+            if (bereq.http.If-Match ~ {"^(W/)?"vetag"}) {
+                unset bereq.http.If-Match;
+            }
+            if (bereq.http.If-Range ~ {"^(W/)?"vetag"}) {
+                unset bereq.http.If-Range;
+            }
+        }
+
+        sub vetag_backend_response {
+            if (! beresp.http.ETag) {
+                set beresp.filters = beresp.filters + " etag";
+                # no Etag for cache miss with streaming
+                set beresp.do_stream = false;
+                # berep.do_* variables have no effect beyond this point
+            }
+        }
+
+        sub vetag_deliver {
+            # safeguard for do_stream == true
+            if (resp.http.Etag ~ {"^(W/)?"vetag.*[-A-Z ]"}) {
+                unset resp.http.Etag;
+            }
+        }
+
+        sub vcl_backend_fetch {
+            # first
+            call vetag_backend_fetch;
+        }
+
+        sub vcl_backend_response {
+            # last - or after any change to beresp.do_*
+            call vetag_backend_response;
+        }
+
+        sub vcl_deliver {
+            # first
+            call vetag_deliver;
+        }
+
+DESCRIPTION
+===========
+
+This vmod adds a `beresp.filter`_ (see aka Varnish Fetch Processor /
+VFP) to generate ETags on the way into the Varnish Cache.
+
+.. _`beresp.filter`: http://varnish-cache.org/docs/trunk/reference/vcl.html#beresp
+
+It is strongly recommended to use this vmod von VCL as shown in the `SYNOPSIS`_
+
+ETag generation is enabled by adding ``etag`` to ``beresp.filters`` as
+shown in the example above.
+
+The ETag format is the string ``"vetag`` followed by 64 hexadecimal
+characters representing a SHA256 hash over the response body and a
+closing quote ``"``. The ``"vetag`` prefix is used to identify
+incompletely generated ETags as explained below.
+
+Usage notes:
+
+* For *streaming*, an ETag can not be generated, because, by design,
+  the response headers are being sent before the backend response is
+  complete.
+
+  The VCL template in the `SYNOPSIS`_ thus contains ``set
+  beresp.do_stream = false`` to disable streaming when the ``etag``
+  filter is activated.
+
+  The ``vcl_deliver`` code from the `SYNOPSIS`_ nevertheless supports
+  streaming by removing any incomplete ETags generated by this vmod.
+
+* By design, ETags generated by this vmod can not be used for backend
+  conditional requests.
+
+  The VCL template in the `SYNOPSIS`_ thus contains code to remove any
+  conditional request headers based on ``vetag`` ETags.
+
+Implementation note:
+
+* Varnish core code does not officially support modifying headers of
+  cache objects after creation, which is exactly what is required
+  here. This vmod thus works by leaving a fixed length placeholder
+  ETag header with the cache object, which later gets overwritten by
+  the VFP. This may or may not work with custom storage engines.
+
+SEE ALSO
+========
+* :ref:`vcl(7)`
+* :ref:`varnishd(1)`
+
+COPYRIGHT
+=========
+
+::
+
+  Copyright 2017,2019 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.

src/vmod_etag.vcc

+#-
+# Copyright 2017,2019 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.
+
 $Module etag 3 "Varnish ETag Module"
 $Synopsis manual