jimbocoder / libvmod-querystring

A general-purpose querystring manipulation module for Varnish

vmod_querystring

Varnish QueryString Module

Author:	Dridi Boukelmoune
Date:	2012-06-18
Version:	0.2
Manual section:	3

SYNOPSIS

import querystring;

DESCRIPTION

Varnish multipurpose vmod for URI query-string manipulation. Can be used to normalize for instance request URLs or Location response headers in various ways. It is recommended to at least clean incoming request URLs (removing empty parameters or query-strings), all other functions do the cleaning.

FUNCTIONS

clean

Prototype

clean(STRING url)

Return value

STRING

Description

Returns the given URI without empty parameters. The query-string is removed if empty (either before or after the removal of empty parameters).

Example

set req.url = querystring.clean(req.url);

remove

Prototype

remove(STRING url)

Return value

STRING

Description

Returns the given URI with its query-string removed

Example

set req.url = querystring.remove(req.url);

sort

Prototype

sort(STRING url)

Return value

STRING

Description

Returns the given URI with its query-string sorted

Example

set req.url = querystring.sort(req.url);

filter

Prototype

filter(STRING url, STRING_LIST parameter_names)

Return value

STRING

Description

Returns the given URI without the listed parameters

Example

set req.url = querystring.filter(req.url,
  "utm_source" + querystring.filtersep() +
  "utm_medium" + querystring.filtersep() +
  "utm_campaign");

filtersep

Prototype

filtersep()

Return value

STRING

Description

Returns the separator needed by the filter function

regfilter

Prototype

regfilter(STRING url, STRING parameter_names_regex)

Return value

STRING

Description

Returns the given URI without the parameters matching a regular expression

Example

set req.url = querystring.regfilter(req.url, "utm\_.*");

EXAMPLES

In your VCL you could then use this vmod along the following lines:

import querystring;

sub vcl_hash {
   # sort the URL before the request hashing
   set req.url = querystring.sort(req.url);
}

You can use regfilter to specify a list of arguments that must not be removed (everything else will be) with a negative look-ahead expression:

set req.url = querystring.regfilter(req.url, "^(?!param1|param2)");

ACKNOWLEDGMENT

The sort algorithm is a mix of Jason Mooberry's Skwurly and my own QuerySort with regards for the Varnish workspace memory model of the worker threads.

COPYRIGHT

This document is licensed under the same license as the libvmod-querystring project. See LICENSE for details.

• Copyright (c) 2012 Dridi Boukelmoune