Rules Engine for Applications

Rules Engine for Applications holds the conditional logic of an application. Each rule tests a request against its criteria, the if of the rule, and runs its behaviors, the then, only when the request matches. Every rule belongs to one phase: it acts on the request the user sends, or on the response the user receives. Some variables and behaviors need a Product enabled on the application, and each table on this page names it. For the order in which an application runs its rules and behaviors, refer to How Applications works.

An application rule decides how the application handles a request that reached it, such as the connector or the cache setting the request uses. When the workload’s deployment names a firewall, the firewall decides earlier whether the request reaches the application at all. For its rules, refer to Rules Engine for Firewall.

Rule fields

An application keeps its rules in the Rules Engine tab of Azion Console, where + Rule creates one. A new application has no rules. In the API, a rule is a JSON object: a request sets five of its fields, and the platform sets and returns the other five.

The platform assigns order as rules are created: the first rule of a phase carries 0, and the next one carries 1. The Console rule list lets you move a rule, and a position past the end of the list places the rule last. The API reorders a phase with one call, which the API section lists.

Phases

A rule runs in the phase chosen in the Phase section when the rule is created, and that choice is final. To run the same logic in the other phase, create a new rule there. The Console groups the rule list by phase, and the API keeps each phase in its own collection.

Each phase offers its own set of variables and behaviors. A value that exists only once the origin answers, such as ${status}, is readable only in the Response Phase. The Phases column of the variable table and the two API columns of the behavior table say which phase accepts each one.

Criteria

Criteria decide which requests a rule acts on. A criterion names a variable, an operator, and, for most operators, an argument to compare the variable with. In the API, a criterion is an object with four keys: variable, operator, conditional, and argument.

This criterion matches a request from a desktop browser, with a regular expression on the User-Agent header:

Variables

A variable holds one value of the request or of the response, and the Phases column names where a criterion can read it. ${request_uri} and ${device_group} require Application Accelerator on the application. The API refuses a rule with ${request_uri} on an application without it, with 400 and code 25047. ${uri} needs no Product, so it is the URI variable for an application without Application Accelerator.

Six entries are families: replace name with the argument, cookie, or header to read.

Mutual Transport Layer Security (mTLS) variables

These variables hold the client certificate that a request presents over mTLS, where the client also authenticates with a certificate. A criterion reads them only in the Request Phase. For how a workload asks for and validates client certificates, refer to mTLS.

Most mTLS services expect to receive the client certificate itself. A Request Phase rule can send ${ssl_client_escaped_cert} to the origin in the X-Forward-Client-Cert (XFCC) header with Add Request Header, and the origin then reads the certificate data from that header.

Variables in behavior arguments

A behavior that takes an argument can read the variables of its phase. For example, a rule can write the device group or the geolocation of a request into a cookie or a header.

This Response Phase rule sets a cookie that records the host of the request:

When the rule matches, the response carries Set-Cookie: cookie-host-value=host.com.

Two more variables act as functions: each takes an argument, and both work only inside a behavior argument.

Operators

A criterion compares its variable with its argument through an operator, and the API sends the operator as one of these values in operator. The operators the Console offers can vary with the variable the criterion uses.

Conditionals

Criteria combine inside groups, and a rule holds 1 to 5 groups of 1 to 10 criteria each. In a group, the first criterion carries the conditional if, and each later criterion carries and or or. The Console joins criteria with And and Or.

Inside a group, and takes precedence over or. To set the precedence yourself, split the conditions into groups: the groups of a rule are joined by and, so a request matches the rule only when it matches every group. For example, a rule that needs A or B, and also C, puts A or B in one group and C in a second one.

In the API, criteria is a list of groups, and each group is a list of criterion objects, as in [[{ … }]].

Behaviors

Behaviors are what a rule does to a request, or to a response, that matches its criteria, and a rule carries from 1 to 10 of them. The Console labels the first behavior row Then and each later row And, and + Add Behavior adds a row. Some behaviors cannot be added together, or only under some conditions, and the Console refuses those combinations.

In the API, each behavior is an object with a type. A behavior that takes an argument carries it in attributes.value, and Capture Match Groups carries three named attributes instead. The Console refuses some arguments that contain a space, with Argument cannot contain spaces, use %20 instead.

The two API columns give the type each phase accepts, and Requires names the Product the application must have enabled. When that Product is off, the Console adds - Required Application Accelerator, - Required Image Processor, or - Required Function to the label. A new application has Cache and Functions on, and Application Accelerator and Image Processor off.

Add Cookie

Add Cookie adds a cookie in the Set-Cookie header, in either phase, and requires Application Accelerator on the application. In a Response Phase rule, the behavior is Add Response Cookie. The argument takes the form cookie-name=cookie-value, and the value can be a variable, as in cookie-name=${arg_cookie}. The Console checks the argument and shows This cookie is not valid when it cannot read one.

In the Response Phase, the argument can carry Set-Cookie attributes after the value, each one after a semicolon (;):

