vmod-cookieplus
is an advanced Cookie VMOD for interacting with request and response Cookies.
vmod-cookieplus
allows you to get, add, delete, and keep Cookie and Set-Cookie values.
It also allows you to remove unused client side Cookies.
All functions will by default parse Cookies from the req.http.Cookie
and Set-Cookies
from resp.http.Set-Cookie
, unless otherwise specified. Backend context is supported.
All functions keep an internal state of Cookies and Set-Cookies until written out
using write()
or setcookie_write()
.
Set-Cookie operations all have a setcookie
prefix and can only be used where a
resp
or beresp
object exists.
Only allow application specific Cookies.
vcl 4.0;
import cookieplus;
sub vcl_recv
{
// Keep these Cookies
cookieplus.keep("JSESSIONID");
cookieplus.keep_regex("^BNES_SSESS");
cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
// Any Cookie that is not kept will be removed
cookieplus.write();
}
Conditionally allow application specific Cookies.
vcl 4.0;
import cookieplus;
sub vcl_recv
{
// Mark all Cookies for removal
cookieplus.keep("");
// Only allow these Cookies if the URL allows for it
if (req.url ~ "^/admin") {
cookieplus.keep("JSESSIONID");
cookieplus.keep_regex("^BNES_SSESS");
cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
}
// Any Cookie that is not kept will be removed
cookieplus.write();
}
Add a VCL cookie.
vcl 4.0;
import cookieplus;
import std;
sub vcl_deliver
{
// Get the vcpsess Cookie value
set req.http.X-vcpsess = cookieplus.get("vcpsess", "");
if (req.http.X-vcpsess == "") {
// Create a new random vcpsess value
set req.http.X-vcpsess = std.random(1, 10000000) + "." + std.random(1, 10000000);
// Create a vcpsess Set-Cookie, valid for 30 days
cookieplus.setcookie_add("vcpsess", req.http.X-vcpsess, 30d, req.http.Host, "/");
// Write the Set-Cookie to the response
cookieplus.setcookie_write();
}
// req.http.X-vcpsess now contains the vcpsess cookie value
}
Only allow application specific Set-Cookie values from the backend.
vcl 4.0;
import cookieplus;
sub vcl_backend_response
{
// Mark all Set-Cookies for removal
cookieplus.setcookie_keep("");
// Only allow these Set-Cookies if the URL allows for it
if (bereq.url ~ "^/admin") {
cookieplus.setcookie_keep("JSESSIONID");
cookieplus.setcookie_keep_regex("^BNES_SSESS");
cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
}
// Any Set-Cookie that is not kept will be removed
cookieplus.setcookie_write();
}
Conditionally allow application specific Cookies and remove all other Cookies from client.
vcl 4.0;
import cookieplus;
sub vcl_recv
{
// Mark all Cookies for removal
cookieplus.keep("");
// Only allow these Cookies if the URL allows for it
if (req.url ~ "^/admin") {
cookieplus.keep("JSESSIONID");
cookieplus.keep_regex("^BNES_SSESS");
cookieplus.keep_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.keep_regex("^SESS[a-zA-Z0-9]+$");
}
// Any Cookie that is not kept will be removed
cookieplus.write();
}
sub vcl_backend_response
{
// Mark all Set-Cookies for removal
cookieplus.setcookie_keep("");
// Only allow these Set-Cookies if the URL allows for it
if (bereq.url ~ "^/admin") {
cookieplus.setcookie_keep("JSESSIONID");
cookieplus.setcookie_keep_regex("^BNES_SSESS");
cookieplus.setcookie_keep_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.setcookie_keep_regex("^SESS[a-zA-Z0-9]+$");
}
// Any Set-Cookie that is not kept will be removed
cookieplus.setcookie_write();
}
sub vcl_deliver
{
// Do not attempt to delete these Cookies from the client
// as they may have been conditionally removed, but we want
// to keep them.
cookieplus.remove_deleted("JSESSIONID");
cookieplus.remove_deleted_regex("^BNES_SSESS");
cookieplus.remove_deleted_regex("^SSESS[a-zA-Z0-9]+$");
cookieplus.remove_deleted_regex("^SESS[a-zA-Z0-9]+$");
// Do not delete Google Analytic Cookies
cookieplus.remove_deleted("_ga");
cookieplus.remove_deleted("_git");
cookieplus.remove_deleted("_gat");
cookieplus.remove_deleted_regex("^__ut..$");
// Delete all other Cookies that were sent in the request
cookieplus.setcookie_add_deleted();
cookieplus.setcookie_write();
}
STRING get(STRING name, STRING default)
Description
Get the Cookie value for name
.
Return value
The Cookie value for name
. If not found, default
is returned.
name
The name of the Cookie. The first Cookie to match is used.
default
The return value if name
is not found. Optional.
STRING get_regex(STRING regex, STRING default)
Description
Get the Cookie value where the name matches regex
.
Return value
The Cookie value where the name matches regex
. If not found, default
is returned.
regex
The regular expression used to match on the name. Only the first matching Cookie is used. This value is static and cannot change between calls.
default
The return value if no matching Cookie is not found. Optional.
VOID add(STRING name, STRING value, BOOL keep = true, BOOL override = true)
Description
Add a Cookie with name
and value
.
Return value
None
name
The name of the Cookie to add.
value
The value of the Cookie to add.
keep
If in keep_mode and keep
is true, the Cookie is always kept when writing.
Defaults to true
.
override
If the cookie exists, override it. Defaults to true
.
VOID delete(STRING name, BOOL delete_keep = false)
Description
Delete all Cookies that match name
.
Return value
None.
name
The name of the Cookie to delete. All Cookies which match name
are deleted.
delete_keep
If delete_keep
is true
, delete kept Cookies. Defaults to false
.
VOID delete_regex(STRING regex, BOOL delete_keep = false)
Description
Delete all Cookies that match regex
.
Return value
None.
regex
The regular expression used to match on the name.
All Cookies which match regex
are deleted.
This value is static and cannot change between calls.
delete_keep
If delete_keep
is true
, delete kept Cookies. Defaults to false
.
VOID keep(STRING name)
Description
Keep Cookies which match name
. This enables keep_mode. When writing, only Cookies
which have been kept are written.
Return value
None.
name
The name of the Cookie to keep. All Cookies which match name
are kept.
VOID keep_regex(STRING regex)
Description
Keep Cookies which match regex
. This enables keep_mode. When writing, only Cookies
which have been kept are written.
Return value
None.
regex
The regular expression used to match on the name.
All Cookies which match regex
are kept.
This value is static and cannot change between calls.
VOID remove_deleted(STRING name)
Description
vmod-cookieplus
keeps track of what Cookies have been deleted. This is so you can
delete them from the client using setcookie_add_deleted()
. This function removes
a Cookie from the deleted list, so it cannot be removed from the client.
Return value
None.
name
The name of the Cookie to remove from the deleted Cookie list.
All Cookies which match name
are deleted.
VOID remove_deleted_regex(STRING regex)
Description
vmod-cookieplus
keeps track of what Cookies have been deleted. This is so you can
delete them from the client using setcookie_add_deleted()
. This function removes
Cookies which match regex
from the deleted list, so they cannot be removed from the client.
Return value
None.
regex
The regular expression used to match on the name of deleted Cookies.
All Cookies which match regex
are deleted.
This value is static and cannot change between calls.
VOID regsub(STRING name, ENUM {NAME, VALUE} where, STRING pattern, STRING replace, BOOl repeat = false)
Description
Cookies that match the regular expression name
can have their name or value replaced
based off the regular expression pattern
with replace
.
Return value
None.
name
The name of the Cookie to modify.
where
Should the name or the value be substituted.
pattern
Regex pattern to match on the name or value.
replace
String to repalce the value with. This string can contain backreferences.
repeat
Replace all occurances. Defaults to false
.
INT count()
Description
Count the number of Cookies which will be written.
Return value
The number of Cookies which will be written.
VOID write()
Description
Write Cookies back out to the Cookie
header.
Return value
None.
STRING as_string()
Description
Return Cookie header string. Can be used to write cookies to a different header.
Return value
A Cookie header formatted string.
VOID parse(STRING cookies)
Description
Parse Cookie values from cookies
.
Return value
None
cookies
The value to parse Cookies from.
VOID reset()
Description
Reset the internal state for Cookies.
Return value
None.
STRING setcookie_get(STRING name, STRING default)
Description
Get the Set-Cookie value for name
.
Return value
The Set-Cookie value for name
. If not found, default
is returned.
name
The name of the Cookie. The first Set-Cookie to match is used.
default
The return value if name
is not found.
STRING setcookie_get_regex(STRING regex, STRING default)
Description
Get the Set-Cookie value where the name matches regex
.
Return value
The Set-Cookie value where the name matches regex
. If not found, default
is returned.
regex
The regular expression used to match on the name. Only the first matching Set-Cookie is used. This value is static and cannot change between calls.
default
The return value if no matching Set-Cookie is not found.
VOID setcookie_add(STRING name, STRING value, DURATION ttl = 0, STRING domain = "",
STRING path = "", BOOL secure = false, BOOL httponly = false, STRING extra = "",
BOOL keep = true, BOOL override = true)
Description
Add a Set-Cookie.
Return value
None
name
The Set-Cookie name.
value
The Set-Cookie value.
ttl
The Cookie expiration. Defaults to 0
, which is a session only Cookie.
A negative ttl
deletes the cookie.
domain
The Cookie domain. Defaults to no domain.
path
The Cookie path. Defaults to no path.
secure
Is this Cookie secure (HTTPS only)? Defaults to false
.
httponly
Is this Cookie HTTP only (no Javascript access)? Defaults to false
.
extra
Extra Set-Cookie attributes which are appended to the header.
keep
If in keep_mode and keep
is true, the Set-Cookie is always kept when writing.
Defaults to true
.
override
If the Set-Cookie name exists, override it. Defaults to true
.
VOID setcookie_add_deleted(BOOL keep = true)
Description
Add a Set-Cookie delete headers for Cookies that were previously deleted.
Return value
None
keep
If in keep_mode and keep
is true, these Set-Cookies are always kept when writing.
Defaults to true
.
VOID setcookie_delete(STRING name, BOOL delete_keep = false)
Description
Delete all Set-Cookies that match name
.
Return value
None.
name
The name of the Set-Cookie to delete. All Set-Cookies which match name
are deleted.
delete_keep
If delete_keep
is true
, delete kept Set-Cookies. Defaults to false
.
VOID setcookie_delete_regex(STRING regex, BOOL delete_keep = false)
Description
Delete all Set-Cookies that match regex
.
Return value
None.
regex
The regular expression used to match on the name.
All Set-Cookies which match regex
are deleted.
This value is static and cannot change between calls.
delete_keep
If delete_keep
is true
, delete kept Set-Cookies. Defaults to false
.
VOID setcookie_keep(STRING name)
Description
Keep Set-Cookies which match name
. This enables keep_mode. When writing, only Set-Cookies
which have been kept are written.
Return value
None.
name
The name of the Set-Cookie to keep. All Set-Cookies which match name
are kept.
VOID setcookie_keep_regex(STRING regex)
Description
Keep Set-Cookies which match regex
. This enables keep_mode. When writing, only Set-Cookies
which have been kept are written.
Return value
None.
regex
The regular expression used to match on the name.
All Set-Cookies which match regex
are kept.
This value is static and cannot change between calls.
VOID regsub(STRING name, ENUM {NAME, VALUE} where, STRING pattern, STRING replace, BOOl repeat = false)
Description
Set-Cookies that match the regular expressoin name
can have their name or value replaced
based off the regular expression pattern
with replace
.
Return value
None.
name
The name of the Set-Cookie to modify.
where
Should the name or the value be substituted.
pattern
Regex pattern to match on the name or value.
replace
String to repalce the value with. This string can contain backreferences.
repeat
Replace all occurances. Defaults to false
.
INT setcookie_count()
Description
Count the number of Set-Cookies which will be written.
Return value
The number of Set-Cookies which will be written.
VOID setcookie_write(HEADER header = (be)resp.http.Set-Cookie)
Description
Write Set-Cookies back out to the Set-Cookie
header.
Return value
None.
header
The response header to write the Set-Cookie values to.
Defaults to Set-Cookie
.
VOID setcookie_parse(HEADER header)
Description
Parse Set-Cookie values from header
.
Return value
None
header
The header to parse Set-Cookie values from.
VOID setcookie_reset()
Description
Reset the internal state for Set-Cookies.
Return value
None.
STRING as_json(ENUM {COOKIE, SETCOOKIE, BOTH) print = BOTH}
Description
Return Cookie name and value pairs as JSON.
Return value
JSON formatted string of Cookie name-value pairs.
Construct the string of only Cookies, only Set-Cookies or both Cookies and Set-cookies.