Utility Macros

In addition to the core and HTTP macros, ngrok provides a set of utility macros within the Traffic Policy engine. These macros are typically available across all phases, unless otherwise specified.

Name	Return Type	Description
`b64.decode(string)`	`string`	Decodes the passed Base64 string into a string.
`b64.encode(string)`	`string`	Encodes the passed string into a Base64 string.
`inCidrRange(ip,cidr)`	`bool`	Returns `true` or `false` if the provided IP address falls within the provided CIDR range. Returns `false` if the provided CIDR range is invalid.
`inCidrRanges(ip,cidrs)`	`bool`	Returns `true` or `false` if the provided IP address falls within any of the provided CIDR ranges. Ignores any provided CIDR ranges that are invalid.
`json.decode(string)`	`list \| map`	Decodes the passed JSON string into a list or map.
`json.encode(list \| map)`	`string`	Encodes the passed map or list into a JSON string.
`list.encodeJson()`	`string`	Encodes the list as a JSON string.
`object.encodeJson()`	`string`	Encodes the object or array as a JSON string.
`object.encodeQueryString()`	`string`	Encodes the object as a URL query string.
`queryString.decode(string)`	`map`	Decodes the supplied query string into a map.
`queryString.encode(map)`	`string`	Encodes the passed map into a query string.
`rand.double()`	`double`	Returns a random `double` between `0` and `1`.
`rand.int(min,max)`	`int`	Returns a random `int` between the provided `min` and `max` values. Only supports positive integers and `min` must be larger than the provided `max`. By default, `min` is `0` and `max` is `1`.
`string.decodeBase64()`	`string`	Decodes the Base64 string and returns it as a string.
`string.decodeJson()`	`map` \| `list`	Decodes the JSON string and returns it as a map or list.
`string.decodeQueryString()`	`map`	Decodes the string as a URL query and returns a map with the query parameters.
`string.encodeBase64()`	`string`	Encodes the object or array as a Base64 string.
`string.escapeUrl()`	`string`	Returns the string with percent encoding applied.
`string.isJson()`	`bool`	Checks if the string is valid JSON and returns true if so, otherwise false.
`string.isQueryString()`	`bool`	Checks if the string is valid Query String and returns true if so, otherwise false.
`string.isURL()`	`bool`	Checks if the string is a valid URL and returns true if so, otherwise false.
`string.parseUrl()`	`URL`	Returns the provided URL string as a net URL map structure.
`string.unescapeUrl()`	`string`	Decodes a percent-encoded string back to its original form.
`url.escape(string)`	`string`	Returns the string with percent encoding applied.
`url.parse(string)`	`URL`	Returns the provided URL string as a net URL map structure.
`url.unescape(string)`	`string`	Decodes a percent-encoded string back to its original form.

`b64.decode(string) → string`

Decodes the passed base64 string into a string.

Example

b64.decode('c29tZTp0aGluZw==')  // some:thing

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - b64.decode(getReqHeader('Signature')[0]) == 'this is a valid signature'

// snippet
{
  "expressions": [
    "b64.decode(getReqHeader('Signature')[0]) == 'this is a valid signature'"
  ]
}

`b64.encode(string) → string`

Encodes the passed string into a Base64 string.

Example

b64.encode('some:thing')  // c29tZTp0aGluZw==

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - "'basic '+b64.encode('john:supersecretpass') ==
    getReqHeader('Authorization')[0]"

// snippet
{
  "expressions": [
    "'basic '+b64.encode('john:supersecretpass') == getReqHeader('Authorization')[0]"
  ]
}

`inCidrRange(ip,cidr) → bool`

Evaluates whether the given IP address falls within the specified CIDR range.

Returns true if the IP is within the range, and false if it is outside the range or if the provided CIDR is invalid.

Example

inCidrRange('192.168.1.100', '192.168.1.0/24')  // true

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - inCidrRange(conn.client_ip, '66.249.66.1/24')

// snippet
{
  "expressions": [
    "inCidrRange(conn.client_ip, '66.249.66.1/24')"
  ]
}

`inCidrRanges(ip,cidrs) → bool`

Checks if the given IP address falls within any of the specified CIDR ranges.

Returns true if the IP is within at least one valid CIDR range, and false if it is not within any valid range. Invalid CIDR ranges are ignored.

Example

inCidrRanges('192.168.1.100', ['192.168.1.0/24', '10.0.0.0/8']) // true

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - inCidrRanges(conn.client_ip, ['66.249.66.1/24', '2001:4860::/32'])