• Expires=date, in the format EEE, d MMM yyyy HH:mm:ss Z
• Domain=domain-value
• Path=path-value
• Max-age=number, a TTL in seconds that takes precedence over Expires
• SameSite=value; Secure
• HttpOnly

A cookie with several attributes chains them, as in cookie-name=cookie-value; Domain=domain-value; Path=path-value; SameSite=value. An attribute value can be a variable too, as in Path=${uri}; Domain=${host}. In the API, the Request Phase type is add_request_cookie and the Response Phase type is set_cookie, with the argument in attributes.value.

Add Request Header

Add Request Header adds a header to the request that Azion sends to the origin, in the Request Phase, and requires no Product. A Response Phase rule adds the header to the response sent to the user instead, with the API type add_response_header. The argument takes the form Field: value, and the Console refuses any other shape with Header must follow the header-name: value format.

The header name takes only letters (a-z, A-Z), numbers (0-9), hyphens, and underscores, and any other character makes the header invalid. The header value takes letters, numbers, and these characters:

The argument holds up to 1,600 characters, and a longer one fails with Argument too long. This argument is a valid header:

In the API, the behavior is add_request_header, with the header in attributes.value, such as "Accept: image/webp". A behavior of type add_header is refused with 400 and code 10039. The headers Host, Connection, Range, X-Forward-For, and Cdn-Loop cannot be overwritten or filtered.

Bypass Cache

Bypass Cache sends the requests the rule matches to the origin, and Azion does not cache the response. It runs in the Request Phase and requires Application Accelerator on the application. The behavior does not change the browser cache, which Set Cache Policy sets through a cache setting. In the API, it is { "type": "bypass_cache" }, with no attributes.

Bypass Cache acts on Azion’s cache and not on the Tiered Cache layer. An application whose cache settings have Tiered Cache on keeps caching objects in that layer for the minimum TTL. For how Bypass Cache differs from a cache TTL of 0, refer to How Applications works. To bypass the cache for one path, refer to Bypass the cache for a path.

Capture Match Groups

Capture Match Groups applies a regular expression to a request field and stores the groups it captures in a temporary array. It runs in either phase and requires Application Accelerator on the application. Rewrite Request reads the array to build a new path. The array is local, so only the rule that captures it can read it.

A capture is read as %{name[index]}. For example, with capture as the array name, ${uri} as the subject, and ^(.*/)([^/]*)$ as the regular expression, a request for /path/image.jpg fills three entries:

• %{capture[0]} = "/path/image.jpg"
• %{capture[1]} = "/path/"
• %{capture[2]} = "image.jpg"

A group can also carry a name, in the ?<name> notation, and its capture is then read by that name instead of an index. This regular expression names the two groups path and filename: ^(?<path>.*/)(?<filename>[^/]*)$.

Deliver

Deliver ends the processing of the request and delivers the content to the user, and the rules that follow do not run. It runs in either phase, requires no Product, and takes no argument. In the API, it is { "type": "deliver" }.

Deny (403 Forbidden)

Deny (403 Forbidden) answers the request with a 403 Forbidden page and ends the processing of the request. It runs in the Request Phase, requires no Product, and takes no argument. In the API, it is { "type": "deny" }.

Enable Gzip

Enable Gzip compresses the content with gzip when the browser of the user supports it. It runs in either phase, requires no Product, and is { "type": "enable_gzip" } in the API. To turn compression on for an application, refer to Compress application responses with gzip.

Enforce HLS cache

Enforce HLS cache imposes the cache policy Azion defines for live HLS transmissions, and requires Live Ingest. Azion adds the behavior to a Request Phase rule every time you select a Live Ingest source. The behavior does two things: it bypasses the cache rules of the application, and it applies the live HLS policy.

To apply the policy to a stream, refer to Enforce HLS cache for live streaming.

Filter Request Cookie

Filter Request Cookie removes a cookie from the request that Azion sends to the origin, and requires Application Accelerator on the application. A Response Phase rule removes a cookie from the response sent to the user instead, with the API type filter_response_cookie. The argument is cookie-name to remove the cookie, or cookie-name=cookie-value to remove only that value. In the API, the Request Phase type is filter_request_cookie.

Filter Request Header

Filter Request Header removes a header from the request that Azion sends to the origin, and requires no Product. A Response Phase rule removes a header from the response sent to the user instead, with the API type filter_response_header. The argument is the header name, such as Header-Name. In the API, the Request Phase type is filter_request_header.

Five headers cannot be filtered or overwritten:

• Host
• Connection
• Range
• X-Forward-For
• Cdn-Loop

Finish Request Phase

Finish Request Phase ends the Request Phase. The behaviors after it in the rule, and the rules after that rule, do not run. It runs in the Request Phase, requires no Product, and is { "type": "finish_request_phase" } in the API.

Forward Cookies

Forward Cookies makes Azion forward the Set-Cookie header that the origin returns to users, even when the response comes from cache. It runs in the Request Phase, requires Application Accelerator on the application, and is { "type": "forward_cookies" } in the API. A cached response can then carry the Set-Cookie of another user’s session. To keep sessions apart, refer to Forward cookies from the origin to the user.

