Skip site navigation (1)Skip section navigation (2)

  
 
  

home | help 
VMOD_COOKIE(3)		    Library Functions Manual		  VMOD_COOKIE(3)

NAME
     vmod_cookie - Vinyl Cache 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 Vinyl Cache 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-sepa-
     rated 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  ex-
     pression 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-sep-
     arated 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 expres-
     sion 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 particu-
     lar 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  re-
     turned.

     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"));
	}

COPYRIGHT
	This document is licensed under the same conditions as Vinyl Cache itself.
	See LICENSE for details.

	SPDX-License-Identifier: BSD-2-Clause

								  VMOD_COOKIE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=vmod_cookie&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help