Skip to main content

Macros

ngrok offers a variety of macros that can be used within the engine to simplify traffic management and dynamic configuration. These macros help you streamline traffic handling by referencing common values and conditions, making it easier to manage complex logic in your traffic policies.

You can use these macros in combination with expressions and actions to create dynamic, condition-based traffic flows.

Base64​

base64.decode() -> bytes​

Decodes base64-encoded string to bytes.

This function will return an error if the string input is not base64-encoded.

Signatures​

  • base64.decode(<string>) -> <bytes>

Example​

Loading…

base64.encode() -> string​

Encodes bytes to a base64-encoded string.

Signatures​

  • base64.encode(<bytes>) -> <string>

Example​

Loading…

Basic Auth​

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)​

Loading…

Bytes​

bytes.size() -> int​

Determines the number of bytes in a sequence.

Signatures​

  • bytes.size() -> int
  • size(bytes) -> int

Example​

Loading…

HTTP Requests​

Available in on_http_request and on_http_response phases.

hasReqHeader(string) -> bool​

Returns true or false if the provided header key is present on the request. Header keys must be written in canonical format.

Example​
Loading…
Example (Expression)​
Loading…

getReqHeader(string) -> list​

Returns a list of header values for the provided key on the request. Header keys must be written in canonical format. Defaults to an empty list if the header is not present.

Example​
Loading…
Example (Expression)​
Loading…

hasQueryParam(string) -> bool​

Returns true or false if the specified query parameter key is part of the request URL.

Example​
Loading…
Example (Expression)​
Loading…

getQueryParam(string) -> list​

Returns a list of the query parameter values from the request URL for the specified key. Defaults to an empty list if the query param is not present.

Example​
Loading…
Example (Expression)​
Loading…

hasReqCookie(string) -> bool​

Returns true or false if a cookie exists on the request with the specified name.

Example​
Loading…
Example (Expression)​
Loading…

getReqCookie(string) -> cookie​

Returns the cookie struct for the specified cookie name, if it exists on the request. If there are multiple cookies of the same name, the first from the ordering specified in the Cookie header will be returned.

Example​
Loading…
Example (Expression)​
Loading…

HTTP Responses​

Available in on_http_response phase only.

hasResHeader(string) -> bool​

Returns true or false if the provided header key is present on the response. Header keys must be written in canonical format. Defaults to empty list if the header is not present.

Example​
Loading…
Example (Expression)​
Loading…

getResHeader(string) -> list​

Returns a list of header values for the provided key on the response. Header keys must be written in canonical format.

Example​
Loading…
Example (Expression)​
Loading…

hasResCookie(string) -> bool​

Returns true or false if a cookie exists on the response with the specified name.

Example​
Loading…
Example (Expression)​
Loading…

getResCookie(string) -> cookie​

Returns the cookie struct for the specified cookie name, if it exists on the response. If there are multiple cookies of the same name, the cookie with the longest path will be returned.

Example​
Loading…
Example (Expression)​
Loading…

JSON​

json.decode(string) -> list | map​

Decodes the passed JSON string into a list or map.

Example​

Loading…

Example (in expression)​

Loading…

json.encode(list | map) -> string​

Encodes the passed string into a JSON string.

Example​

Loading…

Example (in expression)​

Loading…

Lists​

list.all(x,p) -> bool​

Checks if a predicate p holds for all elements of a list.

Where x is a variable name to be used in p as a reference to the element.

Example​
Loading…

list.exists(x,p) -> bool​

Checks if a predicate p holds for at least one element of a list.

Where x is a variable name to be used in p as a reference to the element.

Example​
Loading…

list.exists_one(x,p) -> bool​

Checks if a predicate p holds for exactly one element of a list.

Where x is a variable name to be used in p as a reference to the element.

Example​
Loading…

list.filter(x,p) -> list​

Filters a list to include only elements that satisfy a condition.

Where x is a variable name to be used in p as a reference to the element.

Example​
Loading…

list.join() -> string​

Returns a new string with the elements of the list concatenated. Optionally, a separator can be specified to insert between elements.

Signatures​
  • <list<string>>.join(<string?>) -> <string>
Example​
Loading…

list.map(x,t) -> list​

Transforms each element in a list by applying the function defined in the expression t.