// snippet
{
  "expressions": [
    "inCidrRanges(conn.client_ip, ['66.249.66.1/24', '2001:4860::/32'])"
  ]
}

`json.decode(string) → list | map`

Decodes the passed JSON string into a list or map.

Example

json.decode('{"a":"b"}')  // map[a:b]
json.decode('["a","b","c"]')  // string["a","b","c"]

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - json.decode(getReqHeader('x-json-array')[0])[0] == "first entry"

// snippet
{
  "expressions": [
    "json.decode(getReqHeader('x-json-array')[0])[0] == \"first entry\""
  ]
}

`json.encode(list | map) → string`

Encodes the passed string into a JSON string.

Example

json.encode({a:b})  // {"a":"b"}
json.encode(["a","b","c"])  // ["a","b","c"]

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - json.encode(req.content_type.parameters) == '{"charset":"UTF-8"}'

// snippet
{
  "expressions": [
    "json.encode(req.content_type.parameters) == '{\"charset\":\"UTF-8\"}'"
  ]
}

`list.encodeJson() → string`

Encodes the list as a JSON string.

Example

["a","b","c"].encodeJson()  // "[\"a\",\"b\",\"c\"]"

`object.encodeJson() → string`

Encodes the object as a JSON string.

Example

{a:"b",c:"d"}.encodeJson()  // "{\"a\":\"b\",\"c\":\"d\"}"

`object.encodeQueryString() → string`

Encodes the object as a URL query string.

Example

{a:"b",c:"d"}.encodeQueryString()  // "a=b&c=d"

`queryString.decode(string) → map`

Encodes the passed map into a query string.

Example

queryString.encode("a=b&c=d")  // {a:b,c:d}

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - queryString.decode(req.url.query)["q"] == "hello"

// snippet
{
  "expressions": [
    "queryString.decode(req.url.query)[\"q\"] == \"hello\""
  ]
}

`queryString.encode(map) → string`

Encodes the passed map into a query string.

Example

queryString.encode({a:b,c:d})  // a=b&c=d

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - queryString.encode({"q":"policy"}) == req.url.query

// snippet
{
  "expressions": [
    "queryString.encode({\"q\":\"policy\"}) == req.url.query"
  ]
}

`rand.double() → double`

Returns a random double between 0 and 1.

Example

rand.double() >= 0.5

Example (in expression)

YAML
JSON

# snippet
---
expressions:
  - rand.double() >= 0.5

// snippet
{
  "expressions": [
    "rand.double() >= 0.5"
  ]
}

`rand.int(min,max) → int`

Returns a random int between the provided min and max values. Only supports positive integers and min must be larger than the provided max. By default, min is 0 and max is 1.

Example

rand.int() == 1
rand.int(0, 10) >= 5

Examples (in expression)

The following is an example of using rand.int with the default values:

YAML
JSON

# snippet
---
expressions:
  - rand.int() == 1

// snippet
{
  "expressions": [
    "rand.int() == 1"
  ]
}

The following is an example of using rand.int with custom values:

YAML
JSON

# snippet
---
expressions:
  - rand.int(0, 10) >= 5

// snippet
{
  "expressions": [
    "rand.int(0, 10) >= 5"
  ]
}

`string.decodeBase64() → string`

Decodes the Base64 string and returns it as a string.

Example

"c29tZTp0aGluZw==".decodeBase64()  // "some:thing"

`string.decodeJson() → map \| list`

Decodes the JSON string and returns it as a map or list.

Example

"{\"a\":\"b\"}".decodeJson()  // map{a:b}

`string.decodeQueryString() → map`

Decodes the string as a URL query and returns a map with the query parameters.

Example

"a=b&c=d".decodeQueryString()  // map{a:b,c:d}

`string.encodeBase64() → string`

Encodes the string and returns it as a base64 encoded string.

Example

"some:thing".encodeBase64()  // "c29tZTp0aGluZw=="

`string.escapeUrl() → string`

Returns the string with percent encoding applied.

Example

"i;md/r/$y".escapeUrl()
// returns i%3Bmd%2Fr%2F%24y

`string.isJson() → bool`

Checks if the string is valid JSON and returns true if so, otherwise false.

Example

'{"a":"b","c":"d"}'.isJson() // true
'not json'.isJson() // false

`string.isQueryString() → bool`

Checks if the string is valid Query String and returns true if so, otherwise false.

Example

'a=b&c=d'.isQueryString() // true
'not a query string'.isQueryString() // false

`string.isURL() → bool`

Checks if the string is a valid URL and returns true if so, otherwise false.

Example

'https://ngrok.com'.isURL() // true
'not a url'.isURL() // false

