Module 14 — Edge Runtime Ingestion & V8 Isolates

Cloudflare Queues gives the edge proxy a durable buffer to fall back to: instead of forwarding directly and hoping, the Worker writes to a queue, and a separate consumer Worker drains it with retries and backoff, moving anything that keeps failing to a dead-letter queue for manual replay.

export default {
  async fetch(request, env, ctx) {
    // ... validation and rate limiting as before ...
 
    const body = await request.arrayBuffer();
 
    try {
      // Try the fast path: forward directly to origin
      const response = await fetch(env.ORIGIN_URL + '/api/v1/ingest', {
        method: 'POST',
        body,
        headers: { Authorization: `Bearer ${env.ORIGIN_TOKEN}` },
      });
      if (!response.ok) throw new Error(`Origin returned ${response.status}`);
    } catch (err) {
      // Fast path failed — buffer it instead of dropping the transaction
      await env.INGEST_QUEUE.send({
        body: Array.from(new Uint8Array(body)),  // queue messages must be JSON-serializable
        attempt: 1,
        failedAt: Date.now(),
      });
    }
 
    return new Response(JSON.stringify({ status: 'accepted' }), {
      status: 202,
      headers: { 'Content-Type': 'application/json' },
    });
  },
 
  // Consumer Worker: drains the queue with retry + dead-letter handling
  async queue(batch, env) {
    for (const message of batch.messages) {
      try {
        const bytes = new Uint8Array(message.body.body);
        const response = await fetch(env.ORIGIN_URL + '/api/v1/ingest', {
          method: 'POST',
          body: bytes,
          headers: { Authorization: `Bearer ${env.ORIGIN_TOKEN}` },
        });
        if (!response.ok) throw new Error(`Origin returned ${response.status}`);
        message.ack();
      } catch (err) {
        if (message.body.attempt >= 5) {
          // Exhausted retries — route to the dead-letter queue instead of losing it
          await env.INGEST_DLQ.send({ ...message.body, finalError: err.message });
          message.ack();  // remove from the retry queue; it now lives in the DLQ
        } else {
          message.retry();  // Cloudflare Queues re-delivers with configured backoff
        }
      }
    }
  },
};

# wrangler.toml — queue bindings
[[queues.producers]]
queue = "ingest-buffer"
binding = "INGEST_QUEUE"
 
[[queues.consumers]]
queue = "ingest-buffer"
max_retries = 5
dead_letter_queue = "ingest-dlq"

The origin cluster being briefly unreachable no longer means dropped transactions — it means a short delay while the queue drains, with a dead-letter queue as the backstop for whatever still fails after retries.

---

Durable Objects: Stateful Edge

Cloudflare Durable Objects provide consistent, stateful coordination at the edge — one JavaScript object with persistent storage, accessible from anywhere globally, guaranteed to run in exactly one location.

// Rate limiter Durable Object
export class RateLimiter {
  #state;
  #requests = new Map();  // In-memory state persists within the DO lifetime
 
  constructor(state) {
    this.#state = state;
  }
 
  async fetch(request) {
    const key = new URL(request.url).searchParams.get('key');
    const now = Date.now();
    const window = 60_000;  // 1 minute
    const limit = 1_000;    // 1K requests per minute
 
    // Clean up old entries
    const entry = this.#requests.get(key) ?? { count: 0, resetAt: now + window };
    if (now > entry.resetAt) {
      entry.count = 0;
      entry.resetAt = now + window;
    }
 
    entry.count++;
    this.#requests.set(key, entry);
 
    if (entry.count > limit) {
      return new Response('Rate limit exceeded', { status: 429 });
    }
    return new Response('OK', { status: 200 });
  }
}

Because a Durable Object runs in exactly one location, it provides strong consistency — unlike KV which is eventually consistent. For rate limiting where you need exact counts (not approximate), Durable Objects are the correct tool.

The KV Consistency Gap

The intake proxy example earlier in this module used a KV lookup for API key validation — reasonable for that use case, since a stale "yes this key is valid" for a few extra seconds is low-risk. It stops being reasonable the moment KV is used for anything where the count matters, like rate limiting: Cloudflare KV writes are globally consistent within seconds in the common case, but the documented worst case is up to 60 seconds of propagation delay across PoPs. A value written at one edge location is not guaranteed to be visible at another for up to a minute.

Production story: An early version of a rate limiter for the UPI payment intake proxy was built directly on KV — increment a per-key counter on each request, reject once it crossed the threshold. During a festival traffic spike, requests for the same API key landed at PoPs in different regions simultaneously. Each PoP read its own (stale) view of the counter from KV, saw it under the limit, and allowed the request through — because the increments from other PoPs hadn't propagated yet. A burst of duplicate and over-limit requests slipped past the rate limiter globally, all technically "under the limit" from each PoP's local, stale perspective. The fix was moving the counter into a Durable Object keyed by API key: every request for that key is routed to the single Durable Object instance responsible for it, so the counter is read and incremented in one consistent place with no propagation delay to race against — exactly the trade-off called out above (KV for cheap, tolerant-of-staleness lookups; Durable Objects for anything needing an exact count).

