Rules Engine for Edge Application
Rules Engine is an Edge Application capability that handles the conditional execution of behaviors through logical operators. By using Rules Engine, you can build an architecture that provides better performance to your users while consuming fewer resources by processing at the origin.
1. How it works
Each requisition made to an application built with Azion Real-Time Manager is processed in a fixed sequence of two phases: first the Request Phase, then the Response Phase.
At each processing phase, you can define a set of rules to handle the request according to the needs of your application or business. Once you have selected in which of the two phases your rule will be executed, you’ll be able to create a new rule.
Rules are designed to follow a conditional if-then logic. Every rule is composed of Criteria (if) that will define the set of conditions that must be met for the execution of Behaviors (then).
You can use a set of variables, comparison operators, and logical operators to trigger the desired behaviors for your application. If the conditions are met, the behaviors of each rule are executed until all the rules are processed.
Warning: some behaviors can finish the execution of rules. If a sequence of rules includes such behavior, any rules or behaviors that follow the finalizing behavior won’t be executed.
Before you create a rule, you should enable the Application Acceleration module, which extends the usability of Rules Engine by applying serverless computing features to Edge Application. If the module is disabled, only some variables and Behaviors will be available for your rule.
See Creating rules using Rules Engine for Edge Application for a step-by-step guide on how to use Rules Engine.
2. Processing phases
When creating a rule, you’ll be prompted to select one of the two available processing phases: Request Phase or Response Phase.
2.1. Request Phase
In the Request Phase, you can handle your user’s request according to your business rules and define which origins should handle the request in case the requested content isn’t cached.
You can use any variable related to the data sent by your user in the request as variables for Request Phase rules. As the response hasn’t been processed by your application yet, you don’t have access to variables related to the content that will be delivered to your user in this phase.
You also define how Azion should manage your application’s cache in the Request Phase. If your application doesn’t allow any type of cache, you can define the conditions to ignore caching.
2.2. Response Phase
In the Response Phase, your application handles what will be delivered to your users. All handling processed in the Response Phase is dynamic and will be performed individually for each user.
3. Description
Aside from the name of the rule, you can add a description to your rule using the Description field. Your description will be visible from the rule list and can be used to help you identify what the rule does.
4. Criteria
The Criteria section of Rules Engine is where you define the conditions for executing the rule.Criteria are composed of:
- variables
- comparison operators
- arguments, when applicable
The inclusion of arguments in a criteria depends on the comparison operators chosen. The format of the arguments is described in the variables and comparison operators sections below. You can also add logical operators to increase the amount of comparisons that the rule will execute.
For example, this criteria identifies whether a user is accessing your application via a desktop web browser using a regular expression as an argument:
| Variable | Comparison operator | Argument | |
|---|---|---|---|
| If | ${http_user_agent} |
matches | (Chrome|Mozilla) |
4.1. Variables
| Variable | Description | Phase |
|---|---|---|
${arg_name} |
The name argument sent by the user on the request line (query string). For example: for the GET /path?Search=test request, the variable will assume the value test. |
Request Phase Response Phase |
${args} |
All arguments sent by the user in the request string (query string). For example: for the GET /path?Search=test request, the variable will assume the value Search=test. |
Request Phase Response Phase |
${cookie_name} |
Value of the cookie name. For example, for cookie_icl_current_language = pt-br, the variable ${cookie_icl_current_language} will assume the value pt-br. |
Request Phase Response Phase |
${device_group} |
User device group. You can customize your device groups in the Device Groups tab of your application in Real-Time Manager. | Request Phase Response Phase |
${geoip_city_continent_code} |
2-letter continent code, using the geolocation base geoip_city. For example: EU for Europe, NA for North America. |
Request Phase Response Phase |
${geoip_city_country_code} |
2-letter country code, using the geolocation base geoip_city. For example: RU for Russia, BR for Brazil. |
Request Phase Response Phase |
${geoip_city} |
Name of the city, using the geolocation base geoip_city. For example: Sao Paulo, London. |
Request Phase Response Phase |
${geoip_continent_code} |
2-letter continent code. For example: EU for Europe, NA for North America. |
Request Phase Response Phase |
${geoip_city_country_name} |
Name of the country, using the geolocation base geoip_city. For example: United States, Brazil. |
Request Phase Response Phase |
${geoip_country_code} |
2-letter country code, using the geolocation base geoip_country. For example: RU for Russia, BR for Brazil. |
Request Phase Response Phase |
${geoip_country_name} |
Name of the country, using the geolocation base geoip_country. For example: United States, Brazil. |
Request Phase Response Phase |
${geoip_region_name} |
Name of the country, using the geolocation base geoip_region. For example: Ontario, Sao Paulo. |
Request Phase Response Phase |
${geoip_region} |
2-letter region code. For example: RS for Rio Grande do Sul, ON for Toronto. |
Request Phase Response Phase |
${host} |
In order of precedence: the host name of the request line, or the value of the Host header field of the request, or the name of the server serving the request. | Request Phase Response Phase |
${http_name} |
The value of a request header. name must be a valid HTTP request header converted to lowercase; hyphens must be converted to underscore. For example: ${http_accept} will take the value of the Accept header of the HTTP request field. |
Request Phase Response Phase |
${remote_addr} |
The IP address of the client performing the HTTP request. | Request Phase Response Phase |
${remote_user} |
The username provided by basic authentication, if any. | Request Phase Response Phase |
${request} |
Complete request query. | Request Phase Response Phase |
${request_body} |
POST arguments sent in the body of the request. | Request Phase Response Phase |
${request_method} |
The HTTP method of the request. For example: GET. |
Request Phase Response Phase |
${request_uri} |
The complete URI of the request, with arguments (query string). | Request Phase Response Phase |
${scheme} |
The scheme of the request. For example: http or https. |
Request Phase Response Phase |
${sent_http_name} |
The value of the response header field name. The name argument must be converted to lowercase and the hyphens must be converted to underscore. For example: ${sent_http_content_length} will take the value of the Content-Length header. |
Response Phase |
${status} |
Status code of the response. | Response Phase |
${upstream_addr} |
The IP address and port of the queried origin for obtaining the response. If many origins are consulted during the processing of the request, the addresses will be separated by a comma. For example: 192.168.1.1:80, 192.168.1.2:80. If an internal redirect from one group of servers to another occurs, initiated by an X-Accel-Redirect or an error page, the addresses of the different groups will be separated by a colon. For example: 192.168.1.1:80, 192.168.1.2:80 : 192.168.10.1:80, 192.168.10.2:80. |
Response Phase |
${upstream_cookie_name} |
Value of cookie name sent by the origin using the Set-Cookie header field. If many origins are consulted while the request is processed, only cookies from the last origin are stored. | Response Phase |
${upstream_http_name} |
Value of the name header field sent by the origin. The name argument must be converted to lowercase and the hyphens must be converted to underscore. If many origins are consulted while the request is processed, only headers from the last origin are stored. For example: ${upstream_http_server} will assume the value of the Server header field sent by the last queried origin. |
Response Phase |
${upstream_status} |
Status code of the origin response sent to RTM. If many origins are consulted while the request is processed, the status codes will be separated by a comma. If an internal redirect from one group of servers to another is initiated by an X-Accel-Redirect or an error page, the status codes of the different groups will be separated by a colon. |
Response Phase |
${uri} |
The normalized (urldecoded) URI of the request. The value of ${uri} can change during the processing of a request, for example, when an internal redirect occurs or when index files are used. For query string parameters, use ${request_uri}. |
Request Phase Response Phase |
4.2. Comparison Operators
| Operator | Description | Argument type |
|---|---|---|
| is equal | The value of the variable is exactly the same as the argument. | string |
| is not equal | The value of the variable isn’t the same as the argument. | string |
| starts with | The value of the variable starts with the argument. | string |
| does not start with | The value of the variable doesn’t start with the argument. | string |
| matches | The value of the variable matches the regular expression entered as an argument. | regular expression |
| does not match | The value of the variable doesn’t match the regular expression entered as an argument. | regular expression |
| exists | The variable has a defined value. For example: ${arg_search} exists if a search argument was sent in the request query string. |
- |
| does not exist | The variable doesn’t have a defined value. For example: ${arg_search} doesn’t exist if a search argument wasn’t sent in the request query string. |
- |
4.3. Logical Operators
Multiple criteria can be defined using the logical operators AND and OR. Each rule can have up to 10 criteria.
The operator AND has implicit precedence over the operator OR. If explicit precedence is required, you can add more criteria groups using the AND operator only.
5. Behaviors
In the Behaviors section of the Rules Engine, you must add the behaviors you want your rule to perform if the conditions defined in the criteria are met.
For example, this behavior redirects the user to an English version of an FAQ location:
| Behavior | Argument |
|---|---|
| Redirect To (302 Found) | /en-us/faq |
Each rule can perform up to 10 behaviors.
Each behavior has their own set of requirements, described in the table below.
| Behavior | Description | Phase | Requirements |
|---|---|---|---|
| Add Request Cookie | Adds a cookie in the Set-Cookie request header. The cookie must be inputted as an argument in the format cookie-name=cookie-value. You may use a variable as a cookie value, for example: cookie-name=${arg_cookie}. |
Request Phase | Application Acceleration |
| Add Response Cookie | Adds a cookie and policies in the Set-Cookie response header. The cookie must be inputted as an argument in the format cookie-name=cookie-value.For response cookies, the following Set-Cookie policies can be added to the argument, following the cookie value and a semicolon ( ;):<li> Expires=date (EEE, d MMM yyyy HH:mm:ss Z)<li> Domain=domain-value<li> Path=path-value<li> Max-age=number (TTL in seconds, takes precedence over Expires)<li> SameSite=value; Secure<li> HttpOnlyMultiple policies for the same cookie can be separated by semicolons ( ;). For example: cookie-name=cookie-value; Domain=domain-value; Path=path-value; SameSite=value.You may also use variables as a cookie or policy value, for example: Path=${uri}; Domain=${host}. |
Response Phase | Application Acceleration |
| Add Request Header | Adds a header field to the request that will be sent to the origin. The header field must be informed as an argument in the format Field:value |
Request Phase | - |
| Add Response Header | Adds a header field to the response that will be sent to the user. The header field must be informed as an argument in the format Field: value. |
Response Phase | - |
| Bypass Cache | Defines that Azion shouldn’t cache the response from its origin. The execution of this rule has no impact on the cache in the users’ browser, which must be defined using the Set Cache Policy behavior. | Request Phase | Application Acceleration |
| Capture Match Groups | Support behavior for handling strings. Stores in a temporary variable the result of capturing correspondence groups defined by a regex applied to one of the available HTTP request fields. This temporary variable can be referenced later in the behavior Rewrite Request to assemble the rewrite string. This behavior requires three arguments: captured array name: the name you want to give the temporary variable where the array of captured strings will be stored. subject: the HTTP request field where you want to capture a string. regex: the regular expression used to capture the strings. Each captured group must be represented in parentheses. For example, to capture the path and name of a file in an HTTP request, you could use: captured array name: capturesubject: ${uri}regex: ^(./)([^/])$You may reference the capture variable as an array by using the notation %{variable[index]}. Because it’s a local variable, you can only use it within the same rule you are setting up. In this example, if the URI is /path/image.jpg, the capture variable will have the following values:%{capture[0]} = “/path/image.jpg”%{capture[1]} = “/path/”%{capture[2]} = “image.jpg”You can also name the indexes to reference them using names instead of a numeric index. To do so, use the ?<name> notation as in the example:captured array name: capturesubject: ${uri}regex: ^(?<path>.*/)(?<filename>[^/]*)$ |
Request Phase | Application Acceleration |
| Deliver | Finishes processing the request and delivers the content to the user, without executing any of the rules added later. You are forcing the processing to end immediately. | Request Phase Response Phase |
- |
| Deny (403 Forbidden) | Delivers a 403 Forbidden page to the user. Ends the request processing. | Request Phase | - |
| Enable Gzip | Enables Gzip data compression, if supported by the user’s browser. See the guide on How to enable gzip compression for more information. | Request Phase Response Phase |
- |
| Enable Sliced Files | Enables segmentation of large objects into 1MB slices, if their origin supports HTTP range requests. You can use this behavior to optimize the performance of your website or application; if you deliver media larger than 1MB through the CDN so that the content reaches users before Azion has received the entire object from its origin. When activating this functionality, Azion will request the objects for their origin via range requests and they’ll be cached in Azion with Advanced Cache Key. If your origin doesn’t support range requests, Azion will only be able to start delivering your content to its users after your origin has completed the complete sending of the object. |
Default Rule | - |
| Enforce HLS cache | This behavior is automatically included by Azion whenever you select a Live Ingest origin. Performs two actions: the bypass of all your Cache Phase rules and the imposition of the cache policy defined by Azion for live transmissions in HTTP Live Streaming (HLS). Azion’s cache policy for live HLS streams is 5 seconds of cache for playlists (.m3u8) and 60 seconds of cache for chunks (.ts). |
Request Phase | Live Ingest |
| Filter Request Cookie | Removes a cookie from the request header that would be sent to the origin. As an argument, add the name of the cookie you want to remove as cookie-name.To remove only specific values, you must inform the name and value of the cookie as cookie-name=cookie-value. |
Request Phase | Application Acceleration |
| Filter Response Cookie | Removes a cookie from the request header that would be sent to the user. As an argument, add the name of the cookie you want to remove as cookie-name.To remove only specific values, you must inform the name and value of the cookie as cookie-name=cookie-value. |
Response Phase | Application Acceleration |
| Filter Request Header | Removes a request header that would be sent to the origin. The name of the header field must be entered as an argument, for example: Header-Name. |
Request Phase | - |
| Filter Response Header | Removes a response header that would be sent to the user. The name of the header field must be entered as an argument, for example: Header-Name. |
Response Phase | - |
| Forward Cookies | By using the Forward Cookies behavior, you are determining that Azion forwards to the users the Set-Cookie header received from its origin, even in a cache content situation (cache hit). To prevent a user from receiving another user’s Set-Cookie session, see the guide on Forward Cookies. |
Request Phase | Application Acceleration |
| Optimize Images | Enables Image Processor. | Request Phase | Image Processor |
| Redirect HTTP to HTTPS | Redirects the HTTP request to the respective HTTPS URL. If the request is already HTTPS, it doesn’t execute any behavior. | Request Phase | HTTPS application. |
| Redirect To (301 Moved Permanently) Redirect To (302 Found) |
These behaviors redirect the user to another URL entered as an argument, returning the status code 301 Moved Permanently or 302 Found. It is recommended that these behaviors be used for path changes; 301 Moved Permanently for permanent changes and 302 Found for temporary changes. This behavior ends the request processing. Warning: in the Response Phase, Redirect To behaviors are only executed when the origin returns a 404 error. |
Request Phase Response Phase |
- |
| Rewrite Request | Modifies the resource path that will be requested for the origin. You can rewrite the resource path using: a string the requisition variables (which can also be used in Criteria) the local variables, in the format %{name [index]}, with the result of capturing strings, when using the auxiliary behavior Capture Match Groups.For example, if you want a user’s request for the /original/image.jpg resource to be sent to its origin as /new/image.jpg, you can:<li>Use the Capture Match Groups auxiliary behavior with the arguments: captured array name: capturesubject: ${uri}regex: /original/(.)<li>Use the Rewrite Request behavior with the argument /new/%{capture[1]}. |
Request Phase | Application Acceleration |
| Run Function | Runs a function created using Edge Functions and instantiated in the Edge Functions tab for the edge application. See the guide on How to run serverless functions for more information. | Request Phase Response Phase |
Application Acceleration Edge Functions |
| Set Cache Policy | Assigns the cache policy that should be used for the request. Before configuring this behavior, you must set up the cache policies in the Cache Settings tab. In the Cache Policies section, you can set up the time that an object will be stored in cache and the rules for the variation of objects in cache with the Advanced Cache Key. | Request Phase | - |
| Set Origin | Assigns an origin that must be consulted by the Intelligent Edge. Before configuring this behavior, you must set up the origins in the Origins tab. | Request Phase | - |
6. Functions
For behaviors that request a mandatory argument, you can use the same variables available for both processing phases. This way, you can compose cookies or HTTP headers via a Response using data collected from a Request, such as the user’s device group or their geolocation.
Azion also provides some functions to simplify the handling of your arguments:
| Function and Argument | Description |
|---|---|
${cookie_time_offset(number)} |
Returns the current date plus an offset in seconds, entered as an argument, to be used to define the expiration time of a cookie. For example, if you want the cookie to expire in 1 hour, use the Add Response Cookie behavior with the argument: cookie-name=cookie-value; Expires=${cookie_time_offset(3600)} |
${encode_base64(string)} |
Returns the arguments coded in base64. For example: ${encode_base64(http://www.yourdomain.com/)} will return the value d3d3LmRvbWFpbi5jb20K |
7. Mutual Transport Layer Security (mTLS) variables
Add those variables inside the Rules Engine of your edge application to configure Mutual Transport Layer Security (mTLS).
Find out more about support for mTLS and the difference between Enforce (standard) and Permissive modes.
| Variable | Description | Phase |
|---|---|---|
| ${ssl_client_fingerprint} | Returns the Secure Hash Algorithm 1 (SHA-1) of the client certificate. | Request |
| ${ssl_client_escaped_cert} | Returns the client certificate in Private Enhanced Mail (PEM) format as URL encoded string. | Request |
| ${ssl_client_s_dn} | Returns the “subject DN” string of the client certificate. | Request |
| ${ssl_client_s_dn_parsed} | Returns the extracted “subject CN” value of the client certificate. | Request |
| ${ssl_client_cert} | Returns the client certificate (PEM format). This variable is deprecated. Use $ssl_client_escaped_cert instead. |
Request |
| ${ssl_client_i_dn} | Returns the “issuer DN” string of the client certificate. | Request |
| ${ssl_client_serial} | Returns the serial number of the client certificate. | Request |
| ${ssl_client_v_end} | Returns the end date (expiration date) of the client certificate. | Request |
| ${ssl_client_v_remain} | Returns the number of days until the client certificate expires. | Request |
| ${ssl_client_v_start} | Returns the start date of the client certificate. | Request |
| ${ssl_client_verify} | Returns the result of the client certificate verification. It can be SUCESS, FAILED:reason, or NONE. |
Request |
Tip: most mTLS services rely on receiving the user certificate. Using Real-Time Manager (RTM), you can send the
${ssl_client_escaped_cert}variable as a Request Header (known as X-Forward-Client-Cert [XFCC]) to the origin, then configure your edge application to use this header with the certificate data.
8. Debugging rules
Note: this functionality is in early access. Contact our Sales team to enable it for your account.
You can debug rules created in Rules Engine for Edge Application through the GraphQL API, Data Streaming, or Real-Time Events.
See How to debug rules created with Rules Engine for detailed information and instructions on how to activate and use this functionality.
Didn’t find what you were looking for? Open a support ticket.