Header Manipulation (Headerplus)

Description

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.

Examples

Set keep if the Cache-Control stale-if-error exists

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

Delete all headers starting with X-

import headerplus;

 sub vcl_recv {
        headerplus.init(req);
        headerplus.delete_regex("^X-");
        headerplus.write();
}

Combine all ykey headers

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

Whitelist a set of headers

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

Functions

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.

init

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.

write

VOID write()

Write out the internal state of headers to the scope.

Arguments

None.

Returns

Nothing.

reset

VOID reset()

Clear the internal state of headers.

Arguments

None.

Returns

Nothing.

add

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.

set

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.

append

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.

get

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.

get_regex

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.

get_name_regex

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.

collapse

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.

collapse_regex

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.

split

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.

count

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.

count_regex

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.

keep

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.

keep_regex

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.

delete

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.

delete_regex

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.

rename

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.

regsub_name

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.

regsub_value

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.

prefix

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.

suffix

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.

as_list

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.

as_json

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.

from_json

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.

attr_get

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.

attr_set

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.

attr_delete

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.