Edge Cache

Fetch external URLs through the Workers Cache API and report whether each response was served from cache, fetched from origin, or bypassed.

API ReferenceCopy Anchor Link

GET /fetchCopy Anchor Link

Fetches a URL and returns cache metadata without streaming the full response body back to the client.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/fetch?url=https://www.cloudflare.com"

Success ResponseCopy Anchor Link

url string

The normalized URL that was fetched

cacheStatus string

One of "HIT", "MISS", or "BYPASS"

statusCode number

HTTP status code from the cached or origin response

contentType string | null

Response Content-Type header, if present

bodySize number

Response body size in bytes

{
  "url": "https://www.cloudflare.com/",
  "cacheStatus": "MISS",
  "statusCode": 200,
  "contentType": "text/html; charset=utf-8",
  "bodySize": 125678
}

Error ResponseCopy Anchor Link

{
  "error": "Missing or invalid query parameter: url",
  "code": "INVALID_URL"
}

Error CodesCopy Anchor Link

• 400 - Missing or invalid url parameter (not http/https)
• 502 - Upstream fetch failed (FETCH_ERROR)

Use CasesCopy Anchor Link

• Learn how to use caches.default in Workers
• Cache expensive origin fetches at the edge
• Compare cache hit vs miss behavior during development
• Build read-through cache patterns for APIs and static content

LimitationsCopy Anchor Link

• Uses the default cache with no custom TTL or cache-key logic in this demo
• Cache is per-colo; entries are not globally consistent
• Only caches successful GET fetch responses for the requested URL

Use in your projectCopy Anchor Link

import { CACHE_MAX_AGE_SECONDS } from "../constants/defaults";import type { FetchResponse } from "../types/fetch";type CachedFetchOptions = {  url: string;  cache: Cache;  bypass: boolean;};export async function fetchWithEdgeCache(options: CachedFetchOptions): Promise<FetchResponse> {  const { url, cache, bypass } = options;  const cacheRequest = new Request(url, { method: "GET" });  if (!bypass) {    const cached = await cache.match(cacheRequest);    if (cached) {      const body = await cached.arrayBuffer();      return {        url,        cacheStatus: "HIT",        statusCode: cached.status,        contentType: cached.headers.get("content-type"),        bodySize: body.byteLength,      };    }  }  const response = await fetch(url);  const body = await response.arrayBuffer();  const contentType = response.headers.get("content-type");  if (!bypass && response.ok) {    const toCache = new Response(body, {      status: response.status,      headers: {        "content-type": contentType ?? "application/octet-stream",        "cache-control": `public, max-age=${CACHE_MAX_AGE_SECONDS}`,      },    });    await cache.put(cacheRequest, toCache);  }  return {    url,    cacheStatus: bypass ? "BYPASS" : "MISS",    statusCode: response.status,    contentType,    bodySize: body.byteLength,  };}

DeploymentCopy Anchor Link

curl "https://your-worker.workers.dev/fetch?url=https://www.cloudflare.com"

Local DevelopmentCopy Anchor Link

cd apps/experiments/edge-cache
npm install
npm run dev

Test locally:

curl "http://localhost:8787/fetch?url=https://www.cloudflare.com"

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Cache API - Edge response caching via caches.default
• Fetch API - Origin requests from Workers