Product Documentation

Expressions for HTTP and Cache-Control Headers

Feb 13, 2017

One common method of evaluating HTTP traffic is to examine the headers in a request or a response. A header can perform a number of functions, including the following:

  • Provide cookies that contain data about the sender.
  • Identify the type of data that is being transmitted.
  • Identify the route that the data has traveled (the Via header).
Note: Note that if an operation is used to evaluate both header and text data, the header-based operation always overrides the text-based operation. For example, the AFTER_STR operation, when applied to a header, overrides text-based AFTER_STR operations for all instances of the current header type.

Prefixes for HTTP Headers

The following table describes expression prefixes that extract HTTP headers.

Table 1. Prefixes That Extract HTTP Headers

HTTP Header Prefix

Description

HTTP.REQ.HEADER("<header_name>")

Returns the contents of the HTTP header specified by the <header_name> argument. The header name cannot exceed 32 characters.

Note that this prefix returns the value from the Host header by default. To use this value as a host name you need to typecast it as follows:

http.req.header("host").typecast_http_hostname_t

For more information on typecasting, see "Typecasting Data."

HTTP.REQ.FULL_HEADER

Returns the contents of the complete set of HTTP header fields including the request line (for example, "GET /brochures/index.html HTTP/1.1") and the terminating \r\n\r\n sequence.

HTTP.REQ.DATE

Returns the contents of the HTTP Date header. The following date formats are recognized:

RFC822. Sun, 06 Jan 1980 8:49:37 GMT

RFC850. Sunday, 06-Jan-80 9:49:37 GMT

ASCII TIME. Sun Jan 6 08:49:37 1980

To evaluate a Date header as a date object, see "Default Syntax Expressions: Working with Dates, Times, and Numbers."

HTTP.REQ.COOKIE

(Name/Value List) Returns the contents of the HTTP Cookie header.

HTTP.REQ.TXID

Returns the HTTP transaction ID. The value is a function of an internal transaction number, system boot time and system MAC address.

HTTP.RES.HEADER("<header_name>")

Returns the contents of the HTTP header specified by the <header_name> argument. The header name cannot exceed 32 characters.

HTTP.RES.FULL_HEADER

Returns the contents of the complete set of HTTP header fields including the status line (for example, "HTTP/1.1 200 OK") and the terminating \r\n\r\n sequence.

HTTP.RES.SET_COOKIE

or

HTTP.RES.SET_COOKIE2

Returns the HTTP Set-Cookie header object in a response.

HTTP.RES.SET_COOKIE("<name>")

or

HTTP.RES.SET_COOKIE2("<name>")

Returns the cookie of the specified name if it is present. If it is not present, returns a text object of length 0. Returns UNDEF if more than 15 Set-Cookie headers are present and the specified cookie was not found in these headers.

HTTP.RES.SET_COOKIE("<name>").DOMAIN

or

HTTP.RES.SET_COOKIE2("<name>").DOMAIN

Returns the value of the first Domain field in the cookie. For example, if the cookie is Set-Cookie : Customer = "ABC"; DOMAIN=".abc.com"; DOMAIN=.xyz.com, the following expression returns .abc.com:

http.res.set_cookie.cookie("customer").domain

A string of zero length is returned if the Domain field or its value is absent.

HTTP.RES.SET_COOKIE.EXISTS("<name>")

or

HTTP.RES.SET_COOKIE2.EXISTS("<name>")

Returns a Boolean TRUE if a Cookie with the name specified in the <name> argument exists in the Set-Cookie header.

This prefix returns UNDEF if more than 15 Set-Cookie headers are present and the named cookie is not in the first 15 headers.

HTTP.RES.SET_COOKIE.COOKIE("<name>").EXPIRES

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").EXPIRES

Returns the Expires field of the cookie. This is a date string that can be evaluated as a number, as a time object, or as text. If multiple Expires fields are present, the first one is returned. If the Expires field is absent, a text object of length zero is returned.

To evaluate the returned value as a time object, see "Default Syntax Expressions: Working with Dates, Times, and Numbers."

HTTP.RES.SET_COOKIE.COOKIE("<name>").PATH|PATH.GET(n)

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").PATH|PATH.GET(n)

Returns the value of Path field of the cookie as a slash- (“/”) separated list. Multiple instances of a slash are treated as single slash. If multiple Path fields are present, the value of the first instance is returned.

For example, the following is a cookie with two path fields:

Set-Cookie : Customer = "ABC"; PATH="/a//b/c"; PATH= "/x/y/z"

The following expression returns /a//b/c from this cookie:

http.res.set_cookie.cookie("Customer").path

The following expression returns b:

