How Applications works
Trace a request through an Application, from its Workload to the origin, and see where Cache, Application Accelerator, and Image Processor act on it.
Between a client and your content, a layer can read each request first, whether the request asks for a page, a file, or an API route. The layer then decides what happens to the request. It can run code that builds the response with no server behind it, stand in front of the server that holds your content, or do both. In front of that server, it can answer with a copy of a response that the server sent earlier, add or remove a header, or choose the server that receives the request. When a response comes back from that server, the same layer can change it before the client receives it.
On Azion, that layer is an Application. Applications is a Platform Resource that processes the requests received by your Workloads, on Azion’s distributed infrastructure, from the data center nearest to your user. Each request reaches an Application through a Workload, which receives the request on one of its domains. The Workload’s deployment sets the Application that processes the request.
The Application acts on the request through its rules, which you write in Rules Engine for Applications. Each rule belongs to one of two phases: Request Phase rules act on the request, and Response Phase rules act on the response that the user receives. To send the request to the origin, a Request Phase rule uses the Set Connector behavior, which sets the Connector that routes the request there. A rule can also run your code on the request: the Run Function behavior invokes a Function Instance of one of your Functions.
Three Platform Resources nested in Applications act along the path from the Workload to the origin, each with its own switch in the Application. Cache answers with a stored copy of an earlier response. Application Accelerator unlocks four capabilities for the cache and the rules of an Application. Among them, cache variation adds more of the request, such as a cookie or a query-string argument, to the cache key, the index under which Cache files each copy. Image Processor builds a resized or converted image from an image on the origin.
This page explains the mechanisms, and two other pages hold the fields: Rules Engine for Applications lists every variable, operator, and behavior, and Applications limits lists every bound. The sections follow a request along its path, then cover the two phases, how rules run, what a new Application has, and propagation. After them, one section each covers Cache, Application Accelerator, and Image Processor. WebSocket Proxy covers, on its own page, the WebSocket connections that an Application proxies to the origin, and How Functions works covers how a Function runs.
The path a request travels
Creating an Application does not put it in the path of any request: a request reaches the Application only after a Workload’s deployment sets that Application. The relation is stored on the deployment, not on the Application, and in Azion Console you set it in the Application field of the Workload’s Deployment Settings. The deployment can also set a Firewall, and the request then crosses the Firewall before the Application receives it. The domains, protocols, and certificates are on the Workload too, so you configure delivery on the Workload, not on the Application.
The Application does not store an origin either: a request reaches an origin only when a Request Phase rule sends it there with the Set Connector behavior. That behavior sets a Connector, and the Connector holds the address of the origin. The API shows this: an Application created with only name and active comes back with modules, active, and debug, and with no field that points to a server. Connectors replace the origins that earlier versions of Applications configured on the Application. In place of an origin, a Function can answer a request: a rule runs the Function with Run Function, and the Function builds the response with no Connector.
The diagram follows one request on the path to an origin, from the client to the response it receives. Solid arrows carry the request, and dotted arrows carry the response. Each label starts with the number of its step below.
- The client sends the request to one of the Workload’s domains. When the Workload’s deployment also sets a Firewall, the Firewall runs its rules first and can refuse the request.
- The Application that the deployment sets runs its Request Phase rules, in order. When a behavior ends the processing, as Deny (403 Forbidden) does, the Application answers the client, and no later behavior or rule runs.
- When a Set Cache Policy rule applied a cache setting, Cache looks for a valid copy of the origin response. If it finds one, that copy becomes the response, and the origin receives no request.
- Otherwise, the Connector set by a Set Connector rule routes the request to the origin, and the origin’s response returns through that Connector.
- The Application runs its Response Phase rules on the response, and the client receives the result.
Because a rule chooses the origin of each request, one Application can route /api/ to one server and every other path to another, with two rules and two Connectors. The cost is that no request reaches an origin by default: a new Application has no rules, so no Connector is set for its requests. To create the first rule that routes an Application’s requests to an origin, refer to Applications quickstart.
Request and response phases
Each rule of an Application belongs to one phase, and the two phases run in a fixed order: the Request Phase before a response exists, then the Response Phase on the response that the Application delivers. You set the phase of a rule when you create it, and you cannot change it later. In the API, the endpoint that receives the rule sets its phase: request_rules or response_rules. To run the same logic in the other phase, add a second rule in that phase.
The diagram follows a request on the path to an origin. Solid arrows carry the request, and dotted arrows carry the response. Each label starts with the number of its step below.
- The request arrives, and the Request Phase rules run on it first. They can read what the request carries, such as its URI, its headers, and its cookies, but nothing about the response, which does not exist yet.
- These rules decide the cache and the origin. Set Cache Policy applies a cache setting, Bypass Cache sends the request past the cache, and Set Connector sets the Connector that routes the request to the origin. These three behaviors and Optimize Images run only in the Request Phase. In this phase, Add Request Header adds a header to the request that the origin receives.
- The response comes back: either a copy of an origin response that Cache stored, or the origin’s response through the Connector.
- The Response Phase rules run on that response, once for each delivery to the user. They can also read what came back, such as
${status}and the headers the origin sent. In this phase, Add Response Header adds a header to the response that the user receives.
Because the Request Phase runs first, the cache is decided before the response exists. A rule cannot apply a cache setting based on the status code that the origin returns, because ${status} is readable only in the Response Phase, and Set Cache Policy runs only in the Request Phase.
Some behaviors work in both phases, and the phase limits what they do. In a Response Phase rule, Redirect To runs only when the origin returns 404. So a redirect in that phase can send the user to another page when the origin has nothing at the path, and leave the requests for existing paths untouched. Run Function also works in both phases, but the Response Phase accepts only Functions written in Lua. The Function Instance form in Azion Console states this limit: Only Lua functions can be used in the Response phase. Phases lists the variables and behaviors that each phase accepts.
How rules run
Within one phase, the Application takes its rules one at a time, in their order. It stops when every rule of the phase has run or when a behavior ends the processing.
Solid arrows follow one request through the rules of one phase. Each label starts with the number of its step below.
- The request enters a phase, and the Application takes the first rule of that phase.
- The Application compares the criteria of the rule with the request. If they do not match, the rule runs nothing, and the Application moves to the next rule.
- If they match, the rule runs its behaviors one after another, in the order you arranged them.
- When one of those behaviors ends the processing, nothing after it runs in the phase.
- Otherwise, the Application moves to the next rule, until no rule of the phase is left.
Rules Engine for Applications lists the variables, operators, and conditionals that criteria combine.
The position of a rule is its order. The platform assigns it when you create the rule, starting at 0 for the first rule of each phase. You can change the order of the rules in Azion Console, or reorder one phase with a single API call.
Some behaviors cannot share a rule, and the API and Azion Console both refuse those combinations. Behaviors lists them.
Behaviors that repeat
When several rules match a request and carry the same Set behavior, such as Set Connector, the behavior does not accumulate: only the one in the last matching rule runs. For example, a first rule sets a Connector for every path, and a second rule sets another Connector for /api/. A request to /api/ matches both rules, so the Connector of the second rule routes it.
Add Request Header does not repeat a header either: when two matching rules add a header with the same name, the origin receives it once, with the value of the last of those rules.
So the order of the rules shapes the result as much as their content does. A broad rule near the top sets a default, and a narrower rule further down overrides that default for the requests it matches. The same mechanism has a cost: moving a rule in the list can change the Connector that a path reaches, even though no rule changed.
Behaviors that end the processing
Some behaviors stop the processing of a request, and nothing after them runs: no later behavior in their rule, and no later rule. Deny (403 Forbidden) answers with a 403 Forbidden page, Deliver delivers the content to the user, and Redirect To sends the user to another URL with a 301 or 302 status. Finish Request Phase ends the Request Phase at the point where it runs, so the rest of its rule and every later rule of that phase are skipped.
An ending behavior saves work, and it can also hide a rule. Early in the list, it settles the request before later rules spend time on it. Placed before a rule that you still need, it stops that rule for every request that the earlier rule matches. With Debug Rules on, Real-Time Events and Data Stream show which rules each request ran. Debug Rules is the debug field of the Application in the API, and Main Settings shows where to turn it on in Azion Console.
What a new Application has
A new Application has two switches on, Cache and Functions, and no rules. When you create an Application through the API with only name and active, the response carries these fields:
Its list of request rules is empty, with count at 0. The four keys of modules are the four switches of an Application, and Main Settings shows each one in Azion Console and the API. Cache cannot be turned off: the API refuses false in modules.cache.enabled with 31001, and in Azion Console the Cache switch is locked on, with the note Automatically enabled in all accounts. Tiered Cache is not one of these switches: it is a Feature of Cache, and each cache setting turns it on in its modules.cache.tiered_cache.enabled field.
Cache is on, but it stores copies only after a rule applies a cache setting, and a new Application has no cache settings and no rules. Cache starts storing copies once you create a cache setting and a Set Cache Policy rule that applies it.
While a switch is off, the rule options that depend on it are unavailable. The Rules Engine form in Azion Console labels each of those options with - Required Application Accelerator, - Required Image Processor, or - Required Function, and the API refuses a rule that uses one. For example, on an Application with Application Accelerator off, a request rule with a criterion on ${request_uri} returns 400 with this body:
The API accepts the same rule with ${uri} instead of ${request_uri}, because ${uri} depends on no Platform Resource. This check keeps a rule from relying on a Platform Resource that is off in the Application. The trade-off is a choice between two variables: ${uri} holds the decoded URI without the query string, while ${request_uri} keeps the query string and needs Application Accelerator. Rules Engine for Applications lists the variables and behaviors that each Platform Resource adds.
Propagation
A change to an Application reaches traffic only after it propagates across Azion’s distributed infrastructure, and Azion guarantees no propagation time. A new rule on an Application that already serves traffic can take a few minutes to apply. The deployment of a new Workload can take several minutes to propagate, and until it does, the Workload answers with Azion’s placeholder 404.
While a change propagates, the answers alternate, because each request can reach a different data center. One request returns the placeholder 404, and the next returns the Application’s response. One correct answer after a change does not prove that the change is live, because the next request can still return the placeholder. Repeat the request until every answer is the one you expect.
A Firewall that the same deployment sets can join the path much later than the Application. So a domain that already answers can still serve requests that skip the Firewall. To see how a Firewall acts on requests, refer to Firewall.
Cache
A cache stores a copy of an origin response in the data center that fetched it. Later requests for the same object get that copy, and the origin receives no request for them. Each copy is filed under a cache key, built from the request, and kept for its time to live (TTL). When the TTL ends, the copy expires, and the next request for that object checks with the origin.
In an Application, Cache stores those copies, and it is on in every Application you create. A cache setting belongs to one Application and holds the TTLs and the inputs that make two requests different. A cache setting acts only through a Request Phase rule, which applies that cache setting with Set Cache Policy to the requests that the rule matches. Bypass Cache does the opposite and sends the request past the cache.
Cache settings lists every field and its default, and Cache keys gives the full key format. To vary the cache by query string, cookie, device group, or method, you need Application Accelerator. Cache quickstart creates a first cache setting and the rule that applies it.
The Cache overview shows where Cache acts on a request, and Expiration and freshness explains how long a copy lives and what ends it.
Application Accelerator
A cache key built from the URL alone assumes that each URL has one correct response. Dynamic content breaks that assumption: under a single URL, a signed-in visitor sees their own cart, a listing reorders when a filter changes, and the layout differs on a phone. With a key built from the URL alone, the cache either serves one visitor’s response to another, or it cannot cache the path at all.
In an Application, Application Accelerator unlocks cache variation, which removes that assumption, and three more capabilities for dynamic content. It is off in a new Application, and each Application turns it on separately, in its modules.application_accelerator.enabled field in the API. Each cache setting then holds its own variations, in its own modules.application_accelerator object. If you have written a Vary header or a cache-key rule, the model is the same: you list the inputs that make two requests different. Application Accelerator settings lists each field, its type, and its default, and Applications limits gives the TTL bounds. To turn Application Accelerator on and add a first variation to a cache setting, refer to Application Accelerator quickstart.
The Application Accelerator overview shows how a variation changes the cache key, and Cache variation explains what turning it on unlocks and what each variation costs.
Image Processor
A page often needs the same image in several sizes, crops, and formats, one for each layout and browser. Preparing every variant in advance means one stored file per variant, and a rebuild of all of them whenever the original changes. Transforming the image at request time avoids both: the URL describes the variant, and the platform builds it from one original when a request asks for it.
In an Application, Image Processor builds those variants. The request URL describes the variant in its ims query string, and Image Processor applies that description to the source image on the origin. Even with no ims query string, Image Processor can convert the image to a format the browser accepts. The result, the derived image, is what the client receives. Image Processor reads the source image without changing it, and it returns the derived image without saving it as an asset of the account. So one file on the origin serves every size, crop, quality, and format that a page requests.
Image Processor is off in a new Application, and each Application turns it on separately, in its modules.image_processor.enabled field in the API. Even when it is on, Image Processor acts only on the requests that a Request Phase rule with Optimize Images matches. Image Processor URL parameters lists the operations that ims accepts, and Image Processor settings covers the headers and behaviors. To turn Image Processor on and request a first derived image, follow Image Processor quickstart.
The Image Processor overview shows where Image Processor acts on a request, and Image delivery explains how the delivered format is chosen and where Image Processor stops.