VMOD_COOKIE(3)             Library Functions Manual             VMOD_COOKIE(3)

NAME
       vmod_cookie - Varnish Cookie Module

SYNOPSIS

          import cookie [as name] [from "path"]

          VOID clean()

          VOID delete(STRING cookiename)

          VOID filter(STRING filterstring)

          VOID filter_re(REGEX expression)

          VOID keep(STRING filterstring)

          VOID keep_re(REGEX expression)

          STRING format_date(TIME now, DURATION timedelta)

          STRING get(STRING cookiename)

          STRING get_re(REGEX expression)

          STRING get_string()

          BOOL isset(STRING cookiename)

          VOID parse(STRING cookieheader)

          VOID set(STRING cookiename, STRING value)

DESCRIPTION
       Handle HTTP cookies more easily in Varnish VCL.

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

       Regular expressions can be used for either selecting cookies, deleting
       matching cookies and deleting non-matching cookie names.

       A convenience function for formatting the Set-Cookie Expires date field
       is also included.

       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:

          import cookie;

          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 delete all but a few:
                  cookie.keep("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;
                  }
              }
          }

   VOID clean()
       Clean up previously parsed cookies. It is not necessary to run clean()
       in normal operations.

       Example:

          sub vcl_recv {
              cookie.clean();
          }

   VOID delete(STRING cookiename)
       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"
          }

   VOID filter(STRING filterstring)
       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"
          }

   VOID filter_re(REGEX expression)
       Delete all cookies from internal vmod storage that matches the regular
       expression expression.

       Example:

          sub vcl_recv {
              cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
              cookie.filter_re("^cookie[12]$");
              # get_string() will now yield "cookie3=value3"
          }

   VOID keep(STRING filterstring)
       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.keep("cookie1,cookie2");
              # get_string() will now yield "cookie1=value1; cookie2=value2"
          }

   VOID keep_re(REGEX expression)
       Delete all cookies from internal vmod storage that does not match
       expression expression.

       Example:

          sub vcl_recv {
              cookie.parse("cookie1=value1; cookie2=value2; cookie3=value3");
              cookie.keep_re("^cookie[12]$");
              # get_string() will now yield "cookie1=value1; cookie2=value2"
          }

   STRING format_date(TIME now, DURATION timedelta)
       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_date(now, 5m) + "; httpOnly";
          }

   STRING get(STRING cookiename)
       Get the value of cookiename, as stored in internal vmod storage.

       Example:

          import std;
          sub vcl_recv {
              cookie.parse("cookie1=value1; cookie2=value2");
              std.log("cookie1 value is: " + cookie.get("cookie1"));
          }

       If cookiename does not exist, the NULL string is returned. Note that a
       NULL string is converted to an empty string when assigned to a header.
       This means that the following is correct:

          if (req.http.Cookie) {
                  cookie.parse(req.http.Cookie);
                  set req.http.X-tmp = cookie.get("a_cookie");
          } else {
                  set req.http.X-tmp = "";
          }
          if (req.http.X-tmp != "") {
                  // do something with the X-tmp header...
          } else {
                  // fallback case
          }

       However, using cookie.isset() is often a better way to check if a
       particular cookie is present, like this:

          unset req.http.X-tmp; # unnecessary if no fallback is needed
          if (req.http.Cookie) {
                  cookie.parse(req.http.Cookie);
                  if (cookie.isset("a_cookie")) {
                          set req.http.X-tmp = cookie.get("a_cookie");
                          # do something with the X-tmp header...
                  }
          }
          # if necessary, do something when a_cookie is not there
          if (!req.http.X-tmp) {
                  # fallback case
          }

   STRING get_re(REGEX expression)
       Get the value of the first cookie in internal vmod storage that matches
       the regular expression expression. If nothing matches, the NULL string
       is returned.

       Example:

          import std;
          sub vcl_recv {
              cookie.parse("cookie1=value1; cookie2=value2");
              std.log("cookie1 value is: " + cookie.get_re("^cookie1$"));
          }

   STRING get_string()
       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.keep("SESSIONID,PHPSESSID");
              set req.http.cookie = cookie.get_string();
          }

   BOOL isset(STRING cookiename)
       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.");
              }
          }

   VOID parse(STRING cookieheader)
       Parse the cookie string in cookieheader. If state already exists,
       clean() will be run first.

       Example:

          sub vcl_recv {
              cookie.parse(req.http.Cookie);
          }

   VOID set(STRING cookiename, STRING value)
       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"));
          }

DEPRECATED
   ALIAS format_rfc1123()
       Deprecated alias for format_date().

COPYRIGHT

          This document is licensed under the same conditions as Varnish itself.
          See LICENSE for details.

          SPDX-License-Identifier: BSD-2-Clause

                                                                VMOD_COOKIE(3)