http.res.set_cookie.cookie("Customer").path.get(2)

Quotes are stripped from the returned value. A string of zero length is returned if the Path field or its value is absent.

HTTP.RES.SET_COOKIE.COOKIE("<name>").PATH.IGNORE_EMPTY_ELEMENTS

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").PATH.IGNORE_EMPTY_ELEMENTS

Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89, the element delimiter in the list is , and the list has an empty element following a=10. The element following b=11 is not considered an empty element.

As another example, in the following expression, if a request contains Cust_Header : 123,,24, ,15 the following expression returns a value of 4:

http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count

The following expression returns a value of 5:

http.req.header("Cust_Header").typecast_list_t(',').count

HTTP.RES.SET_COOKIE.COOKIE("<name>").PORT

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").PORT

Returns the value of Port field of the cookie. Operate as a comma-separated list.

For example, the following expression returns 80. 2580 from Set-Cookie : Customer = "ABC"; PATH="/a/b/c"; PORT= "80, 2580":

http.res.set_cookie.cookie("ABC").port

A string of zero length is returned if the Port field or value is absent.

HTTP.RES.SET_COOKIE.COOKIE("<name>").PORT.IGNORE_EMPTY_ELEMENTS

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").PORT.IGNORE_EMPTY_ELEMENTS

Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89, the element delimiter in the list is , and the list has an empty element following a=10. The element following b=11 is not considered an empty element.

As another example, in the following expression, if a request contains Cust_Header : 123,,24, ,15 the following expression returns a value of 4:

http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count

The following expression returns a value of 5:

http.req.header("Cust_Header").typecast_list_t(',').count

HTTP.RES.SET_COOKIE.COOKIE("<name>").VERSION

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>").VERSION

Returns the value of the first Version field in the cookie as a decimal integer.

For example, the following expression returns 1 from the cookie Set-Cookie : Customer = "ABC"; VERSION = "1"; VERSION = "0"

http.res.set_cookie.cookie("CUSTOMER").version

A zero is returned if the Version field or its value is absent or if the value is not a decimal number.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>)

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>)

Returns the nth instance (0-based) of the cookie with the specified name. If the cookie is absent, returns a text object of length 0.

Returns UNDEF if more than 15 Set-Cookie headers are present and the cookie is not found.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).DOMAIN

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).DOMAIN

Returns the value of the Domain field of the first cookie with the specified name. For example, the following expression returns a value of abc.com from the cookie Set-Cookie : Customer = "ABC"; DOMAIN=".abc.com"; DOMAIN=.xyz.com

http.res.set_cookie.cookie("CUSTOMER").domain

A string of zero length is returned if the Domain field or its value is absent.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).EXPIRES

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).EXPIRES

Returns the nth instance (0-based) of the Expires field of the cookie with the specified name as a date string. The value can be operated upon as a time object that supports a number of date formats. If the Expires attribute is absent a string of length zero is returned.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).PATH | PATH.GET(i)

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).PATH | PATH.GET(i)

Returns the value of the Path field of the nth cookie, as a '/' separated list. Multiple /s are treated as a single /.

For example, the following expression returns /a//b/c from the cookie Set-Cookie : Customer = "ABC"; PATH="/a//b/c"; PATH= "/x/y/z"

http.res.set_cookie.cookie("CUSTOMER").path

The following returns b:

http.res.set_cookie.cookie("CUSTOMER").path.get(2)

A string of zero length is returned if the Path field or its value is absent.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).PATH.IGNORE_EMPTY_ELEMENTS

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).PATH.IGNORE_EMPTY_ELEMENTS

Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89, the element delimiter in the list is , and the list has an empty element following a=10. The element following b=11 is not considered an empty element.

As another example, in the following expression, if a request contains Cust_Header : 123,,24, ,15 the following expression returns a value of 4:

http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count

The following expression returns a value of 5:

http.req.header("Cust_Header").typecast_list_t(',').count

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).PORT

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).PORT

Returns the value or values of the Port field of the named cookie as a ',' separated list. For example, the following expression returns 80, 2580 from the cookie Set-Cookie : Customer = "ABC"; PATH="/a/b/c"; PORT= "80, 2580"

http.res.set_cookie.cookie("ABC").port

A string of zero length is returned if the Port field or its value is absent.

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).PORT.IGNORE_EMPTY_ELEMENTS

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).PORT.IGNORE_EMPTY_ELEMENTS

Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89, the element delimiter in the list is , and the list has an empty element following a=10. The element following b=11 is not considered an empty element.

As another example, in the following expression, if a request contains Cust_Header : 123,,24, ,15 the following expression returns a value of 4:

http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count