`url.escape(string) → string`

Returns the string with percent encoding applied.

Example

url.escape("i;md/r/$y")
// returns i%3Bmd%2Fr%2F%24y

Examples (in expression)

The following is an example of using url.escape:

YAML
JSON

# snippet
---
expressions:
  - url.escape(req.raw) == '%2Ffoo'

// snippet
{
  "expressions": [
    "url.escape(req.raw) == '%2Ffoo'"
  ]
}

`string.parseUrl() → URL`

Returns the provided string as a net URL map structure.

Example

"https://ngrok.com".parseUrl()
// returns {host:ngrok.com, scheme:https}

`string.unescapeUrl() → string`

Decodes a percent-encoded string back to its original form.

Example

"i%3Bmd%2Fr%2F%24y".unescapeUrl()
// returns i;md/r/$y

`url.parse(string) → URL`

Returns the provided URL string as a net URL map structure.

Example

url.parse("https://ngrok.com")
// returns {host:ngrok.com, scheme:https}

Examples (in expression)

The following is an example of using url.parse:

YAML
JSON

# snippet
---
expressions:
  - url.parse(req.url).host == 'ngrok.com'

// snippet
{
  "expressions": [
    "url.parse(req.url).host == 'ngrok.com'"
  ]
}

`url.unescape(string) → string`

Decodes a percent-encoded string back to its original form.

Example

url.unescape("i%3Bmd%2Fr%2F%24y")
// returns i;md/r/$y

Examples (in expression)

The following is an example of using url.unescape:

YAML
JSON

# snippet
---
expressions:
  - url.unescape('%2Ffoo') == '/foo'

// snippet
{
  "expressions": [
    "url.unescape('%2Ffoo') == '/foo'"
  ]
}

b64.decode(string) → string​

Example​

Example (in expression)​

b64.encode(string) → string​

Example​

Example (in expression)​

inCidrRange(ip,cidr) → bool​

Example​

Example (in expression)​

inCidrRanges(ip,cidrs) → bool​

Example​

Example (in expression)​

json.decode(string) → list | map​

Example​

Example (in expression)​

json.encode(list | map) → string​

Example​

Example (in expression)​

list.encodeJson() → string​

Example​

object.encodeJson() → string​

Example​

object.encodeQueryString() → string​

Example​

queryString.decode(string) → map​

Example​

Example (in expression)​

queryString.encode(map) → string​

Example​

Example (in expression)​

rand.double() → double​

Example​

Example (in expression)​

rand.int(min,max) → int​

Example​

Examples (in expression)​

string.decodeBase64() → string​

Example​

string.decodeJson() → map \| list​

Example​

string.decodeQueryString() → map​

Example​

string.encodeBase64() → string​

Example​

string.escapeUrl() → string​

Example​

string.isJson() → bool​

Example​

string.isQueryString() → bool​

Example​

string.isURL() → bool​

Example​

url.escape(string) → string​

Example​

Examples (in expression)​

string.parseUrl() → URL​

Example​

string.unescapeUrl() → string​

Example​

url.parse(string) → URL​

Example​

Examples (in expression)​

url.unescape(string) → string​

Example​

Examples (in expression)​

`b64.decode(string) → string`

Example

Example (in expression)

`b64.encode(string) → string`

Example

Example (in expression)

`inCidrRange(ip,cidr) → bool`

Example

Example (in expression)

`inCidrRanges(ip,cidrs) → bool`

Example

Example (in expression)

`json.decode(string) → list | map`

Example

Example (in expression)

`json.encode(list | map) → string`

Example

Example (in expression)

`list.encodeJson() → string`

Example

`object.encodeJson() → string`

Example

`object.encodeQueryString() → string`

Example

`queryString.decode(string) → map`

Example

Example (in expression)

`queryString.encode(map) → string`

Example

Example (in expression)

`rand.double() → double`

Example

Example (in expression)

`rand.int(min,max) → int`

Example

Examples (in expression)

`string.decodeBase64() → string`

Example

`string.decodeJson() → map \| list`

Example

`string.decodeQueryString() → map`

Example

`string.encodeBase64() → string`

Example

`string.escapeUrl() → string`

Example

`string.isJson() → bool`

Example

`string.isQueryString() → bool`

Example

`string.isURL() → bool`

Example

`url.escape(string) → string`

Example

Examples (in expression)

`string.parseUrl() → URL`

Example

`string.unescapeUrl() → string`

Example

`url.parse(string) → URL`

Example

Examples (in expression)

`url.unescape(string) → string`

Example

Examples (in expression)