Adopting worldmonitor at the Edge: Three CORS Layers, One KV Hedge, and a Bundle You Cannot Import

import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

type Bindings = {
  BOOTSTRAP_KV: KVNamespace;
  BOOTSTRAP_KV_SERVE: 'off' | 'slow' | 'all';
  ORIGIN: string;
};

const TIERS = ['fast', 'slow'] as const;
type Tier = (typeof TIERS)[number];

const MAX_AGE_MS = { fast: 15 * 60_000, slow: 60 * 60_000 } as const;
const CACHE_TTL_S = { fast: 60, slow: 300 } as const;
const HEDGE_MS = 500;

const Envelope = z.object({
  schemaVersion: z.literal(1),
  tier: z.enum(TIERS),
  generatedAt: z.number().int().positive(),
  payload: z.object({ data: z.record(z.unknown()), missing: z.array(z.string()) }),
});

async function readTier(env: Bindings, tier: Tier) {
  let raw: string | null;
  try {
    raw = await env.BOOTSTRAP_KV.get(tier, { type: 'text', cacheTtl: CACHE_TTL_S[tier] });
  } catch {
    return { ok: false as const, reason: 'kv_error' };
  }
  if (raw === null) return { ok: false as const, reason: 'miss' };

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return { ok: false as const, reason: 'invalid' };
  }

  const envelope = Envelope.safeParse(parsed);
  if (!envelope.success) return { ok: false as const, reason: 'invalid' };
  if (Date.now() - envelope.data.generatedAt > MAX_AGE_MS[tier]) {
    return { ok: false as const, reason: 'stale' };
  }
  return { ok: true as const, body: JSON.stringify(envelope.data.payload) };
}

function hedge(ms: number) {
  let id: ReturnType<typeof setTimeout> | undefined;
  const promise = new Promise<{ kind: 'hedge' }>((resolve) => {
    id = setTimeout(() => resolve({ kind: 'hedge' }), ms);
  });
  return { promise, cancel: () => clearTimeout(id) };
}

const app = new Hono<{ Bindings: Bindings }>();

const query = z.object({ public: z.literal('1'), tier: z.enum(TIERS) });

app.get(
  '/api/bootstrap',
  zValidator('query', query, (result, c) => {
    if (!result.success) {
      return c.json({ error: 'invalid_query', issues: result.error.issues }, 400);
    }
  }),
  async (c) => {
    const { tier } = c.req.valid('query');
    const env = c.env;
    const origin = () =>
      fetch(`${env.ORIGIN}/api/bootstrap?public=1&tier=${tier}`);

    const serving =
      env.BOOTSTRAP_KV_SERVE === 'all' ||
      (env.BOOTSTRAP_KV_SERVE === 'slow' && tier === 'slow');
    if (!serving) return passThrough(await origin(), 'origin');

    const kv = readTier(env, tier).then((r) => ({ kind: 'kv' as const, ...r }));
    const timer = hedge(HEDGE_MS);
    const first = await Promise.race([kv, timer.promise]);
    timer.cancel();

    if (first.kind === 'kv' && first.ok) return serve(first.body, tier);

    const pending = origin().then((resp) => ({ kind: 'origin' as const, resp }));
    const settled = first.kind === 'kv' ? await pending : await Promise.race([kv, pending]);
    if (settled.kind === 'kv' && settled.ok) return serve(settled.body, tier);

    const resp = settled.kind === 'origin' ? settled.resp : (await pending).resp;
    return passThrough(resp, 'origin');
  },
);

function serve(body: string, tier: Tier) {
  return new Response(body, {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Cache-Control': 'no-store',
      'X-Bootstrap-Source': 'kv',
      'X-Bootstrap-Tier': tier,
    },
  });
}

function passThrough(resp: Response, source: 'origin') {
  const headers = new Headers(resp.headers);
  headers.set('X-Bootstrap-Source', source);
  return new Response(resp.body, { status: resp.status, headers });
}

export default app;

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "bootstrap-edge",
  "main": "src/index.ts",
  "compatibility_date": "2025-05-01",

  // No nodejs_compat. The router and KV path touch Web APIs only. Enabling it
  // doubles cold-start payload to support imports this Worker must never make.

  "routes": [
    { "pattern": "api.example.com/api/bootstrap", "zone_name": "example.com" }
  ],

  // Without a route the Worker uploads and receives no traffic. This is the
  // load-bearing line, not the binding.
  "kv_namespaces": [
    { "binding": "BOOTSTRAP_KV", "id": "<your-kv-namespace-id>" }
  ],

  "vars": {
    "BOOTSTRAP_KV_SERVE": "slow",
    "ORIGIN": "https://origin.internal"
  },

  // Secrets stay out of this file: wrangler secret put AXIOM_TOKEN
  "observability": { "enabled": true },
  "placement": { "mode": "smart" }
}