The following expression returns a value of 5:

http.req.header("Cust_Header").typecast_list_t(',').count

HTTP.RES.SET_COOKIE.COOKIE("<name>", <integer>).VERSION

or

HTTP.RES.SET_COOKIE2.COOKIE("<name>", <integer>).VERSION

Returns the value of Version field of the nth cookie as a decimal integer.

A string of zero length is returned if the Port field or its value is absent.

HTTP.RES.TXID

Returns the HTTP transaction ID. The value is a function of an internal transaction number, system boot time and system MAC address.

Operations for HTTP Headers

The following table describes operations that you can specify with the prefixes for HTTP headers.

Table 2. Operations That Evaluate HTTP Headers
HTTP Header Operation Description

http header .EXISTS

Returns a Boolean TRUE if an instance of the specified header type exists.

Following is an example:

http.req.header("Cache-Control").exists

http header.CONTAINS" http header . CONTAINS("<string>")

Returns a Boolean TRUE if the <string> argument appears in any instance of the header value.

Note: This operation overrides any text-based Contains operations on all instances of the current header type.

Following is an example of request with two headers:

HTTP/1.1 200 OK\r\n

MyHeader: abc\r\n

Content-Length: 200\r\n

MyHeader: def\r\n

\r\n

The following returns a Boolean TRUE:

http.res.header("MyHeader"). contains("de")

The following returns FALSE. Note that the NetScaler does not concatenate the different values.

http.res.header("MyHeader"). contains("bcd")

http header .COUNT

Returns the number of headers in a request or response, to a maximum of 15 headers of the same type. The result is undefined if there are more than 15 instances of the header.

Following is sample data in a request:

HTTP/1.1 200 OK\r\n

MyHeader: abc\r\n

Content-Length: 200\r\n

MyHeader: def\r\n

\r\n

When evaluating the preceding request, the following returns a count of 2:

http.res.header("MyHeader").count

http header.AFTER_STR("<string>")

Extracts the text that follows the first occurrence of the <string> argument. The headers are evaluated from the last instance to the first.

Following is an example of a request:

HTTP/1.1 200 OK\r\n

MyHeader: 111abc\r\n

Content-Length: 200\r\n

MyHeader: 111def\r\n

\r\n

The following extracts the string "def" from the last instance of MyHeader. This is value "111def."

http.res.header("MyHeader").after_str("111")

The following extracts the string "c" from the first instance of MyHeader. This is the value "abc111."

http.res.header("MyHeader").after_str("1ab")

http header.BEFORE_STR("<string>")

Extracts the text that appears prior to the first occurrence of the input <string> argument. The headers are evaluated from the last instance to the first.

Following is an example of a request that contains headers:

HTTP/1.1 200 OK\r\n

MyHeader: abc111\r\n

Content-Length: 200\r\n

MyHeader: def111\r\n

\r\n

The following extracts the string "def" from the last instance of MyHeader. This is the value "def111."

http.res.header("MyHeader").before_str("111")

The following extracts the string "a" from the first instance of MyHeader. This is the value "abc111."

http.res.header("MyHeader").before_str("bc1")

http header.INSTANCE(<instance number>)

An HTTP header can occur multiple times in a request or a response. This operation returns the header that occurs <instance number> of places before the final instance. For example, instance(0) selects the last instance of the current type, instance(1) selects the next-to-last instance, and so on. This prefix cannot be used in bidirectional policies.

The <instance number> argument cannot exceed 14. Following is an example of a request with two headers:

HTTP/1.1 200 OK\r\n

MyHeader: abc\r\n

Content-Length: 200\r\n

MyHeader: def\r\n

\r\n

The following returns a text object that refers to "MyHeader: abc\r\n":

http.res.header("MyHeader").instance(1)

http header.SUBSTR("<string>")

Extracts the text that matches the <string> argument. The headers are evaluated from the last instance to the first. Following is an example of a request with two headers that contain the string “111”:

HTTP/1.1 200 OK\r\n

MyHeader: abc111\r\n

Content-Length: 200\r\n

MyHeader: 111def\r\n

\r\n

The following returns "111" from the last instance of MyHeader. This is the header with the value "111def."

http.res.header("MyHeader").substr("111")

http header.VALUE(<instance number>)

An HTTP header can occur multiple times in a request or a response. VALUE(0) selects the value in the last instance, VALUE(1) selects the value in the next-to-last instance, and so on. The <instance number> argument cannot exceed 14.

Following is an example of a request with two headers:

HTTP/1.1 200 OK\r\n

MyHeader: abc\r\n

Content-Length: 200\r\n

MyHeader: def\r\n

\r\n

