Living Document Notice
Published 2026-09-12. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Mastering Edge Cache Headers

Summary

Serving dynamic content from constrained origin servers without edge caching guarantees collapse under unexpected traffic spikes. However, aggressive browser caching causes users to view stale revisions long after edits are committed, while disabling caching altogether floods the origin node with identical database requests. Balancing fresh updates with origin survivability requires a deliberate edge caching strategy.

Harbor controls edge behavior by combining three standard HTTP directives: public, max-age=0, s-maxage=60, stale-while-revalidate=300. This header structure instructs client web browsers to validate every request against the network, directs edge CDNs (such as Cloudflare or Fastly) to serve cached responses for 60 seconds, and permits edge nodes to serve stale content for up to 300 seconds while asynchronously revalidating from the origin in the background.

The Anatomy of Origin-Shielding Directives

When configuring HTTP caching for dynamically generated documents, conflating client-side caching with edge CDN proxy caching creates operational incidents. By separating client instructions (max-age) from proxy instructions (s-maxage), the origin maintains control over distribution.

Client Browser               Edge CDN (Cloudflare)                  Harbor Origin
     ?                                ?                                    ?
     ? GET /posts/example             ?                                    ?
     ??????????????????????????????????                                    ?
     ?                                ? Cache hit (age < 60s)              ?
     ?????????????????????????????????? (Returns HTTP 200 via edge cache)  ?
     ?                                ?                                    ?
     ? GET /posts/example (age = 80s) ?                                    ?
     ??????????????????????????????????                                    ?
     ?                                ? Age between 60s and 360s:          ?
     ?????????????????????????????????? Serves stale cached HTML           ?
     ?                                ?                                    ?
     ?                                ? Background async origin fetch:     ?
     ?                                ??????????????????????????????????????
     ?                                ??????????????????????????????????????
     ?                                ? Updates edge cache buffer          ?

Directive Breakdown

1. public: Declares that any intermediate cache, proxy, or CDN is permitted to store the response body.
2. max-age=0: Instructs the end-user's web browser not to store the response in its local disk cache without revalidation. When the user navigates between pages or refreshes, the browser initiates a network fetch to the CDN rather than rendering stale local HTML.
3. s-maxage=60: Overrides max-age exclusively for shared caches (CDNs and reverse proxies). The CDN serves requests directly from edge memory for 60 seconds. Inbound traffic of 10,000 requests per minute results in only one request reaching the origin every 60 seconds.
4. stale-while-revalidate=300: Defines a 300-second grace window after s-maxage expires. The first visitor whose request arrives during this window receives the cached response immediately (< 15ms), while the CDN initiates a non-blocking background fetch to Harbor to refresh its cache.

Implementing the Header Policy in Hono

Harbor applies cache headers via scoped middleware based on document mutability.

import { Hono } from "hono";

const app = new Hono();

// Immutable static assets: 1 year client + edge cache
app.use("/assets/*", async (c, next) => {
  await next();
  c.header("Cache-Control", "public, max-age=31536000, immutable");
});

// Dynamic content routes: strict CDN shielding with background revalidation
app.use("/posts/*", async (c, next) => {
  await next();
  if (c.res.status === 200) {
    c.header(
      "Cache-Control",
      "public, max-age=0, s-maxage=60, stale-while-revalidate=300"
    );
    // Cloudflare specific tags for granular purging
    c.header("Cache-Tag", `post-${c.req.param("slug") || "all"}`);
  }
});

app.get("/posts/:slug", (c) => {
  return c.html(`<h1>Rendered Content for ${c.req.param("slug")}</h1>`);
});

export default app;

Cloudflare Cache Rule and Origin Bypass Protection

To prevent requests from evading the edge cache via query string variation, configure Cloudflare Cache Rules to ignore non-essential tracking parameters.

{
  "description": "Harbor Dynamic Edge Shield",
  "expression": "(http.host eq \"bosunpkm.com\" and starts_with(http.request.uri.path, \"/posts/\"))",
  "action": "set_cache_settings",
  "action_parameters": {
    "cache": true,
    "edge_ttl": {
      "mode": "respect_origin"
    },
    "browser_ttl": {
      "mode": "respect_origin"
    },
    "serve_stale": {
      "disable_stale_while_updating": false
    },
    "query_string_sort": true
  }
}

Command-Line Verification and Header Inspection

Verify edge cache hit statuses and header delivery using curl:

# First request: expect MISS or EXPIRED from CDN edge
curl -s -D - -o /dev/null https://bosunpkm.com/posts/mastering-edge-cache-headers | grep -E "(HTTP|cache-control|cf-cache-status|age)"

# Second request within 60s: expect HIT with non-zero Age
curl -s -D - -o /dev/null https://bosunpkm.com/posts/mastering-edge-cache-headers | grep -E "(HTTP|cache-control|cf-cache-status|age)"

# Inspect raw origin response bypassing Cloudflare
curl -s -D - -o /dev/null -H "Host: bosunpkm.com" http://127.0.0.1:3000/posts/mastering-edge-cache-headers | grep -i "cache-control"