---
url: https://docs.smoxy.eu/concepts/request-lifecycle.md
---
# Request Lifecycle

This page explains what happens to a request from the moment a visitor's browser resolves your hostname until the response is delivered — and in which order smoxy's features act on it. Use it as the mental model behind every other page: security decisions, rules, caching, and origin fetching all happen at a specific point in this sequence.

***

### 1. DNS & TLS

A request reaches smoxy because the hostname's **CNAME record** points at smoxy. Until that record resolves to smoxy, nothing else on this page applies — the zone can be fully configured and certificates issued without any traffic being redirected.

At the edge, smoxy terminates TLS using the certificate that covers the hostname (see [How SSL Works](/ssl-and-certificates/how-ssl-works)).

### 2. Hostname → Zone resolution

The `Host` header maps the request to a **hostname**, and the hostname to its **zone**. From this point on, all of the zone's configuration applies: proxy settings, security, rules, caching, and optimization. Two switches gate everything downstream:

* The zone's **Enabled/Disabled** toggle (zone header) — a disabled zone does not process traffic with smoxy features.
* The hostname's **CDN** flag — with CDN disabled, caching and optimization are skipped for this hostname, while proxy and security handling can still apply.

[Redirects](/zones/redirects) are resolved right after zone resolution — a redirect hostname answers here, before any security or content handling.

See [Hostnames](/zones/hostnames) and [What is a Zone?](/zones/what-is-a-zone).

### 3. IP Lists

Security screening happens before content handling, so blocked traffic never touches the cache or your origin. The IP lists are evaluated in this order — an **allow** short-circuits everything below it:

1. **Global allowlist** — smoxy's operator-managed trust list. A match is **absolute for the security layer**: it bypasses everything below it, including the zone blocklist and access rules. **Basic Auth is the exception and is never bypassed** (see step 7). This is the one exception to the customer-first rule and is reserved for smoxy's own trusted infrastructure.
2. **Zone allowlist** — a match flags the request `s-allowlist` and skips the zone blocklist, reputation, Under Attack Mode, and the WAF. It does **not** skip access rules or Basic Auth. Because allowlisted traffic is neither ingested nor scored by the [managed scenarios](/zones/security-and-waf), an allowlisted IP can never be blocked or challenged by a scenario. A zone allowlist entry also overrides smoxy's **global blocklist** for this zone.
3. **Zone blocklist** — a *block* entry ends the request here (a *challenge* must be passed to continue). Because this runs before the rule stages, a zone blocklist entry **cannot be overridden by an allow access rule** — use the zone allowlist to exempt an IP.
4. **Global blocklist** — smoxy's operator-managed blocklist. A zone allowlist entry (step 2) overrides it for that zone.

This matches what [Threat Lookup](/zones/threat-lookup) displays as the decision source: zone → global blocklist → global reputation.

### 4. Access Rules

[Access Rules](/rules/access-rules) run after the IP lists and before the scenario/WAF stage: they evaluate request properties (IP, country, path, user agent, …) and **allow, block, challenge, or skip**. The **Skip** action exempts the request from the WAF stage or from challenges; **Stop Mode** halts evaluation of further access rules after a match. Access rules apply even to zone-allowlisted traffic — they are your own policy layer on top of the trust lists.

### 5. Scenarios & WAF

Unless an allow (or a skip action) exempted the request, three checks follow in order:

1. **Reputation** — decisions produced by the [managed scenarios](/zones/security-and-waf) for this IP (block, challenge, or throttle). The scenario engine itself runs out-of-band on the traffic logs; the request path only enforces its stored verdicts — which is why [Threat Lookup](/zones/threat-lookup) can show the full decision history.
2. **Under Attack Mode** — when active for the zone, visitors must pass a challenge before continuing.
3. **WAF** — the [managed ruleset](/zones/security-and-waf) inspects the request and blocks matches (typically with a 403).

### 6. Rewrite Rules

[Rewrite Rules](/rules/rewrite-rules) transform the URL **before** anything downstream sees it. Everything after this stage — conditional rules, the cache key, and the origin request — operates on the rewritten URL. Rules match with `=`, `~`, or `~*` and can reuse capture groups in the target.

### 7. Conditional Rules

[Conditional Rules](/rules/conditional-rules) are the last rule stage. **All matching rules apply** (in ascending position order, unless a matching rule sets **Stop**), and each can override zone settings for this single request — caching behavior, cache key composition, image optimization settings, basic auth, and more. See [Execution & Ordering](/rules/rules-execution-and-ordering) for the full pipeline semantics.

