vmod_header.vcc

$Module header 3 "Header VMOD for Varnish"
DESCRIPTION
===========

Varnish Module for manipulation of duplicated HTTP headers, for instance
multiple Set-Cookie headers.

.. vcl-start

Example::

    vcl 4.0;
    import header;

    backend default { .host = "192.0.2.11"; .port = "8080"; }

    sub vcl_backend_response {
        if (beresp.http.Set-Cookie) {
            # Add another line of Set-Cookie in the response.
            header.append(beresp.http.Set-Cookie, "VSESS=abbabeef");

            # CMS always set this, but doesn't really need it.
            header.remove(beresp.http.Set-Cookie, "JSESSIONID=");
        }
    }

.. vcl-end


$ABI vrt
$Function VOID append(HEADER, STRANDS)

Description
        Append an extra occurrence to an existing header.
Example
    ::
    header.append(beresp.http.Set-Cookie, "foo=bar")

$Function VOID copy(HEADER, HEADER)

Description
        Copy all source headers to a new header.
Example
    ::
    header.copy(beresp.http.set-cookie, beresp.http.x-old-cookie);

$Function STRING get(HEADER header, REGEX regex)

Description
        Fetches the value of the first `header` that matches the given
        regular expression `regex`.
Example
    ::
    set beresp.http.xusr = header.get(beresp.http.set-cookie,"user=");

$Function VOID remove(HEADER header, REGEX regex)

Description
        Remove all occurrences of `header` that matches `regex`.
Example
    ::
    header.remove(beresp.http.set-cookie,"^(?!(funcookie=))");

$Function VOID regsub(HTTP, REGEX regex, STRING sub, BOOL all=0)

Description
        For every header line in the HTTP object, which can be one of
        ``req``, ``resp``, ``bereq`` or ``beresp``, if the line
        matches the regular expression ``regex``, then replace it with
        the result of a substitution using the string ``sub``. ``sub``
        may include backreferences of the form ``\1`` through ``\9``,
        which refer to capturing expressions in the ``regex``, or
        ``\0`` to refer to the entire matched portion of the header
        line.

        If ``all`` is ``false``, replace the first matched portion of
        the header line with ``sub``. This is the same operation
        performed by the VCL native function ``regsub()``. ``all`` is
        ``false`` by default.

        If ``all`` is ``true``, replace each non-overlapping matched
        portion of the header line with ``sub``. This is the same
        operation performed by native ``regsuball()``.

        Note that unlike the other functions in this VMOD,
        ``regsub()`` applies to the *entire* header line, including
        the header name, colon separator, and header value. Take care
        that your substitutions result in valid headers, since
        ill-formed headers can interfere with the HTTP protocol.

        Consider case sensitivity in the regex match. The standard
        dictates that header names are case insensitive, but header
        values are not. The VMOD function does not take care of that
        for you, but you can express it in the ``regex`` using the
        ``(?i)`` flag, as shown in the example below (use ``(?-i)`` to
        turn it off).

        Consider using the ``^`` starting anchor in ``regex`` to be
        sure to match a header name (and not the same string somewhere
        in the middle of the line).
Example
    :: header.regsub(req, "^(?i)Foo(\\d): (?-i)bar=(.*)$", "Bar\\1: \\2")

$Function HEADER dyn(HTTP, STRING)

Description
        Return a dynamic header name.

	Most other functions of this vmod require a *HEADER* argument,
	which usually is a VCL-defined header like ``req.http.foo``.

	This function allows to construct a header name from an
	arbitrary string, which may also be dynamically created, for
	example from a variable.

	*Notice* that there are no syntactic checks on the *STRING*
	argument by purpose in order to support exotic use cases. It
	is entirely up to the user and at their own risk to supply a
	string which represents a valid HTTP header name (or not).

Example
    ::
    # create this request header
    # 42: is the answer
    header.append(header.dyn(req, 35 + 7), "is the answer");

ACKNOWLEDGEMENTS
================

The development of this plugin was made possible by the sponsorship of
Softonic, http://en.softonic.com/ .

Also thanks to Imo Klabun and Anders Nordby for bug reports.

BUGS
====

You can't use dynamic regular expressions, which also holds true for normal
regular expressions in regsub().