README.rst 4.57 KB
Newer Older
Nils Goroll's avatar
Nils Goroll committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
..
.. 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

Nils Goroll's avatar
Nils Goroll committed
77
It is strongly recommended to use this vmod from VCL as shown in the `SYNOPSIS`_
Nils Goroll's avatar
Nils Goroll committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92

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.

Nils Goroll's avatar
Nils Goroll committed
93 94
  The VCL template in the `SYNOPSIS`_ thus contains
  ``set beresp.do_stream = false`` to disable streaming when the ``etag``
Nils Goroll's avatar
Nils Goroll committed
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
  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.