---

Vercel Edge Runtime: Next.js Integration

Vercel's Edge Runtime is optimized for Next.js middleware and API routes. Same V8 isolate model, same Web Standards API surface, same constraints.

// app/api/validate-transaction/route.ts
export const runtime = 'edge';  // opt into Edge Runtime
 
export async function POST(request: Request) {
  const body = await request.json();
 
  // Web Crypto API — available in edge runtime
  const encoder = new TextEncoder();
  const data = encoder.encode(JSON.stringify(body));
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  const hash = Buffer.from(hashBuffer).toString('hex');
 
  // Validate basic structure
  if (!body.hash || !body.sender || !body.amount) {
    return Response.json({ error: 'Missing required fields' }, { status: 400 });
  }
 
  // Forward to main API
  const response = await fetch(process.env.API_URL + '/ingest', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Request-Hash': hash,
      'X-Edge-Validated': '1',
    },
    body: JSON.stringify(body),
  });
 
  return Response.json(await response.json(), { status: response.status });
}

Edge Runtime restrictions in Next.js:

// ✅ Works in Edge Runtime:
import { NextRequest } from 'next/server';
import { cookies } from 'next/headers';
// Web APIs: fetch, Request, Response, URL, Headers
// Web Crypto: crypto.subtle.*
// Encoding: TextEncoder, TextDecoder
 
// ❌ Does NOT work in Edge Runtime:
import pg from 'pg';                    // requires net module
import fs from 'fs';                    // no filesystem
import { createServer } from 'net';     // no TCP sockets
import { execSync } from 'child_process';  // no child processes

---

Deno Deploy: The Third Edge Platform

Deno Deploy runs on the same fundamental model as Cloudflare Workers and Vercel Edge Runtime — V8 isolates distributed across edge locations, Web Standards APIs (fetch, Request, Response, crypto.subtle) as the primary surface. Where it diverges is in how much of the standard runtime it exposes: Deno Deploy supports a substantial subset of the Deno runtime itself, including native Deno.KV (a globally-replicated key-value store built on FoundationDB, philosophically similar to Cloudflare KV — same eventual-consistency trade-offs apply) and first-class TypeScript execution with no separate build/transpile step.

// A Deno Deploy handler for blockchain intake validation
// Deno Deploy uses the same `fetch`-handler shape the other platforms do
Deno.serve(async (request: Request) => {
  const url = new URL(request.url);
 
  if (request.method !== 'POST' || url.pathname !== '/api/v1/ingest') {
    return new Response('Not found', { status: 404 });
  }
 
  const apiKey = request.headers.get('X-API-Key');
 
  // Deno.openKv() — Deno Deploy's globally-distributed KV store
  const kv = await Deno.openKv();
  const { value: validKey } = await kv.get(['api_keys', apiKey ?? '']);
  if (!validKey) {
    return new Response('Unauthorized', { status: 401 });
  }
 
  const bodyBytes = await request.arrayBuffer();
 
  // Same Web Crypto surface as Cloudflare Workers and Vercel Edge Runtime
  const hash = await crypto.subtle.digest('SHA-256', bodyBytes);
 
  const response = await fetch(`${Deno.env.get('ORIGIN_URL')}/api/v1/ingest`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/octet-stream' },
    body: bodyBytes,
  });
 
  return new Response(JSON.stringify({ status: 'accepted' }), {
    status: 202,
    headers: { 'Content-Type': 'application/json' },
  });
});

The practical decision between the three platforms rarely comes down to raw isolate performance — they're architecturally close enough that it's a wash for most workloads. It comes down to ecosystem fit: Cloudflare Workers if you're already on Cloudflare's network (Queues, Durable Objects, R2) or need the largest edge footprint; Vercel Edge Runtime if the intake proxy is a thin layer in front of a Next.js application and you want middleware and API routes in the same deploy; Deno Deploy if native TypeScript execution and Deno.KV fit the rest of your stack better, or you want to avoid Cloudflare-specific bindings entirely. Every constraint covered in this module — no fs/net/child_process, per-request CPU and memory ceilings, no reliable module-level shared state, KV eventual consistency — applies to all three; only the binding names and specific limits change.

---

Web Crypto API: Edge-Safe Cryptography

Edge runtimes provide the Web Crypto API as a substitute for Node.js crypto. It covers most use cases:

// HMAC verification (for webhook signatures)
async function verifyWebhookSignature(body, signature, secret) {
  const key = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify']
  );
 
  const signatureBytes = hexToBytes(signature);
  const bodyBytes = new TextEncoder().encode(body);
 
  return crypto.subtle.verify('HMAC', key, signatureBytes, bodyBytes);
}
 