After the rule stages, **Basic Auth** is enforced (as configured on the zone or overridden per rule). **No allowlist bypasses it** — not a zone allow, not a global allowlist match, and not a verified search-engine crawler. A password-protected zone answers `401` to a trusted IP that presents no valid credentials. This is deliberate: an allowlist is a trust list for the security layer, not a credential, and it keeps synced third-party ranges such as crawler and CDN networks out of protected content. The only way to switch Basic Auth off for part of your traffic is a [Conditional Rule](/rules/conditional-rules) carrying the **Basic Auth** setting.

### 8. Cache

With security passed and the final URL known, smoxy decides whether the response can come from the edge cache:

1. **Eligibility** — the hostname has CDN enabled and the response Content-Type is cacheable (see [Supported MIME Types](/zones/supported-mime-types)). HTML requires the zone's **Dynamic cache** to be enabled; stylesheets, JavaScript, JSON, XML/text and fonts require their [content class](/zones/cache#cacheable-content-types) to be enabled. Responses over 10 MB are never stored.
2. **Cache key** — built from the request URI and query string, optionally extended by hostname, country, cookie, and header values ([Cache](/zones/cache#cache-key)).
3. **HIT** — the key exists in the cache: the response is served from the edge, the origin is not contacted, and the response carries `s-cache: HIT`.
4. **MISS** — not cached yet: the request continues to the origin and the response is stored according to the TTL and the origin's `Cache-Control`. A URL that smoxy is seeing for the first time is served but not yet stored; an object is admitted once it proves it recurs, so a brand-new URL is served from the edge from its third request on ([details](/zones/cache#miss)).
5. **BYPASS** — smoxy deliberately skips the cache: the origin sent `no-cache`, `private`, or `max-age=0` *without* a positive `s-maxage` (with **Respect origin Cache-Control** enabled), the request carried a valid `http-bypass` header, or the content type is ineligible. Remember: **`s-maxage` takes precedence** — `max-age=0, s-maxage=3600` is cached ([details](/zones/cache#respect-cache-control)).

Stale-cache options can serve expired content while the origin is unreachable or while a fresh copy is being fetched ([Stale Cache](/zones/cache#stale-cache)).

### 9. Origin

On MISS or BYPASS, smoxy forwards the request to the zone's **default backend** — a single origin or a load balancer distributing across origins via **Random** or **IP Hash** ([Backends](/organization/origins-and-loadbalancer)). The request arrives at your origin with:

* the configured **Host header** (or the origin's default),
* your custom **request headers** ([Proxy](/zones/proxy)),
* smoxy's **GeoIP headers** describing the visitor's location ([GeoIP Headers](/developer-guide/geoip-headers)).

When the backend is a load balancer, a connection failure fails over to the next healthy origin — retried only while nothing has yet been sent upstream ([Resilience and Failover](/organization/origins-and-loadbalancer#resilience-and-failover)).

### 10. Response processing

Before the response reaches the visitor, smoxy applies:

* **Custom response headers** — applied after the origin responds, so they override origin headers of the same name ([Proxy](/zones/proxy)).
* **Debug headers** — including `s-cache`, when enabled ([Proxy](/zones/proxy)).
* **Custom error pages** — a `502`/`504` from the origin, and the `503` generated when no origin is available, are replaced by the zone's error page ([Custom Pages](/zones/custom-pages)).
* **SSI / ESI processing** — edge-side page assembly ([Cache](/zones/cache#ssi-esi)). ESI tags are rewritten to SSI includes, and the includes are expanded at delivery time, on every request: for cache HITs as well as MISSes. The cache stores the unassembled page; every included fragment is fetched and cached independently.
* **Image optimization** — AVIF/WebP conversion and quality targeting, per zone settings or conditional-rule overrides ([Optimization](/zones/optimization)). Conversion runs asynchronously after the first miss: the first response delivers the original, an optimization job then creates the variants. Variants are stored alongside the original as separate cache files and selected per request from the `Accept` header.
* **HTML minification** — if enabled ([Optimization](/zones/optimization#code-minification)).

***

### Where to go next

* [Cache](/zones/cache) — every caching control in detail
* [Rules: Execution & Ordering](/rules/rules-execution-and-ordering) — the rule pipeline in depth
* [Security & WAF](/zones/security-and-waf) — the security layer's features
* [Cache Invalidation](/developer-guide/cache-invalidation) — purging from your application