Cookies created with JavaScript are an alternative to the Set-Cookie response header: a script creates, reads, and expires them through the document.cookie property. A JavaScript cookie takes this format:

Azion does not filter the Cookie request header by default, whatever the Forward Cookies configuration, so JavaScript cookies reach the origin. For more information, refer to JavaScript Cookies.

No Content (204)

No Content (204) answers with 204 instead of the status code the origin returns. It runs in the Request Phase, requires no Product, and is { "type": "no_content" } in the API.

Optimize Images

Optimize Images applies Image Processor to the requests the rule matches, and requires Image Processor on the application. It runs in the Request Phase. In the API, it is { "type": "optimize_images" }: it takes no attributes, and a rule can carry it as its only behavior.

Redirect HTTP to HTTPS

Redirect HTTP to HTTPS redirects a request made over HTTP to HTTPS, and does nothing to a request already made over HTTPS. It runs in the Request Phase and is { "type": "redirect_http_to_https" } in the API. It requires HTTPS enabled in the protocol settings of the workload that delivers the application.

Redirect To

Redirect To (301 Moved Permanently) and Redirect To (302 Found) send the user to the URL or URI in the argument, with that status code. Use 301 when a path changes for good, and 302 when the change is temporary. Both behaviors end the processing of the request, run in either phase, and require no Product. In a Response Phase rule, they run only when the origin returns 404.

The Console asks for the argument with Redirect target is required, and refuses a space in it with Redirect target cannot contain spaces, use %20 instead. In the API, the types are redirect_to_301 and redirect_to_302, with the target in attributes.value. This behavior sends a reader of a FAQ to its English version:

Rewrite Request

Rewrite Request changes the path of the resource that Azion requests from the origin. It runs in the Request Phase, requires Application Accelerator on the application, and is rewrite_request in the API, with the new path in attributes.value. The new path can combine a string, the variables of the Request Phase, and the captures of Capture Match Groups, written as %{name[index]}.

For example, two behaviors in one rule send a request for /original/image.jpg to the origin as /new/image.jpg:

Run Function

Run Function runs a function instance of the application on what the rule matches. It runs in either phase and requires Application Accelerator and Functions on the application. The instances live in the Functions Instances tab of the application, and a new application has Functions on. For the Response Phase, the Console function instance form states Only Lua functions can be used in the Response phase.

In the API, attributes.value holds the ID of the function instance, not of the function, as in { "type": "run_function", "attributes": { "value": <function-instance-id> } }. To create an instance, refer to Instantiate a function on an application.

Set Cache Policy

Set Cache Policy applies a cache setting to the requests the rule matches, which is how a cache setting reaches a request. It runs in the Request Phase and requires no other Product. The cache setting comes first, in the Cache Settings tab of the application, and the behavior then names it in a second list.

The cache setting holds how long an object stays in cache. Its Application Accelerator section holds the variations that set the cache key. In the API, attributes.value holds the ID of the cache setting. The API returns that ID as an integer, even when the request sends it as a string. A cache setting that a rule applies cannot be deleted: the API answers 400 with code 21014.

Set Connector

Set Connector sends the requests the rule matches to a connector, which reaches the origin. In Azion Console, origins have been redesigned as connectors, and this behavior names one. It runs in the Request Phase and requires no Product, so a rule with ${uri} and Set Connector works on an application without Application Accelerator. In the API, attributes.value holds the ID of the connector, as the API section shows.

API

Every rule operation is authenticated and sits under https://api.azion.com/v4/workspace/applications/<application-id>. A request carries a personal token in the Authorization header under the Token scheme. A request with a body also carries Content-Type: application/json.

A create answers 202 with a state of pending, and a list answers 200. The reorder call takes an order array that lists the rule IDs of the phase in their new order.

This call creates a Request Phase rule that sends every request of the application to a connector:

The response carries 202 and a state of pending. The excerpt keeps the rule as the platform stored it:

The platform adds description, an empty string when the create sends none, and order, the position of the rule in its phase. The same body with ${request_uri} in place of ${uri} fails with code 25047 on an application without Application Accelerator.

CLI

Azion CLI creates a rule with azion create rules-engine, which reads the rule from a JSON file in the shape the API takes. --phase names the phase, and it defaults to request.

This file applies a cache setting to every request whose path starts with /static/:

Save it as rule.json, replace <cache-setting-id> with the ID of a cache setting of the application, and create the rule:

The CLI refuses two older shapes of a rule file. A criterion with input_value instead of argument fails with json: unknown field "input_value". A behavior written as {"type":"set_cache_settings","cache_settings_id":"<id>"} fails with data failed to match schemas in oneOf(RequestPhaseBehaviorRequest): the behavior is set_cache_policy, with the ID in attributes.value.

Errors

A rejected rule returns an errors array. Each entry carries a code, a title, a detail, the status, and a source pointer that names the field, and some entries add a meta object. This body answers a rule with ${request_uri} on an application without Application Accelerator:

Related resources