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.
basic_auth.encode(username, password)	string	Encodes the passed username and password strings into a Base64 string for use in HTTP Basic Authentication.
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

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

b64.encode(string) → string

Encodes the passed string into a Base64 string.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

basic_auth.encode(username, password) → string

Encodes the passed username and password strings into a Base64 string for use in HTTP Basic Authentication. Appends the prefix Basic to the encoded string.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

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

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

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

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

json.decode(string) → list | map

Decodes the passed JSON string into a list or map.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

json.encode(list | map) → string

Encodes the passed string into a JSON string.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

list.encodeJson() → string

Encodes the list as a JSON string.

Example

Loading…

object.encodeJson() → string

Encodes the object as a JSON string.

Example

Loading…

object.encodeQueryString() → string

Encodes the object as a URL query string.

Example

Loading…

queryString.decode(string) → map

Encodes the passed map into a query string.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

queryString.encode(map) → string

Encodes the passed map into a query string.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

rand.double() → double

Returns a random double between 0 and 1.

Example

Loading…

Example (in expression)

YAML

Loading…

JSON

Loading…

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

Loading…

Examples (in expression)

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

YAML

Loading…

JSON

Loading…

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

YAML

Loading…

JSON

Loading…

string.decodeBase64() → string

Decodes the Base64 string and returns it as a string.

Example

Loading…

string.decodeJson() → map \| list

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

Example

Loading…

string.decodeQueryString() → map

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

Example

Loading…

string.encodeBase64() → string

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

Example

Loading…

string.escapeUrl() → string

Returns the string with percent encoding applied.

Example

Loading…

string.isJson() → bool

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

Example

Loading…

string.isQueryString() → bool

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

Example

Loading…

string.isURL() → bool

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

Example

Loading…

url.escape(string) → string

Returns the string with percent encoding applied.

Example

Loading…

Examples (in expression)

The following is an example of using url.escape:

YAML

Loading…

JSON

Loading…

string.parseUrl() → URL

Returns the provided string as a net URL map structure.

Example

Loading…

string.unescapeUrl() → string

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

Example

Loading…

url.parse(string) → URL

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

Example

Loading…

Examples (in expression)

The following is an example of using url.parse:

YAML

Loading…

JSON

Loading…

url.unescape(string) → string

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

Example

Loading…

Examples (in expression)

The following is an example of using url.unescape:

YAML

Loading…

JSON

Loading…