// SHA-256 hashing
async function hashPayload(data) {
  const bytes = new TextEncoder().encode(data);
  const hashBuffer = await crypto.subtle.digest('SHA-256', bytes);
  return Array.from(new Uint8Array(hashBuffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}
 
// Random bytes (for request IDs)
const requestId = crypto.randomUUID();  // available in all modern edge runtimes

What Web Crypto cannot do (use a native addon in Node.js instead):

• Secp256k1 signature verification (used by Ethereum/Bitcoin) — still not part of the Web Crypto standard, and not supported by any major edge runtime natively
• Custom, non-standard elliptic curve operations outside what the platform ships

Ed25519 is no longer a clean "unavailable" case. Earlier guidance (including older versions of this module) flagged Ed25519 as requiring the same WASM workaround as secp256k1 — that's now outdated. Ed25519 support has been landing across modern JavaScript runtimes, including Cloudflare Workers' crypto.subtle, and Node.js itself has supported it natively for several major versions. Don't assume either way — check the current support matrix for your specific edge platform and target Node version before committing to a WASM library purely for Ed25519; it may no longer be necessary. Secp256k1 remains the one that reliably requires a WASM or native fallback everywhere.

For secp256k1 and any other cryptography genuinely missing from the platform, use a WASM build of a cryptographic library.

---

When NOT to Use Edge Runtime

Edge is not a universal upgrade. These workloads belong on your main Node.js cluster:

Stateful streaming: WebSocket connections that maintain subscription state for hours. Edge runtimes have strict CPU and memory limits per request — but those limits vary sharply by plan: Cloudflare Workers' free tier caps CPU time around 10ms per request (documented as "up to 30ms" in older material, but the free-tier default is tighter), while paid plans raise that ceiling to up to 30 seconds of CPU time per request (memory stays capped around 128MB regardless of plan). The free-tier figure is not a hard architectural ceiling of the isolate model — it's a billing-tier default. Either way, a WebSocket handler holding state for hours cannot run on an isolate: even the 30s paid-plan CPU allowance is wall-clock CPU time for a single request, not a budget for a connection that stays open indefinitely.

Database connections: pg requires raw TCP sockets. Connection pooling requires persistent state. Neither is available at the edge. Use edge as a proxy, never as a database client.

Heavy computation: Isolates have strict CPU time limits (10ms–30ms per request on free plans, up to 30s on paid). Merkle proof verification, batch signature verification, large JSON parsing — these belong on your cluster.

Anything that needs the full Node.js API: native addons, fs, child_process, net, existing npm packages that use these. If it doesn't work in a browser, it probably doesn't work at the edge.

// The architectural decision:
// Edge = thin validation + routing + auth + rate limiting
// Cluster = business logic + state + cryptography + databases
 
// Edge worker: <50ms, <128MB, Web Standards only
// Does: auth, rate limit, geo-route, basic validation
// Returns: 202 Accepted (fast), forwards to cluster
 
// Cluster worker: unlimited time, full Node.js, database connections
// Does: signature verify, DB write, event publish, WebSocket notify
// Returns: final status after all processing

---

Production Incident: Edge Function Leaking Response Body

Context: A Cloudflare Worker processing incoming blockchain event webhooks. The Worker validated the request and forwarded to the origin cluster.

What happened:

// Broken: response body consumed twice
export default async function handler(request, env) {
  const body = await request.json();  // ← consumes the request body stream
 
  const isValid = validateWebhook(body);
  if (!isValid) return new Response('Invalid', { status: 400 });
 
  // Forward original request to origin
  return fetch(env.ORIGIN_URL, {
    method: 'POST',
    body: request.body,  // ← request.body is already consumed! null stream
    headers: request.headers,
  });
}
// Result: origin receives empty body → 400 error from origin
// The Worker returns a 400 to the blockchain node → node retries → origin flooded

The fix:

export default async function handler(request, env) {
  // Read body ONCE, use it for both validation and forwarding
  const bodyBytes = await request.arrayBuffer();
  const body = JSON.parse(new TextDecoder().decode(bodyBytes));
 
  const isValid = validateWebhook(body);
  if (!isValid) return new Response('Invalid', { status: 400 });
 
  // Forward the original bytes — not re-parsed/re-serialized
  return fetch(env.ORIGIN_URL, {
    method: 'POST',
    body: bodyBytes,           // ← use the ArrayBuffer, not request.body
    headers: request.headers,
  });
}

The rule: a Request body is a readable stream — it can only be consumed once. If you need to read it AND forward it, read it into an ArrayBuffer first.

---

Summary

---

Edge handles the perimeter. Module 15 covers what happens when the perimeter is attacked — ReDoS, memory exhaustion, cascade failures, and the runbooks that keep your service alive when everything is going wrong.

Next: Module 15 — Resiliency Runbooks & High-Load Security Defenses →

---