Middleware scripts

Middleware scripts allow you to transform and modify HTTP requests and responses as they flow through the CDN. Manipulate requests before they reach your origin server or the cache and alter responses before they are sent back to the client.

Middleware scripts sit inside the CDN request flow. Your logic runs on requests on their way in and on responses on their way out, so you can change how traffic behaves without touching your backend, and the work happens at the edge rather than on your origin.

Use cases

• Verify credentials and manage session tokens at the edge
• Add, modify, or remove HTTP headers on requests and responses
• Rewrite HTML, inject scripts, or otherwise change the response body before delivery
• Run A/B tests and feature flags, routing users based on headers or cookies
• Route or redirect requests based on path, geolocation, or your own logic
• Apply rate limiting, IP filtering, or bot protection

The servePullZone function

The servePullZone function creates a middleware handler that integrates with your Pull Zone. It returns a chainable object for adding request and response middleware.

import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http
  .servePullZone({ url: "https://your-origin.com" })
  .onOriginRequest((ctx) => {
    // Modify or intercept requests
    return Promise.resolve(ctx.request);
  })
  .onOriginResponse((ctx) => {
    // Modify responses
    return Promise.resolve(ctx.response);
  });

Function signature

servePullZone(options: { url: string }): PullZoneHandler

Option	Type	Description
url	string	The origin URL to proxy requests to. Only used during local development; in production, the Pull Zone origin is used.

The url option is only used during local development. When deployed to bunny.net, requests are proxied to the origin configured in your Pull Zone settings.

Middleware methods

The servePullZone function returns a PullZoneHandler object with chainable middleware methods:

onClientRequest

Preview

If your PullZone is configured to execute script before cache, you’ll have access to this function.

Intercepts requests before they are sent to the cache. You can modify the request or short-circuit by returning a response directly.

onClientRequest(
  middleware: (ctx: { request: Request }) => Promise<Response> | Response | Promise<Request> | Request | void
): PullZoneHandler

Property	Type	Description
ctx.request	Request	The incoming request object

Return value:

• Return Promise<Request> to continue to the origin with the (modified) request
• Return Promise<Response> to short-circuit and respond immediately without hitting the cache

onClientResponse

Preview

If your PullZone is configured to execute script before cache, you’ll have access to this function.

Intercepts responses before they are returned to the user, including responses served from the cache.

onClientResponse(
  middleware: (ctx: { request: Request; response: Response }) => Promise<Response> | Response
): PullZoneHandler

Property	Type	Description
ctx.request	Request	The original request object
ctx.response	Response	The response from the origin server

Return value:

• Return Promise<Response> or Response with the (modified) response to send to the client.

onOriginRequest

Intercepts requests before they are sent to the origin server. You can modify the request or short-circuit by returning a response directly.

onOriginRequest(
  middleware: (ctx: { request: Request }) => Promise<Request> | Promise<Response>
): PullZoneHandler

Property	Type	Description
ctx.request	Request	The incoming request object

Return value:

• Return Promise<Request> to continue to the origin with the (modified) request
• Return Promise<Response> to short-circuit and respond immediately without hitting the origin

onOriginResponse

Intercepts responses from the origin server before they are sent to the client. Modifications occur before the response is cached.

onOriginResponse(
  middleware: (ctx: { request: Request; response: Response }) => Promise<Response>
): PullZoneHandler

Property	Type	Description
ctx.request	Request	The original request object
ctx.response	Response	The response from the origin server

Return value:

• Return Promise<Response> with the (modified) response to send to the client

Enable before cache scripts

Preview

Before cache execution is turned on per Pull Zone. Navigate to your Pull Zone, then go to General > Origin and enable Run script before cache.

Learn more about before cache execution.

Workflow

When a client makes a request to a Pull Zone, the request passes through middleware at different stages:

If your PullZone is configured to execute script before cache, you’ll run the onClientRequest and onClientResponse if those are registered.

1. onClientRequest - Called before the request is sent to the cache. Modify the request or return a response to short-circuit.
2. onOriginRequest - Called before the request is sent to the origin, so only when the cache returns a MISS. Modify the request or return a response to short-circuit.
3. Origin fetch - The request is sent to your origin server.
4. onOriginResponse - Called after the origin responds. Modify the response before it’s sent to the client and cached.
5. onClientResponse - Called just before a response is sent to the client, unless you short-circuited at the onClientRequest layer.

Example

This example gates a route behind a feature flag and adds a custom header to responses:

import * as BunnySDK from "@bunny.net/edgescript-sdk";

BunnySDK.net.http
  .servePullZone({ url: "https://echo.free.beeceptor.com/" })
  .onOriginRequest((ctx) => {
    const optFT = ctx.request.headers.get("feature-flags");
    const featureFlags = optFT
      ? optFT.split(",").map((v) => v.trimStart())
      : [];

    // Route-based matching and feature flag check
    const path = new URL(ctx.request.url).pathname;
    if (path === "/d") {
      if (!featureFlags.includes("route-d-preview")) {
        // Short-circuit: return response without hitting origin
        return Promise.resolve(
          new Response("You cannot use this route.", { status: 400 }),
        );
      }
    }

    // Continue to origin with the request
    return Promise.resolve(ctx.request);
  })
  .onOriginResponse((ctx) => {
    // Add custom header to response
    ctx.response.headers.append("X-Via", "MyMiddleware");
    return Promise.resolve(ctx.response);
  });

Local development

You can run middleware scripts locally using Deno:

deno run -A script.ts

Test with curl:

# Blocked - missing required feature flag
curl http://127.0.0.1:8080/d --header 'feature-flags: something-else'

# Allowed - has required feature flag
curl http://127.0.0.1:8080/d --header 'feature-flags: route-d-preview, something-else'