The following returns "abc\r\n":

http.res.header("MyHeader").value(1)

Prefixes for Cache-Control Headers

The following prefixes apply specifically to Cache-Control headers.

Table 3. Prefixes That Extract Cache-Control Headers

HTTP Header Prefix

Description

HTTP.REQ.CACHE_CONTROL

Returns a Cache-Control header in an HTTP request.

HTTP.RES.CACHE_CONTROL

Returns a Cache-Control header in an HTTP response.

Operations for Cache-Control Headers

You can apply any of the operations for HTTP headers to Cache-Control headers. For more information, see "Operations for HTTP Headers."

In addition, the following operations identify specific types of Cache-Control headers. See RFC 2616 for information about these header types.

Table 4. Operations That Evaluate Cache-Control Headers

HTTP Header Operation

Description

Cache-Control header.NAME(<integer>)

Returns as a text value the name of the Cache-Control header that corresponds to the nth component in a name-value list, as specified by <integer>.

The index of the name-value component is 0-based. If the <integer> that is specified by the integer argument is greater than the number of components in the list, a zero-length text object is returned.

Following is an example:

http.req.cache_control.name(3).contains("some_text")

Cache-Control header.IS_INVALID

Returns a Boolean TRUE if the Cache-Control header is not present in the request or response.

Following is an example:

http.req.cache_control.is_invalid

Cache-Control header.IS_PRIVATE

Returns a Boolean TRUE if the Cache-Control header has the value Private.

Following is an example:

http.req.cache_control.is_private

Cache-Control header.IS_PUBLIC

Returns a Boolean TRUE if the Cache-Control header has the value Private.

Following is an example:

http.req.cache_control.is_public

Cache-Control header.IS_NO_STORE

Returns a Boolean TRUE if the Cache-Control header has the value No-Store.

Following is an example:

http.req.cache_control.is_no_store

Cache-Control header.IS_NO_CACHE

Returns a Boolean TRUE if the Cache-Control header has the value No-Cache.

Following is an example:

http.req.cache_control.is_no_cache

Cache-Control header.IS_MAX_AGE

Returns a Boolean TRUE if the Cache-Control header has the value Max-Age.

Following is an example:

http.req.cache_control.is_max_age

Cache-Control header.IS_MIN_FRESH

Returns a Boolean TRUE if the Cache-Control header has the value Min-Fresh.

Following is an example:

http.req.cache_control.is_min_fresh

Cache-Control header.IS_MAX_STALE

Returns a Boolean TRUE if the Cache-Control header has the value Max-Stale.

Following is an example:

http.req.cache_control.is_max_stale

Cache-Control header.IS_MUST_REVALIDATE

Returns a Boolean TRUE if the Cache-Control header has the value Must-Revalidate.

Following is an example:

http.req.cache_control.is_must_revalidate

Cache-Control header.IS_NO_TRANSFORM

Returns a Boolean TRUE if the Cache-Control header has the value No-Transform.

Following is an example:

http.req.cache_control.is_no_transform

Cache-Control header.IS_ONLY_IF_CACHED

Returns a Boolean TRUE if the Cache-Control header has the value Only-If-Cached.

Following is an example:

http.req.cache_control.is_only_if_cached

Cache-Control header.IS_PROXY_REVALIDATE

Returns a Boolean TRUE if the Cache-Control header has the value Proxy-Revalidate.

Following is an example:

http.req.cache_control.is_proxy_revalidate

Cache-Control header.IS_S_MAXAGE

Returns a Boolean TRUE if the Cache-Control header has the value S-Maxage.

Following is an example:

http.req.cache_control.is_s_maxage

Cache-Control header.IS_UNKNOWN

Returns a Boolean TRUE if the Cache-Control header is of an unknown type.

Following is an example:

http.req.cache_control.is_unknown

Cache-Control header.MAX_AGE

Returns the value of the Cache-Control header Max-Age. If this header is absent or invalid, 0 is returned.

Following is an example:

http.req.cache_control.max_age.le(3)

Cache-Control header.MAX_STALE

Returns the value of the Cache-Control header Max-Stale. If this header is absent or invalid, 0 is returned.

Following is an example:

http.req.cache_control.max_stale.le(3)

Cache-Control header.MIN_FRESH

Returns the value of the Cache-Control header Min-Fresh. If this header is absent or invalid, 0 is returned.

Following is an example:

http.req.cache_control.min_fresh.le(3)

Cache-Control header.S_MAXAGE

Returns the value of the Cache-Control header S-Maxage. If this header is absent or invalid, 0 is returned.

Following is an example:

http.req.cache_control.s_maxage.eq(2)