headerplus
is a VMOD for advanced header access, creation and manipulation for
singular headers, multiple headers of the same name, or groups of headers through regex.
Additionally this VMOD provides an easy to use API to access and manipulate individual
attributes from a header.
Documentation for the legacy vmod-header
can be found here.
import headerplus;
sub vcl_backend_response {
headerplus.init(beresp);
set bereq.http.stale-if-error = headerplus.attr_get("Cache-Control", "stale-if-error");
if (bereq.http.stale-if-error != "") {
set beresp.keep = std.duration(bereq.http.stale-if-error + "s", 11s);
}
}
import headerplus;
sub vcl_recv {
headerplus.init(req);
headerplus.delete_regex("^X-");
headerplus.write();
}
import headerplus;
import ykey;
sub vcl_backend_response {
headerplus.init(beresp);
headerplus.collapse_regex("^ykey-", "all-ykey");
headerplus.write();
ykey.add_key(beresp.http.all-key);
}
import headerplus;
sub vcl_recv {
headerplus.init(req);
headerplus.keep("Host");
headerplus.keep("X-Forwarded-For");
headerplus.keep("Connection");
headerplus.keep("Accept-Language");
headerplus.keep("Accept-Encoding");
headerplus.keep("Referer");
headerplus.keep("User-Agent");
headerplus.keep("Authorization");
headerplus.keep("Cookie");
headerplus.keep_regex("^Upgrade-.*");
headerplus.keep_regex("^Sec-.*");
headerplus.write();
}
init()
is required to be called before using any other function. All functions keep an
internal state of the URL until it is written out using write()
. This VMOD uses a state
called keep
mode. This is enabled by calling keep()
or keep_regex()
. This acts in the
opposite way of delete()
. When calling keep()
or keep_regex()
, all headers except
the ones matching the name specified in the function will be marked for deletion. These two
functions can be called multiple times to keep multiple headers. All parameters that use regex (noted by a _re
suffix) must be a static string and cannot change between requests. Regex on header names
(noted by name_re
) are case insensitive.
VOID init(HTTP scope)
Set up the internal state of headers. This is required to be called before any of the below functions can be used.
Arguments
HTTP scope
- The set of headers to use. This can be req
, bereq
, resp
, or beresp
.VOID write()
Write out the internal state of headers to the scope.
Arguments
None.
Returns
Nothing.
VOID reset()
Clear the internal state of headers.
Arguments
None.
Returns
Nothing.
VOID add(STRING name, STRING value, BOOL keep = true)
Add a new header. This function does not overwrite or remove headers of the same name.
Arguments
STRING name
- The name of the header to add.STRING value
- The value of the header to add.BOOL keep
optional
- Indicate if the header should be kept.Returns
Nothing.
VOID set(STRING name, STRING value, BOOL keep = true)
Set a new header. Removes all previous headers of the same name.
Arguments
STRING name
- The name of the header to add.STRING value
- The value of the header to add.BOOL keep
optional
- Indicate if the header should be kept.Returns
Nothing.
VOID append(STRING name, STRING value, STRING delim = ", ", BOOL all = false, BOOL keep = true)
Append a value to the end of a header. If the header is not present, add a new header.
Arguments
STRING name
- The name of the header to add.STRING value
- The value of the header to add.STRING delim
optional
- The delimiter to separate values.BOOL all
optional
- If true
, append to all headers with name name
.BOOL keep
optional
- If a header is found the keep value is inherited from that header. If not found, use this keep
to indicate if the header should be kept.Returns
Nothing.
STRING get(STRING name, STRING value_re, STRING def = NULL)
Return the value of the first header matching name
. If value_re
is
present, the value must match as well.
Arguments
STRING name
- The name of the header to get the value of.STRING value_re
optional
- A regex to match against the header value.STRING def
optional
- A string to return if no matching headers are found.Returns
The value of the first matching header.
STRING get_regex(STRING name_re, STRING value_re, STRING def = NULL)
Return the value of the first header matching name_re
. If value_re
is
present, the value must match as well.
Arguments
STRING name_re
- A regex to match against the header name.STRING value_re
optional
- A regex to match against the header value.STRING def
optional
- A string to return if no matching headers are found.Returns
The value of the first matching header.
STRING get_name_regex(STRING name_re, STRING value_re)
Return the name of the first header matching name_re
. If value_re
is present,
the value must match as well. If name_re
is not present and value_re
is,
return the name of the first header with a value matching `value_re. If neither are
present, return the first header.
Arguments
STRING name_re
optional
- A regex to match against the header name.STRING value_re
optional
- A regex to match against the header value.Returns
The value of the first matching header.
STRING collapse(STRING name, STRING new_name, STRING delim=", ", BOOL keep = true)
Collapse all headers with name name
.
Arguments
STRING name
- The name of the headers to merge.STRING new_name
optional
- New name of the collapsed header. If not present, the name is kept as is.STRING delim
optional
- The deliminator for the header values.BOOL keep
optional
- Indicate if the header should be kept.Returns
The value of the collapsed header.
STRING collapse_regex(STRING name_re, STRING new_name, STRING delim=", ", BOOL keep = true)
Collapse all headers with name matching the regex name_re
into a new header new_name
.
Arguments
STRING name_re
- A regex to match against the header name.STRING new_name
- New name of the collapsed header.STRING delim
optional
- The deliminator for the header values.BOOL keep
optional
- Indicate if the header should be kept.Returns
The value of the collapsed header.
VOID split(STRING name, STRING delim=", ")
Split headers with name name
into multiple headers, breaking up the value by delim
.
The keep value is inherited from the original header.
Arguments
STRING name
- The name of the headers to merge.STRING delim
optional
- The deliminator for the header values.Returns
Nothing.
INT conut(STRING name)
Count the number of headers with name name
.
Arguments
STRING name
- The name of the headers to count.Returns
The number of headers with name name
.
INT conut_regex(STRING name_re)
Count the number of headers with name matching the regex name_re
.
Arguments
STRING name_re
- A regex to match against the header name.Returns
The number of headers with name name
.
VOID keep(STRING name)
Keep all headers with name name
. This enables keep mode.
Arguments
STRING name
- The name of the headers to keep.Returns
Nothing.
VOID keep_regex(STRING name_re)
Keep all headers with name matching the regex name_re
. This enables keep mode.
Arguments
STRING name_re
- A regex to match against the header name.Returns
Nothing.
VOID delete(STRING name, BOOL delete_keep = false)
Delete all headers with name name
.
Arguments
STRING name
- The name of the headers to delete.BOOL delete_keep
optional
- When in keep mode, should kept headers also be deleted.Returns
Nothing.
VOID delete_regex(STRING name_re, BOOL delete_keep = false)
Delete all headers with name matching the regex name_re
.
Arguments
STRING name_re
- A regex to match against the header name.BOOL delete_keep
optional
- When in keep mode, should kept headers also be deleted.Returns
Nothing.
VOID rename(STRING name, STRING new_name, BOOL remove = true)
Rename all headers with name name
to new_name
.
Arguments
STRING name
- The name of the headers to delete.BOOL remove
optional
- If true
remove the original header. Otherwise add a new header.Returns
Nothing.
VOID regsub_name(STRING name_re, STRING sub, BOOL all = false, BOOL remove = true)
Perform a regular expression substitution on all headers with name matching the regex name_re
, substituting the name
with substitution pattern sub
.
Arguments
STRING name_re
- The regex to match against the header name. This parameter can contain grouping to be used with the parameter sub
.STRING sub
- The substitution pattern to change the name to. This parameters supports backreferences.BOOL all
optional
- If true
continue the substitution on the header name matching name_re
.BOOL remove
optional
- If true
remove the original header. Otherwise add a new header.Returns
Nothing.
VOID regsub_value(STRING name_re, STRING value_re, STRING sub, BOOL all = false, BOOL remove = true)
Perform a regular expression substitution on all headers with name matching the regex name_re
, substituting the name
with substitution pattern sub
.
Arguments
STRING name_re
- The regex to match against the header name. This parameter can contain grouping to be used with the parameter sub
.STRING sub
- The substitution pattern to change the name to. This parameters supports backreferences.BOOL all
optional
- If true
continue the substitution on the header name matching name_re
.BOOL remove
optional
- If true
remove the original header. Otherwise add a new header.Returns
Nothing.
VOID prefix(STRING name, STRING prefix, BOOL remove = true)
Add a prefix to all headers matching the regex name_re
.
Arguments
STRING name_re
- A regex to match against a header name. Note that this parameter is
grouped by default.STRING prefix
- The string to prefix the matching headers with.BOOL remove
optional
- If true
remove the original header. Otherwise add a new header.Returns
Nothing.
VOID suffix(STRING name, STRING suffix, BOOL remove = true)
Add a suffix to all headers matching the regex name_re
.
Arguments
STRING name_re
- A regex to match against a header name. Note that this parameter is
grouped by default.STRING suffix
- The string to suffix the matching headers with.BOOL remove
optional
- If true
remove the original header. Otherwise add a new header.Returns
Nothing.
STRING as_list(ENUM {BOTH, NAME, VALUE} which = BOTH, STRING hdr_delim = ", ", STRING value_delim = ": ", BOOL sort = 1, ENUM {NONE, LOWER, UPPER} name_case = NONE)
Turn set of headers to a list.
Arguments
ENUM which
optional
- Which part of the header to display, the name, the value or both name and value.STRING hdr_delim
optional
- How should the headers be separated.STRING value_delim
optional
- When which
is BOTH
how should the header name be separated from the header value.BOOL sort
optional
- Should the list be sorted.ENUM name_case
optional
- Options to normalize the header name.Returns
The list of header names and or values.
STRING as_json(ENUM {FIRST, LAST, ARRAY, ALL} which = FIRST)
Turn set of headers to a JSON string in the format of {"header":"value"}
.
Arguments
ENUM which
optional
- Which header to use if there are multiple headers
with the same name. FIRST
will pick the first header. LAST
will pick the last header.
ARRAY
will format the values into an array of strings. For example, {"X-ample": ["a", "b", "c"]}
.
ALL
will use all headers.Returns
A string of the set of headers as a JSON string.
VOID from_json(STRING json, BOOL overwrite = false, BOOL keep = true)
Add the values of a JSON string as headers. The format should be {"name": "value"}
.
To add multiple headers an array should be used. For example, {"X-ample": ["a", "b", "c"]}
will result in 3 headers with the name of X-ample
with the values of a
, b
, and c
.
Arguments
STRING json
- The JSON to convert to headers.BOOL overwrite
optional
- If true
remove the original header. Otherwise add a new header.
Multiple headers with the same name in json
will not be overwritten.BOOL keep
optional
- Indicate if the header should be kept.Returns
Nothing.
STRING attr_get(STRING name, STRING attr, STRING hdr_delim = ", ", STRING attr_delim = "=", STRING def = NULL)
Return the value of the attribute of a header name
. For example if header
Cache-Control: public, max-age=123
is present, given name
Cache-Control and attr
max-age, 123 is returned.
Arguments
STRING name
- The name of the headers to get the attribute of.STRING attr
- The attribute to get the value of.STRING hdr_delim
optional
- The deliminator separating the attributes.STRING attr_delim
optional
- The deliminator separating the attribute from the value.STRING def
optional
- A string to return if no matching attributes are found.Returns
The value of the matching attribute.
VOID attr_set(STRING name, STRING attr, STRING value, STRING hdr_delim = ", ", STRING attr_delim = "=", ENUM {FIRST, UPDATE, ALL} how = FIRST)
Set the value of the attribute of a header name
. For example if header
Cache-Control: public, max-age=123
is present, given name
Cache-Control
and attr
max-age, max-age will be set to value
.
Arguments
STRING name
- The name of the headers to get the attribute of.STRING attr
- The attribute to get the value of.STRING value
- The value set the attribute to.STRING hdr_delim
optional
- The deliminator separating the attributes.STRING attr_delim
optional
- The deliminator separating the attribute from the value.ENUM how
optional
- How the attribute should be set. If set to FIRST
update the first
header with name name
and attr
present. If not found, append the value to the first header with name name
.
If set to UPDATE
only set the attribute value if both name
and attr
are present.
If set to ALL
all headers with name name
will have either the attribute appended, if attribute is not in the header, or update, if the attribute is in the header.Returns
Nothing.
VOID attr_delete(STRING name, STRING attr, STRING hdr_delim = ", ", BOOL all = false)
Remove an attribute from a header. For example the max-age attribute can be removed from Cache-Control: public, max-age=123
by using a name
of Cache-Control and attr
of max-age.
If the header is empty after removing attr
the header will be deleted.
Arguments
STRING name
- The name of the headers to get the attribute of.STRING attr
- The attribute to get the value of.STRING hdr_delim
optional
- The deliminator separating the attributes.BOOL all
optional
- If true
remove from all headers with name name
. Otherwise
only remove the attribute from the first header with name name
.Returns
Nothing.