Search
Varnish Cache Plus

Uniform Resource Identifier (uri)

Description

VMOD-URI let you parse a URI into the five generic components: scheme, authority, path, query and fragment, as described by RFC3986. VMOD-URI makes no attempt to verify if the URI is using the scheme correctly, but rather it extracts the generic components, if present, of an URI.

parse is usually called before any other functions, but in case of no prior call an implicit parse will take place with the default parameters before the function itself will run.

Example VCL

Rewrite the location header from the backend

vcl 4.1;

import uri;

sub vcl_backend_response {
	if (beresp.status == 301 || beresp.status == 302) {
		uri.parse(beresp.http.location);
		uri.set_port();
		set beresp.http.location = uri.as_string();
		set beresp.reason = "Moved";
	}
}

Follow redirects from the backend

vcl 4.1;

import goto;
import uri;

sub vcl_backend_response {
	call follow_redirects;
}

sub follow_redirects {
	if (beresp.status == 301 || beresp.status == 302) {
		uri.parse(beresp.http.location);
		uri.write();
		set bereq.backend = goto.dns_backend(uri.as_string(), ttl_rule = abide, ignore_update = onempty);
		return(retry);
	}
}

API

parse

VOID parse([STRING input], BOOL norm = 0)

Parse a URI and build the corresponding internal state, any information from the previous state is overwritten. The URI must be provided in the percent-encoded format. No mandatory components, meaning a URI lacking components is as valid as a full URI containing all components. The authority component must start with two forward slashes, and a path must start with a forward slash if an authority component is also present.

If input is not present, as it is optional, parse will use the combined value of be/req.http.Host + be/req.url. However, if input is present, but happens to be NULL, or empty, then all internal states will be initiated but left empty.

If norm is true, the internal state is also rebuilt to reflect the safe normalization process of RFC3986 Section 6.

The generic normalization process (safe):

  • Remove percent-encoding for unreserved characters.

  • Convert upper-case letters to lower-case in both the host and the scheme component.

  • Convert remaining lower-case percent-encoding to upper-case.

  • Employ remove_dot_segments algorithm to the path component, see RFC3986 Section 5.2.4.

  • Convert empty path to “/” when an authority component is present.

  • Removes default port for some commonly understood schemes: http (80), https (443), ftp (21), ssh (22).

write

VOID write()

Replace the combined value of be/req.http.Host + be/req.url with the currently loaded internal state. The scheme and userinfo component are currently ignored as they are not in use.

reset

VOID reset()

Reset internal state of the VMOD back to its default.

as_string

STRING as_string(STRING fmt = "%S%A%P%Q%F", BOOL decode = 0)

Build and return a URI based on the current internal state. Use fmt to decide how and what to return. The default is to return all components, as described by RFC3986 Section 5.3.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

fmt is a format string, valid percent-tokens are:

  • %% - outputs a single percent.

  • %S - outputs the scheme component of the internal state.

  • %A - outputs the autority component of the internal state.

  • %U - outputs the userinfo component of the internal state.

  • %H - outputs the host component of the internal state.

  • %p - outputs the port component of the internal state.

  • %P - outputs the path component of the internal state.

  • %Q - outputs the query component of the internal state.

  • %F - outputs the fragment component of the internal state.

get_scheme

STRING get_scheme()

Returns the scheme found in the currently loaded internal state, or NULL if there is none.

set_scheme

VOID set_scheme(STRING new = "")

Sets the scheme found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_userinfo

STRING get_userinfo(BOOL decode = 0)

Returns the user information found in the currently loaded internal state, or NULL if there is none.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

set_userinfo

VOID set_userinfo(STRING new = "")

Sets the user information found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_host

STRING get_host(BOOL decode = 0)

Returns the host found in the currently loaded internal state, or NULL if there is none.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

set_host

VOID set_host(STRING new = "")

Sets the host found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_port

STRING get_port()

Returns the port found in the currently loaded internal state, or NULL if there is none.

set_port

VOID set_port(STRING new = "")

Sets the port found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_path

STRING get_path(BOOL decode = 0)

Returns the path found in the currently loaded internal state, or NULL if there is none.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

set_path

VOID set_path(STRING new = "")

Sets the path found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_query

STRING get_query(BOOL decode = 0)

Returns the query found in the currently loaded internal state, or NULL if there is none.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

set_query

VOID set_query(STRING new = "")

Sets the query found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.

get_fragment

STRING get_fragment(BOOL decode = 0)

Returns the fragment found in the currently loaded internal state, or NULL if there is none.

If decode is true, then before returning an attempt will be made to remove percent encoding for any reserved characters.

set_fragment

VOID set_fragment(STRING new = "")

Sets the fragment found in the currently loaded internal state.

In case of no new string given (default), the previous string from the internal state is cleared.