Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
301 lines (208 sloc) 6.41 KB

vmod_cookie

Manual section:3

SYNOPSIS

import cookie [from "path"] ;

DESCRIPTION

Handle HTTP cookies easier in Varnish VCL. (without regex)

Parses a cookie header into an internal data store, where per-cookie get/set/delete functions are available. A filter_except() method removes all but a set comma-separated list of cookies. A filter() method removes a comma- separated list of cookies.

A convenience function for formatting the Set-Cookie Expires date field is also included. To actually manipulate the Set-Cookie response headers, vmod-header should be used instead though.

The state loaded with cookie.parse() has a lifetime of the current request or backend request context. To pass variables to the backend request, store the contents as fake bereq headers.

Filtering example:

vcl 4.0;

import cookie;

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

sub vcl_recv {
    if (req.http.cookie) {
        cookie.parse(req.http.cookie);
        # Either delete the ones you want to get rid of:
        cookie.delete("cookie2");
        # or filter everything but a few:
        cookie.filter_except("SESSIONID,PHPSESSID");

        # Store it back into req so it will be passed to the backend.
        set req.http.cookie = cookie.get_string();

        # If empty, unset so the builtin VCL can consider it for caching.
        if (req.http.cookie == "") {
            unset req.http.cookie;
        }
    }
}

CONTENTS

  • func_clean
  • func_delete
  • func_filter
  • func_filter_except
  • func_format_rfc1123
  • func_get
  • func_get_string
  • func_isset
  • func_parse
  • func_set

clean

VOID clean(PRIV_TASK)
Description
Clean up previously parsed cookies. It is not necessary to run clean() in normal operations.
Example
sub vcl_recv {
        cookie.clean();
}

delete

VOID delete(PRIV_TASK, STRING cookiename)
Description
Delete cookiename from internal vmod storage if it exists.
Example
sub vcl_recv {
    cookie.parse("cookie1: value1; cookie2: value2;");
    cookie.delete("cookie2");
    // get_string() will now yield "cookie1: value1";
}

filter

VOID filter(PRIV_TASK, STRING filterstring)
Description
Delete all cookies from internal vmod storage that are in the comma-separated argument cookienames.
Example
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
        cookie.filter("cookie1,cookie2");
        // get_string() will now yield
        // "cookie3: value3";
}

filter_except

VOID filter_except(PRIV_TASK, STRING filterstring)
Description
Delete all cookies from internal vmod storage that is not in the comma-separated argument cookienames.
Example
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2; cookie3: value3");
        cookie.filter_except("cookie1,cookie2");
        // get_string() will now yield
        // "cookie1: value1; cookie2: value2;";
}

format_rfc1123

STRING format_rfc1123(TIME now, DURATION timedelta)
Description

Get a RFC1123 formatted date string suitable for inclusion in a Set-Cookie response header.

Care should be taken if the response has multiple Set-Cookie headers. In that case the header vmod should be used.

Example
sub vcl_deliver {
        # Set a userid cookie on the client that lives for 5 minutes.
        set resp.http.Set-Cookie = "userid=" + req.http.userid + "; Expires=" + cookie.format_rfc1123(now, 5m) + "; httpOnly";
}

get

STRING get(PRIV_TASK, STRING cookiename)
Description
Get the value of cookiename, as stored in internal vmod storage. If cookiename does not exist an empty string is returned.
Example
import std;
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}

get_string

STRING get_string(PRIV_TASK)
Description
Get a Cookie string value with all cookies in internal vmod storage. Does not modify internal storage.
Example
sub vcl_recv {
        cookie.parse(req.http.cookie);
        cookie.filter_except("SESSIONID,PHPSESSID");
        set req.http.cookie = cookie.get_string();
}

isset

BOOL isset(PRIV_TASK, STRING cookiename)
Description
Check if cookiename is set in the internal vmod storage.
Example
import std;
sub vcl_recv {
        cookie.parse("cookie1: value1; cookie2: value2;");
        if (cookie.isset("cookie2")) {
                std.log("cookie2 is set.");
        }
}

parse

VOID parse(PRIV_TASK, STRING cookieheader)
Description
Parse the cookie string in cookieheader. If state already exists, clean() will be run first.
Example
sub vcl_recv {
        cookie.parse(req.http.Cookie);
}

set

VOID set(PRIV_TASK, STRING cookiename, STRING value)
Description
Set the internal vmod storage for cookiename to value.
Example
sub vcl_recv {
        cookie.set("cookie1", "value1");
        std.log("cookie1 value is: " + cookie.get("cookie1"));
}
You can’t perform that action at this time.