> ## Documentation Index
> Fetch the complete documentation index at: https://bunny.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Before cache execution

> Run your edge scripts before the cache layer to take control of every request, instead of only executing when the cache is missed.

By default, edge scripts run **after** the cache. The CDN serves cached
responses directly, without invoking your script, so cached traffic is not
slowed down by script execution.

With before cache execution enabled, your script runs on **every request**,
before the cache lookup. This gives you full control over the request flow at
the cost of executing your script even for cached content.

Post-cache execution remains the default. Enable before cache execution when
you need per-request logic, such as authentication, tenant-aware routing, or
custom caching rules.

> [!WARNING]
>
> Overriding the default handling of `/.well-known/*` paths in your script can
> break ACME challenges and prevent automated certificate renewal.

## Enable before cache execution

Before cache execution is enabled at the Pull Zone level and applies to the
script linked to that Pull Zone.

Navigate to your Pull Zone, then go to **General** > **Origin** and enable
**Run script before cache**.

For standalone scripts, you can use the same Pull Zone toggle or enable it
directly in the script settings.

With the [Update Pull Zone](https://bunny.net/docs/api-reference/core/pull-zone/update-pull-zone.md)
API, set `EdgeScriptExecutionPhase` to `2` to enable before cache execution.
The default value, `0`, runs the script after the cache.

## Access control

To block requests to cached content, you must enable before cache execution.
In the default mode, the CDN serves a cache HIT without the script. A check
that runs only on a cache MISS does not protect content that is already
cached.

For a complete, tested example, see
[Protect cached content](https://bunny.net/docs/scripting/middleware/examples/protect-cached-content.md).

## Middleware scripts

When before cache execution is enabled, middleware scripts gain access to two
additional hooks that run on the client side of the cache:

* **`onClientRequest`**: runs on every incoming request before the cache
  lookup. Modify the request or short-circuit by returning a response
  directly.
* **`onClientResponse`**: runs just before the response is sent to the
  client, including responses served from the cache.

If before cache execution is off, these hooks do not run, and no error shows.

```ts theme={null}
import * as BunnySDK from "@bunny.net/edgescript-sdk@0.13.0";

BunnySDK.net.http
  .servePullZone({ url: "https://your-origin.com" })
  .onClientRequest((ctx) => {
    // Runs before the cache lookup on every request
    return Promise.resolve(ctx.request);
  })
  .onClientResponse((ctx) => {
    // Runs before the response is sent to the client
    return Promise.resolve(ctx.response);
  });
```

See [Middleware scripts](https://bunny.net/docs/scripting/middleware/overview.md) for the full hook
reference and workflow.

## Standalone scripts

Standalone scripts act as the origin for their Pull Zone, so by default they
only execute when the cache is missed. With before cache execution enabled,
your script handles **every request** before the cache lookup, and decides
whether and how responses are cached.

See [Standalone scripts](https://bunny.net/docs/scripting/standalone/overview.md) for details.

## Workflow

### Default

The script runs only on a cache MISS.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Cache
    participant Script
    participant Origin

    Client->>Cache: Request
    alt Cache HIT
        Cache-->>Client: Cached response
    else Cache MISS
        Cache->>Script: Request
        Script->>Origin: Request
        Origin-->>Script: Response
        Script-->>Cache: Response
        Cache-->>Client: Response
    end
```

### Before cache execution

The script runs on every request, before the cache lookup.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Script
    participant Cache
    participant Origin

    Client->>Script: Request
    Script->>Cache: Cache lookup
    Cache->>Origin: On cache MISS
    Origin-->>Cache: Response
    Cache-->>Script: Response
    Script-->>Client: Response
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.