4.2 Request modifications

A service can modify requests before forwarding them to backends. Several statements are provided for that purpose:

SetHeader

Set a HTTP header.

DeleteHeader

Delete a HTTP header.

SetURL

Rewrite the request URL.

SetPath

Rewrite the path part of the URL.

SetQuery

Rewrite the query part of the URL.

SetQueryParam

Set a single query parameter.

For example, the following service declaration will add the header ‘X-Resent-By: pound’ to each request:

Service
    SetHeader "X-Resent-By: pound"
    Backend
       ...
    End
End

Arguments to request modification statements are expanded before actual use. During expansion, references to parenthesized subexpressions in matching rules are replaced with their actual values. Parenthesized subexpression is a part of a regular expression enclosed in parentheses. It can be referred to in string arguments as ‘$n’, where n is its ordinal number. Numbers start at one, ‘$0’ referring to the entire string that matched.

The process of expanding parenthesized subexpressions is called backreference expansion.

For example, the following condition:

Header "Content-Type: ([^/]+)/(.+)$"

has two subexpressions: ‘$1’ and ‘$2’. The following fragment uses these values to add two query parameters to the URL:

SetQueryParam "type" "$1"
SetQueryParam "subtype" "$2"

As a more practical example, the following service rewrites the path to JPEG and GIF images:

Service
    Path "/([^/]+\\.(jpg|gif))$"
    SetPath "/images/$1"
    ...
End

When several matching statements are used, these forms refer to the last one that matched. Subexpressions in prior statements can be referred to using the ‘$i(j)’ construct. Here, j is the 0-based number of the statement, counted from the last one upwards. For example, given the following statements:

Host -re "www\.(.+)"
Header -icase "^Content-Type: *(.*)"
Path "^/static(/.*)?"

‘$1’ refers to the subexpression of Path, ‘$1(1)’ to that of Header, and $1(2) to that of Host.

String arguments to Set statements can also contain request accessors – special constructs that are expanded to particular values from the request. Syntactically, a request accessor is ‘%[name]’, where name denotes the request part to access. For example, %[url] expands to entire URL, %[path] to the path part of the URL, etc.

Using request accessors, the above example of path modification can be rewritten as:

Path "\\.(jpg|gif)$"
SetPath "/images%[path]"

See Request Accessor Interpretation, for a detailed discussions of available accessors.