Where x is a variable name to be used in t as a reference to the element.

Example​
Loading…

list.map(x,p,t) -> list​

Transforms each element in a list by applying the function defined in the expression t to elements that satisfy predicate p.

Where x is a variable name to be used in p as a reference to the element.

Example​
Loading…

list.size() -> int​

Determines the number of elements in a list.

Signatures​
  • list.size() -> int
  • size(list) -> int
Example​
Loading…

list.slice() -> list​

Returns a new sub-list using the indexes provided.

Signatures​
  • <list>.slice(<int>, <int>) -> <list>
Example​
Loading…

list.encodeJson() -> string​

Encodes the list as a JSON string.

Example​
Loading…

Maps​

map.all(x,p) -> bool​

Checks if a predicate p holds for all elements of a map.

Where x is a variable name to be used in p as a reference to the key.

Example​
Loading…

map.exists(x,p) -> bool​

Checks if a predicate p holds for at least one element of a map.

Where x is a variable name to be used in p as a reference to the key.

Example​
Loading…

map.exists_one(x,p) -> bool​

Checks if a predicate p holds for exactly one element of a map.

Where x is a variable name to be used in p as a reference to the key.

Example​
Loading…

map.filter(x,p) -> list​

Filters a map to include only keys that satisfy a condition.

Where x is a variable name to be used in p as a reference to the key.

Example​
Loading…

map.map(x,t) -> list​

Transforms each key in a map by applying the function defined in the expression t.

Where x is a variable name to be used in t as a reference to the key.

Example​
Loading…

map.map(x,p,t) -> list​

Transforms each key in a map by applying the function defined in the expression t to keys that satisfy predicate p.

Where x is a variable name to be used in p as a reference to the key.

Example​
Loading…

map.size() -> int​

Determines the number of entries in a map.

Signatures​
  • map.size() -> int
  • size(map) -> int
Example​
Loading…

map.encodeJson() -> string​

Encodes the map as a JSON string.

Example​
Loading…

map.encodeQueryString() -> string​

Encodes the map as a URL query string.

Example​
Loading…

Query String​

queryString.decode(string) -> map​

Decodes the supplied query string into a map.

Example​

Loading…

Example (in expression)​

Loading…

queryString.encode(map) -> string​

Encodes the passed map into a query string.

Example​

Loading…

Example (in expression)​

Loading…

Random​

rand.double() -> double​

Returns a random double between 0 and 1.

Example​

Loading…

Example (in expression)​

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:

Loading…

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

Loading…

Secrets​

secret(string, string) -> string​

Early Access

This feature is currently in Early Access. Log into the ngrok dashboard to request access.

Takes the vault name as the first argument and the secret name as the second argument. Returns the secret value.

Security Macros allow you to access sensitive information directly in your Traffic Policies. Your ngrok account has a Vault that can store Secrets. Any secrets that you add to your vault will be available across your account on all traffic policies. Updates to these secrets will be reflected across all traffic policies automatically.

How secrets are secured​
  • Secrets are protected at rest using industry standard AES-256 encryption
  • ngrok's REST API does not return secrets as part of any of its response payloads
  • REST API traffic is encrypted in-transit using HTTP/S and TLS 1.2+
Example​
Loading…

String​

string.matches() -> bool​

Tests whether a string matches a given RE2 regular expression. This function provides a simple way to validate patterns in strings.

Signatures​

  • matches(string, regex) -> bool
  • string.matches(regex) -> bool

Example​

Loading…

string.startsWith() -> bool​

Tests whether a string starts with the specified prefix.

Signatures​

  • string.startsWith(prefix) -> bool

Example​

Loading…

string.endsWith() -> bool​

Tests whether a string ends with the specified suffix.

Signatures​

  • string.endsWith(suffix) -> bool

Example​

Loading…

string.contains() -> bool​

Tests whether a string contains the specified substring.

Signatures​

  • string.contains(substring) -> bool

Example​

Loading…

string.size() -> int​

Determines the length of a string in terms of the number of Unicode codepoints.

Signatures​

  • string.size() -> int
  • size(string) -> int

Example​

Loading…

string.indexOf() -> int​

Returns the index of the first occurrence of a substring within the string. The function also accepts an optional position argument to start the search.

Signatures​

  • <string>.indexOf(<string>, <int?>) -> <int>

