Modifier Reference¶
Modifiers are a way to modify or filter features.
Modifiers¶
- else¶
The else
modifier leaves the feature unchanged unless it is the NULL
value or is
an empty string. In that case, the feature is changed to be the value of the modifier key.
- hash¶
Compute the hash of a feature and take the result modulo the value. This modifier requires a value that is a positive integer.
- filter¶
Filter is intended to operate on lists, although it will work on a single value as if it were a list of length 1.
The purpose of filter is to create a new list based on the input list. The common form of this is to remove elements.
The modifier takes a list of comparisons, each of which can have an attached action as a key. The valid action keys are
- pass
Pass the item through to the new list unchanged.
- drop
Do not pass the item to the new list, in effect removing it.
- replace
Add an item to the new list in place of the original element. This key takes a feature expression which is the new value to put in the new list.
It is an error to have more than one action for a comparison.
If no action is specified with a comparison, a match will pass
the item. If an action has no
comparison, it always matches. The comparisons are checked in order for each element and the first
match determines the action for that element. If there are no matches, the item is dropped. This
makes it easy to remove elements. To remove any “set-cookie” field with the loopback address in it -
[ proxy-rsp-field<set-cookie> , { filter: [ { contains: "127.0.0.1", drop: }, { pass: } ] } ]
or long hand
- proxy-rsp-field<set-cookie>
- filter:
- contains: "127.0.0.1"
drop:
- pass:
It is not permitted to have a do
key with any of the comparisons.
See Filter Techniques for examples of using this modifier.
- join¶
- Argument:
- Separator
Join features in to a string. The value is used as the separator between elements. If used on a scalar feature it will simply convert that feature to a string. If used on tuple it will convert each tuple element to a string and concentate the result, placing the separator between the strings. Nested tuples are placed in brackets and the modifier recursively applied. NULL elements are discared, but empty strings are retained.
- concat¶
- Argument:
- List of separator, string
Concatenate a string. This takes a list of two values, the separator and the string. If the active feature is a non-empty string, and the string value for the modifier is not empty, the latter is appended to the active feature. The separator is appended first if the active feature does not already end with the separator. For example
[ pre-remap-path , { concat: [ "/" , "albums" ] } ]
will add “albums” to the pre-remap path. If that path is “delain” the result is “delain/albums”. If the path is “delain/” the result is still “delain/albums”.
A common use is to attach a query string to a URL while avoiding adding “?” if there is no query stirng. E.g.
[ "http://delain.nl/albums/{pre-remap-path}", { concat: [ "?" , pre-remap-query ] } ]
which propagate the query string without creating a URL ending in “?”. If there was no query
string pre-remap-query
will be the empty string and the modifier will not change the
string.
This can be used to append separated strings even on empty fields. For instance, to make sure the list of rock bands contains “Delain”, it would be
- proxy-req-field<bands>:
- proxy-req-field<bands>
- concat: [ ",", "Delain" ]
An empty field is changed to “Delain”, while if there is already a value, a comma is added before adding “Delain”.
- as-bool¶
Coerce the feature to a Boolean if possible. The following types can be coerced
- Boolean
Identity.
- Integer
0 is false, any other value is true.
- Float
0.0 is false, anything else is true.
- String
False unless the string is one of “true”, “1”, “on”, “enable”, “Y”, “yes”.
- IP Address
A valid IP address is true, otherwise false.
- Duration
A non-zero duration is true, otherwise false.
- Tuple
A non-zero length tuple is true, otherwise false. Note the value(s) in the tuple are not examined.
- Null
False.
- as-integer¶
Coerce the feature to an Integer type if possible. If the feature is already an Integer, it is
left unchanged. If it is a string, it is parsed as an integer string and if that is successfull, the
feature is changed to be the resulting integer value. If not, the modifier value is used. This is the
NULL
value if unspecified.
- as-duration¶
Convert to a duration. If the feature is a string the conversion is done based on following table.
Duration |
Names |
---|---|
nanoseconds |
ns, nanoseconds |
microseconds |
us, microseconds |
milliseconds |
ms, milliseconds |
second |
s, sec, second, seconds |
minute |
m, min, minute, minutes |
hour |
h, hour, hours |
day |
d, day, days |
week |
w, week, weeks |
The string must consist of pairs, each pair an integer followed by a name. Spaces are ignored, but can be added for clarity. The duration for the string is the sum of all the pairs, irrespective of order. For instance, a duration of ninety minutes could be “90 minutes”, “90m”, “1h 30m”, “30 m 1 hour”, “5400 sec”, or even “900 s1 hours15 minute”. Note the singular vs. plural forms are purely for convenience. “1 day” and “1 days” are indistinguishable, as are “10 minute” and “10 minutes”.
If used on a tuple, each element will be coerced to a duration and all of the durations summed.
- as-ip-addr¶
Convert to an IP address or range. If the conversion can not be done, the result is NULL
.
- ip-space¶
- Argument:
- IP Space name
This modifier must be used in conjunction with ip-space-define
. The latter defines and
loads an IP space. This modifier changes an IP address feature into a row from the named IP
Space. The value for the modifier is a feature expression in which ip-col
can be used to
extract data from the row. The value of that expression replaces the IP address.
- as-text-block¶
- Argument:
- Block name as a string.
Convert a string in to the contents of a text block. The active value is treated as the name. The modifier value is used if there is no block for the name. If there is no block and no name the result is an empty string.
- url-encode¶
- Value:
- string
The url-encode
perform percent-encoding of a feature, this provides a mechanism for encoding information in a
Uniform Resource Identifier (URI). This modifier uses the Traffic Server api TSStringPercentEncode
to perform the encoding.
In addition we are using a custom map optional in the mentioned API) to deal with reserved characters(RFC2396:Sec 2.2).
reserved = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
"$" | ","
The following example shows how a particular field can be encoded.
- with: proxy-req-field<comets>
select:
- is-null: # field not present.
- do:
# encode it.
- proxy-req-field<comets>: [ proxy-req-field<comets>, { url-encode: } ]
Perform a redirect and apply the url-encode
to pre-remap-query
in combination with concat
.
- redirect:
location:
- "http://delta.ex/{pre-remap-path}"
- concat:
- "?"
- [ pre-remap-query , { url-encode: } ]
status: 302
reason: "Because he said so! "
- url-decode¶
- Value:
- string
The url-decode
perform percent-decoding of a feature, this provides a mechanism for encoding information in a
Uniform Resource Identifier (URI).This internally uses the Traffic Server api TSStringPercentDecode
to perform the decoding.
The following example shows how a particular field can be encoded.
- with: proxy-req-field<comets-encoded>
select:
- is-null: # field not present.
- do:
# decode it.
- proxy-req-field<comets-decoded>: [ proxy-req-field<comets-encoded>, { url-decode: } ]
Perform a redirect and apply the url-decode
to pre-remap-query
in combination with concat
.
- redirect:
location:
- "http://delta.ex/{pre-remap-path}"
- concat:
- "?"
- [ pre-remap-query , { url-decode: } ]
status: 302
reason: "Because he said so! "
- query-sort¶
- Argument:
- ``nc``, ``rev``
Sort a query string by name.
nc
Caseless comparison for sorting.
rev
Sort in reverse (descending) order.
- query-filter¶
This is designed to work with URL query strings in a manner similar to filter
. The filter
is applied to each element in the query string. Comparisons match on the name. The basic actions
are the same as filter
.
- pass
Pass element to the output unchanged.
- drop
Do not pass the element to the output (the element is removed).
- replace
Replace the element with a new element. This can have two nested keys,
name
andvalue
. These are optional and should contain feature expressions which will replace the existing text.
It is an error to have more than one action for a comparison.
It is an error to have a do
key with any of the comparisons.
If no action is specified with a comparison, a match will pass
the item. If an action has no
comparison, it always matches. The comparisons are checked in order for each element and the first
match determines the action for that element. If there are no matches, the item is dropped.
In addition to actions there are a set of options which are attached to the option
key with
the comparison. These nested keys are
- value
This must contain a comparison which is applied to the value for the element.
- append
Append a new element to the output. This requires a list of two elements, the name and value. This will be added after the current element (if passed or replaced). It is valid to
drop
the current element and thenappend
, although that is more easily done by using the list form ofreplace
.
append-unique
NOT IMPLEMENTED
As
append
but only once. If this is used, the name for the appended element will appear exactly once in the modified query string. Using this will effect all elements with the name, regardless of how such elements are added to the output. If some previous element was passed with this name, this append will be dropped to satisfy the uniqueness.
- pass-rest
Stop filtering - all remaining elements are passed.
- drop-rest
Stop filtering - all remaining elements are dropped.
For feature expressions in the scope of this modifier the extractors name
and value
are
locally bound to the name and value of the current element.
Example - drop all elements with the name “email” if the address is for “base.ex”.
query-filter:
- match: "email"
option:
value:
suffix: "@base.ex"
drop:
- pass: # everything else pass on through.
Change the name “x-email” to “email” for all elements.
query-filter:
- match: "x-email"
replace:
name: "email"
- pass:
Make every value more exciting.
query-filter:
- replace:
value: "{value}!"
- rxp-replace¶
- Argument:
- nc, g
Perform a regular expression based search and replace on a string. This takes a list of two elements, the pattern and the replacement. As is common this modifier searches the value a match for the regular expression pattern. If found the text matching pattern is removed and replaced by replacement*. Capture group extractors are available to extract text from the matched text.
PCRE syntax is used for the regular expression.
The arguments are
- nc
Case insensitive matching.
- g
Global - after a match and replacement, the remaining string is searched for further matches.