Example​

Loading…

string.split() -> list​

Splits a string into a list of substrings using a specified separator. Optionally, a maximum number of splits can be defined.

Signatures​

  • <string>.split(<string?>, <int?>) -> list<string>

Example​

Loading…

string.replace() -> string​

Replaces occurrences of a substring with another string. Optionally, limits the number of replacements.

Signatures​

  • <string>.replace(<string>, <string>, <int?>) -> <string>

Example​

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.isPrivateIp() -> bool​

Checks if the string is a valid private IP address falling in the range of

Loading…

as per RFC 1918. It 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…

string.lower() -> string​

Lowercases a UTF-8 string.

Example​

Loading…

string.upper() -> string​

Uppercases a UTF-8 string.

Example​

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…

Timestamps​

ts.getDate() -> int​

Extracts the day of the month (1-based indexing) from a timestamp.

Signatures​

  • Timestamp.getDate() -> int (in UTC)
  • Timestamp.getDate(string) -> int (with timezone)

Example​

Loading…

ts.getDayOfMonth() -> int​

Returns the day of the month from a timestamp, using zero-based indexing.

Signatures​

  • Timestamp.getDayOfMonth() -> int (in UTC)
  • Timestamp.getDayOfMonth(string) -> int (with timezone)

Example​

Loading…

ts.getDayOfWeek() -> int​

Returns the day of the week from a timestamp, using zero-based indexing (0 for Sunday).

Signatures​

  • Timestamp.getDayOfWeek() -> int (in UTC)
  • Timestamp.getDayOfWeek(string) -> int (with timezone)

Example​

Loading…

ts.getDayOfYear() -> int​

Returns the day of the year from a timestamp, using zero-based indexing.

Signatures​

  • Timestamp.getDayOfYear() -> int (in UTC)
  • Timestamp.getDayOfYear(string) -> int (with timezone)

Example​

Loading…

ts.getFullYear() -> int​

Returns the year from a timestamp.

Signatures​

  • Timestamp.getFullYear() -> int (in UTC)
  • Timestamp.getFullYear(string) -> int (with timezone)

Example​

Loading…

ts.getHours() -> int​

Returns the hour from a timestamp or converts a duration to hours.

Signatures​

  • Timestamp.getHours() -> int (in UTC)
  • Timestamp.getHours(string) -> int (with timezone)
  • Duration.getHours() -> int (convert the duration to hours)

Example​

Loading…

ts.getMilliseconds() -> int​

Returns the milliseconds from a timestamp or the milliseconds portion of a duration.

Signatures​

  • Timestamp.getMilliseconds() -> int (in UTC)
  • Timestamp.getMilliseconds(string) -> int (with timezone)
  • Duration.getMilliseconds() -> int (extracts the milliseconds portion)

Example​

Loading…

ts.getMinutes() -> int​

Returns the minutes from a timestamp or converts a duration to minutes.

Signatures​

  • Timestamp.getMinutes() -> int (in UTC)
  • Timestamp.getMinutes(string) -> int (with timezone)
  • Duration.getMinutes() -> int (convert the duration to minutes)

Example​

Loading…

ts.getMonth() -> int​

Returns the month from a timestamp, using zero-based indexing (0 for January).

Signatures​

  • Timestamp.getMonth() -> int (in UTC)
  • Timestamp.getMonth(string) -> int (with timezone)

Example​

Loading…

ts.getSeconds() -> int​

Returns the seconds from a timestamp or converts a duration to seconds.

Signatures​

  • Timestamp.getSeconds() -> int (in UTC)
  • Timestamp.getSeconds(string) -> int (with timezone)
  • Duration.getSeconds() -> int (convert the duration to seconds)

Example​

Loading…

URL​

url.escape(string) -> string​

Returns the string with percent encoding applied.

Example​

Loading…

Example (in expression)​

Loading…

url.parse(string) -> URL​

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

Example​

Loading…

Example (in expression)​

Loading…

url.unescape(string) -> string​

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

Example​

Loading…

Example (in expression)​

Loading…

Utility​

has(field) -> bool​

Checks whether a field or property exists in a list or map.

Example​
Loading…

inCidrRange(ip,cidr) -> bool​

Evaluates whether the given IP address falls within the specified 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)​
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)​
Loading…