@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/recipes/contact-form/tests/requests.json

@@ -0,0 +1,47 @@
+[
+  {
+    "path": "/contact",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"Ada\",\"email\":\"ada@example.com\",\"message\":\"Please send the brochure.\"}",
+    "status": 202,
+    "expectBody": "{\"accepted\":true}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/contact",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"\",\"email\":\"not-an-address\",\"message\":\"short\"}",
+    "status": 422,
+    "expectBody": "{\"accepted\":false,\"errors\":[\"name: 1-100 characters\",\"email: a valid address\",\"message: 10-4000 characters\"]}"
+  },
+  {
+    "path": "/contact",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "\"just a string\"",
+    "status": 422
+  },
+  {
+    "path": "/contact",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/x-www-form-urlencoded"
+    },
+    "body": "name=Ada",
+    "status": 415
+  },
+  {
+    "path": "/contact",
+    "status": 405
+  }
+]

package/recipes/contact-form/urlcode.yaml

@@ -0,0 +1,18 @@
+version: "1"
+routes:
+  /contact:
+    description: Validate a JSON contact message and notify an operator-granted hook after the response.
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 16384
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/contact.mjs
+    signals:
+      - url: https://hooks.example.com/contact
+    response:
+      headers:
+        Cache-Control: no-store

package/recipes/cors-api/README.md

@@ -0,0 +1,16 @@
+# CORS JSON API
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 1`.
+
+`/api/items` returns JSON from a sandboxed function. `middleware/cors.mjs` runs
+around it: it answers `OPTIONS` preflight itself with 204 and adds
+`Access-Control-Allow-Origin` to responses for origins in its allowlist. Other
+origins get `Vary: Origin` and no allow header, so browsers refuse them.
+
+Edit `allowedOrigins` in the middleware and the function body. The route must
+list `OPTIONS` in `methods`, or the runtime answers 405 before the middleware
+runs. CORS is not a host policy in this contract; middleware is the supported
+place for it, and it needs the sandbox, so serverless targets refuse this
+project. A browser-facing API that also needs credentials must add
+`Access-Control-Allow-Credentials` deliberately, never with a wildcard origin.

package/recipes/cors-api/functions/items.mjs

@@ -0,0 +1,3 @@
+export default function items() {
+  return Response.json({items: [{id: 1, name: 'first'}, {id: 2, name: 'second'}]});
+}

package/recipes/cors-api/middleware/cors.mjs

@@ -0,0 +1,21 @@
+// Edit this allowlist. The runtime has no CORS policy; middleware is the
+// supported place for it, and it runs only on routes that declare it.
+const allowedOrigins = ['https://app.example.com'];
+const allowMethods = 'GET, HEAD, OPTIONS';
+const allowHeaders = 'Content-Type';
+
+export default async function cors(request, context, next) {
+  const origin = request.headers.get('origin');
+  const allowed = origin !== null && allowedOrigins.includes(origin);
+  if (request.method === 'OPTIONS') {
+    // Preflight never reaches the handler. A disallowed origin gets no CORS
+    // headers, so the browser refuses the real request.
+    const headers = {Vary: 'Origin'};
+    if (allowed) Object.assign(headers, {'Access-Control-Allow-Origin': origin, 'Access-Control-Allow-Methods': allowMethods, 'Access-Control-Allow-Headers': allowHeaders, 'Access-Control-Max-Age': '600'});
+    return new Response(null, {status: 204, headers});
+  }
+  const response = await next();
+  response.headers.set('Vary', 'Origin');
+  if (allowed) response.headers.set('Access-Control-Allow-Origin', origin);
+  return response;
+}

package/recipes/cors-api/recipe.yaml

@@ -0,0 +1,26 @@
+id: cors-api
+description: JSON endpoint for one allowed browser origin; middleware answers preflight and adds CORS headers.
+tags: [cors, preflight, options, browser, origin, api, json, middleware, access-control, vary]
+complexity: intermediate
+capabilities: [enabled, function, methods, middleware, response.headers]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 1
+inputs:
+  - name: allowedOrigins
+    file: middleware/cors.mjs
+    description: The browser origins allowed to read the response.
+  - name: handler
+    file: functions/items.mjs
+    description: Replace the literal list with the real data.
+files: [urlcode.yaml, middleware/cors.mjs, functions/items.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 1
+behavior:
+  - OPTIONS /api/items from https://app.example.com answers 204 with Access-Control-Allow-Origin, -Methods and -Headers
+  - GET from the allowed origin carries Access-Control-Allow-Origin; other origins get Vary Origin and no allow header
+  - the route lists OPTIONS in methods, otherwise the runtime answers 405 before the middleware runs
+  - CORS is middleware, not a host policy, so the route needs the sandbox

package/recipes/cors-api/tests/requests.json

@@ -0,0 +1,65 @@
+[
+  {
+    "path": "/api/items",
+    "headers": {
+      "origin": "https://app.example.com"
+    },
+    "status": 200,
+    "expectBody": "{\"items\":[{\"id\":1,\"name\":\"first\"},{\"id\":2,\"name\":\"second\"}]}",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://app.example.com",
+      "vary": "Origin",
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/api/items",
+    "status": 200,
+    "expectBody": "{\"items\":[{\"id\":1,\"name\":\"first\"},{\"id\":2,\"name\":\"second\"}]}",
+    "expectHeaders": {
+      "vary": "Origin"
+    }
+  },
+  {
+    "path": "/api/items",
+    "method": "HEAD",
+    "headers": {
+      "origin": "https://app.example.com"
+    },
+    "status": 200,
+    "expectBody": "",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://app.example.com"
+    }
+  },
+  {
+    "path": "/api/items",
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://app.example.com",
+      "access-control-request-method": "GET"
+    },
+    "status": 204,
+    "expectBody": "",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://app.example.com",
+      "access-control-allow-methods": "GET, HEAD, OPTIONS",
+      "access-control-allow-headers": "Content-Type"
+    }
+  },
+  {
+    "path": "/api/items",
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://evil.example.net",
+      "access-control-request-method": "GET"
+    },
+    "status": 204,
+    "expectBody": ""
+  },
+  {
+    "path": "/api/items",
+    "method": "POST",
+    "status": 405
+  }
+]

package/recipes/cors-api/urlcode.yaml

@@ -0,0 +1,12 @@
+version: "1"
+routes:
+  /api/items:
+    description: JSON list callable from one allowed browser origin; middleware answers preflight and adds CORS headers.
+    methods: [GET, HEAD, OPTIONS]
+    middleware:
+      - source: middleware/cors.mjs
+    function:
+      source: functions/items.mjs
+    response:
+      headers:
+        Cache-Control: no-store

package/recipes/health-page/README.md

@@ -0,0 +1,13 @@
+# Health and status
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 2`.
+
+`/health` answers `ok` as text and `/status` answers a small JSON document. Both
+are native `respond` routes with `Cache-Control: no-store`, so no sandbox runs
+and every target supports them. Change `service` in `urlcode.yaml` to your
+service name.
+
+These routes report that the runtime is serving this revision; they do not
+check databases or upstreams, because native routes run no code. Operators who
+want process-level detail use the runtime's own metrics endpoint instead.

package/recipes/health-page/recipe.yaml

@@ -0,0 +1,23 @@
+id: health-page
+description: Plain-text liveness and JSON readiness answers served natively with no caching.
+tags: [health, status, readiness, liveness, uptime, probe, monitoring, respond, native, json]
+complexity: starter
+capabilities: [enabled, methods, respond, response.headers]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+routes: 2
+inputs:
+  - name: service
+    file: urlcode.yaml
+    description: The service name in the /status document.
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 2
+behavior:
+  - GET /health answers 200 "ok" with Cache-Control no-store
+  - GET /status answers 200 {"ok":true,"service":"example","schema":1}
+  - HEAD answers empty bodies; POST answers 405
+  - the routes report that this revision is serving; native routes check no upstream

package/recipes/health-page/tests/requests.json

@@ -0,0 +1,36 @@
+[
+  {
+    "path": "/health",
+    "status": 200,
+    "expectBody": "ok",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/health",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/status",
+    "status": 200,
+    "expectBody": "{\"ok\":true,\"service\":\"example\",\"schema\":1}",
+    "expectHeaders": {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/status",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/status",
+    "method": "POST",
+    "status": 405
+  }
+]

package/recipes/health-page/urlcode.yaml

@@ -0,0 +1,19 @@
+version: "1"
+routes:
+  /health:
+    description: Plain-text liveness answer for load balancers and uptime probes.
+    respond:
+      text: ok
+    response:
+      headers:
+        Cache-Control: no-store
+  /status:
+    description: JSON status document with the service name and a fixed schema version.
+    respond:
+      json:
+        ok: true
+        service: example
+        schema: 1
+    response:
+      headers:
+        Cache-Control: no-store

package/recipes/json-api/README.md

@@ -0,0 +1,6 @@
+# JSON echo API
+
+Run `urlcode validate --local --project .` and `urlcode serve --project .`.
+POST JSON with `Content-Type: application/json` to `/echo`. The sandbox returns
+`{"received": ...}`. Other methods are refused. Do not submit credentials to an
+echo endpoint. This recipe grants no network or filesystem access.

package/recipes/json-api/functions/echo.mjs

@@ -0,0 +1,3 @@
+export default async function echo(request) {
+  return Response.json({received: await request.json()});
+}

package/recipes/json-api/recipe.yaml

@@ -0,0 +1,25 @@
+id: json-api
+description: Bounded JSON request body echoed back by a sandboxed function.
+tags: [json, api, post, echo, function, body, validation, sandbox]
+complexity: starter
+capabilities: [enabled, function, methods, request.body]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 1
+inputs:
+  - name: handler
+    file: functions/echo.mjs
+    description: Replace the echo with the real response; the parsed body arrives through request.json().
+  - name: maxBytes
+    file: urlcode.yaml
+    description: The request body limit (16 KiB by default).
+files: [urlcode.yaml, functions/echo.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 1
+behavior:
+  - POST /echo with application/json answers 200 {"received":<body>}
+  - malformed JSON answers 400 and another content type 415 before the sandbox runs
+  - GET answers 405

package/recipes/json-api/tests/requests.json

@@ -0,0 +1,34 @@
+[
+  {
+    "path": "/echo",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"hello\":\"world\"}",
+    "status": 200,
+    "expectBody": "{\"received\":{\"hello\":\"world\"}}"
+  },
+  {
+    "path": "/echo",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{",
+    "status": 400
+  },
+  {
+    "path": "/echo",
+    "method": "POST",
+    "headers": {
+      "content-type": "text/plain"
+    },
+    "body": "hello",
+    "status": 415
+  },
+  {
+    "path": "/echo",
+    "status": 405
+  }
+]

package/recipes/json-api/urlcode.yaml

@@ -0,0 +1,12 @@
+version: "1"
+routes:
+  /echo:
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 16384
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/echo.mjs

package/recipes/middleware/README.md

@@ -0,0 +1,34 @@
+# Middleware patterns
+
+Fourteen reusable middleware modules on fifteen routes (`auth.mjs` serves two),
+covering what Express, Koa,
+Hono, Next.js and edge runtimes usually ship as middleware, rewritten for
+URLCode's small sandboxed guest API. Run `urlcode validate --local --project .`
+and `urlcode serve --project .`, then keep the routes you need and delete the
+rest; every module is independent.
+
+| Route | Module | Pattern |
+| --- | --- | --- |
+| `/api/private` | `middleware/auth.mjs` (`bearer`) | Bearer token with constant-time comparison |
+| `/admin/panel` | `middleware/auth.mjs` (`basic`) | HTTP Basic decoded in the guest |
+| `/cors/data` | `middleware/cors.mjs` | Origin allowlist and preflight |
+| `/traced` | `middleware/request-id.mjs` | Caller correlation id and Server-Timing |
+| `/maintenance` | `middleware/maintenance.mjs` | 503 kill switch with bypass header |
+| `/fragile` | `middleware/errors.mjs` | Error boundary returning JSON 500 |
+| `/api/items` | `middleware/envelope.mjs` | JSON response envelope |
+| `/negotiated` | `middleware/negotiate.mjs` | Accept negotiation, 406 otherwise |
+| `/resource` | `middleware/methods.mjs` | POST method override |
+| `/versioned` | `middleware/etag.mjs` | Weak ETag and 304 for function output |
+| `/experiment` | `middleware/bucket.mjs` | Sticky A/B cookie bucket |
+| `/welcome` | `middleware/locale.mjs` | Accept-Language redirect |
+| `/downloads/report` | `middleware/referer.mjs` | Referer allowlist on a download |
+| `/profile` | `middleware/body.mjs` | Body validation handed through `context.state` |
+| `/inspect` | `middleware/debug.mjs` | Redacted request echo for authoring |
+
+Tokens, passwords and switches are literal `env` values so the recipe runs
+without grants. Before deploying, move credentials to `{secret: name}` bindings
+with an operator grant, replace the example.com destinations, and delete the
+`/inspect` route or set `DEBUG` to `false`. The guest exposes no crypto, so none
+of these modules can verify signatures or hash passwords; treat them as request
+shaping, not as a security boundary. See the runtime's middleware documentation
+for the full list of guest limits.

package/recipes/middleware/functions/catalog.mjs

@@ -0,0 +1,3 @@
+export default function catalog() {
+  return Response.json({version: 3, items: ['alpha', 'beta']});
+}

package/recipes/middleware/functions/fail.mjs

@@ -0,0 +1,4 @@
+export default function fail(request, {args}) {
+  if (args.fail) throw new Error('simulated failure');
+  return Response.json({healthy: true});
+}

package/recipes/middleware/functions/items.mjs

@@ -0,0 +1,3 @@
+export default function items() {
+  return Response.json([{id: 1, name: 'first'}, {id: 2, name: 'second'}]);
+}

package/recipes/middleware/functions/profile.mjs

@@ -0,0 +1,3 @@
+export default function profile(request, {state}) {
+  return Response.json({welcome: state.body.name, age: state.body.age ?? null}, {status: 201});
+}

package/recipes/middleware/functions/resource.mjs

@@ -0,0 +1,3 @@
+export default function resource(request, {state}) {
+  return Response.json({method: state.method, tunneled: state.method !== request.method});
+}

package/recipes/middleware/functions/status.mjs

@@ -0,0 +1,3 @@
+export default function status() {
+  return Response.json({service: 'cookbook', state: 'ok'});
+}

package/recipes/middleware/middleware/auth.mjs

@@ -0,0 +1,48 @@
+// Authentication gates. Like Hono bearerAuth/basicAuth or express-basic-auth,
+// but the expected credential comes from the route's declared bindings.
+// The cookbook binds literal values; real projects use {secret: name} grants.
+
+// Compare without leaking where two strings differ through timing.
+function same(actual, expected) {
+  if (typeof actual !== 'string' || typeof expected !== 'string') return false;
+  const length = Math.max(actual.length, expected.length);
+  let mismatch = actual.length ^ expected.length;
+  for (let i = 0; i < length; i++) mismatch |= (actual.charCodeAt(i) || 0) ^ (expected.charCodeAt(i) || 0);
+  return mismatch === 0 && length > 0;
+}
+
+// The guest exposes no atob; a small decoder handles standard Basic credentials.
+const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+function decodeBase64(text) {
+  const clean = String(text).replace(/=+$/, '');
+  if (!/^[A-Za-z0-9+/]*$/.test(clean)) return null;
+  let bits = 0, buffer = 0, out = '';
+  for (const char of clean) {
+    buffer = (buffer << 6) | alphabet.indexOf(char); bits += 6;
+    if (bits >= 8) { bits -= 8; out += String.fromCharCode((buffer >> bits) & 0xff); }
+  }
+  return out;
+}
+
+export async function bearer(request, context, next) {
+  const header = request.headers.get('authorization') || '';
+  const token = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
+  if (!same(token, context.env.API_TOKEN)) {
+    return new Response('Unauthorized\n', {status: 401, headers: {'www-authenticate': 'Bearer realm="cookbook"', 'cache-control': 'no-store'}});
+  }
+  return next();
+}
+
+export async function basic(request, context, next) {
+  const header = request.headers.get('authorization') || '';
+  const decoded = header.startsWith('Basic ') ? decodeBase64(header.slice(6).trim()) : null;
+  const separator = decoded === null ? -1 : decoded.indexOf(':');
+  const user = separator < 0 ? '' : decoded.slice(0, separator), password = separator < 0 ? '' : decoded.slice(separator + 1);
+  // Evaluate both comparisons so a wrong user costs the same as a wrong password.
+  const userOk = same(user, context.env.ADMIN_USER), passwordOk = same(password, context.env.ADMIN_PASSWORD);
+  if (!(userOk && passwordOk)) {
+    return new Response('Unauthorized\n', {status: 401, headers: {'www-authenticate': 'Basic realm="cookbook", charset="UTF-8"', 'cache-control': 'no-store'}});
+  }
+  context.state.user = user;
+  return next();
+}

package/recipes/middleware/middleware/body.mjs

@@ -0,0 +1,15 @@
+// Validate a JSON body once and hand the parsed object to the handler through
+// context.state. Bodies are single-use, so downstream code must not read again.
+export default async function validateBody(request, context, next) {
+  const body = await request.json();
+  const errors = [];
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) errors.push('body must be an object');
+  else {
+    if (typeof body.name !== 'string' || body.name.length < 1 || body.name.length > 80) errors.push('name must be 1-80 characters');
+    if (body.age !== undefined && (!Number.isInteger(body.age) || body.age < 0 || body.age > 150)) errors.push('age must be an integer from 0 to 150');
+    for (const key of Object.keys(body)) if (!['name', 'age'].includes(key)) errors.push('unknown field ' + key);
+  }
+  if (errors.length) return Response.json({errors}, {status: 422});
+  context.state.body = body;
+  return next();
+}

package/recipes/middleware/middleware/bucket.mjs

@@ -0,0 +1,19 @@
+// Sticky A/B bucketing through a cookie, as on Vercel or Cloudflare edge examples.
+// Bucket b gets a different destination; everyone keeps their bucket for a week.
+function cookie(request, name) {
+  for (const part of (request.headers.get('cookie') || '').split(';')) {
+    const [key, ...rest] = part.trim().split('=');
+    if (key === name) return rest.join('=');
+  }
+  return null;
+}
+export default async function bucket(request, context, next) {
+  let assigned = cookie(request, 'bucket');
+  const fresh = assigned !== 'a' && assigned !== 'b';
+  if (fresh) assigned = Math.random() < 0.5 ? 'a' : 'b';
+  context.state.bucket = assigned;
+  const response = assigned === 'b' ? Response.redirect(context.env.VARIANT_URL, 302) : await next();
+  response.headers.set('vary', 'cookie');
+  if (fresh) response.headers.append('set-cookie', 'bucket=' + assigned + '; Path=/; Max-Age=604800; SameSite=Lax');
+  return response;
+}

package/recipes/middleware/middleware/cors.mjs

@@ -0,0 +1,21 @@
+// Cross-origin resource sharing with an origin allowlist, as in Express cors
+// or Hono cors. The route must declare OPTIONS in its methods for preflight.
+const preflightHeaders = {
+  'access-control-allow-methods': 'GET, HEAD, OPTIONS',
+  'access-control-allow-headers': 'Content-Type, Authorization',
+  'access-control-max-age': '600'
+};
+export default async function cors(request, context, next) {
+  const allowed = (context.env.ALLOWED_ORIGINS || '').split(/\s+/).filter(Boolean);
+  const origin = request.headers.get('origin');
+  const permitted = origin !== null && allowed.includes(origin);
+  if (request.method === 'OPTIONS') {
+    // Preflight never reaches the handler. Unknown origins get no allow headers.
+    const headers = {vary: 'origin', ...(permitted ? {...preflightHeaders, 'access-control-allow-origin': origin} : {})};
+    return new Response(null, {status: 204, headers});
+  }
+  const response = await next();
+  response.headers.set('vary', 'origin');
+  if (permitted) response.headers.set('access-control-allow-origin', origin);
+  return response;
+}

package/recipes/middleware/middleware/debug.mjs

@@ -0,0 +1,13 @@
+// Authoring aid: with DEBUG on and X-Debug: 1, describe what the guest received.
+// Secrets and credential-bearing headers are never echoed.
+const hidden = ['authorization', 'cookie', 'proxy-authorization'];
+export default async function debug(request, context, next) {
+  if (context.env.DEBUG !== 'true' || request.headers.get('x-debug') !== '1') return next();
+  const headers = {};
+  for (const [name, value] of request.headers) headers[name] = hidden.includes(name) ? '[redacted]' : value;
+  return Response.json({
+    method: request.method, url: request.url, headers,
+    inputs: context.inputs, args: context.args ?? null,
+    env: Object.keys(context.env), secrets: Object.keys(context.secrets)
+  }, {headers: {'cache-control': 'no-store'}});
+}

package/recipes/middleware/middleware/envelope.mjs

@@ -0,0 +1,11 @@
+// Wrap successful JSON function responses in a stable envelope. Native bodies are
+// opaque and pass through untouched; only readable JSON is rewritten.
+export default async function envelope(request, context, next) {
+  const response = await next();
+  if (!response.ok || !(response.headers.get('content-type') || '').startsWith('application/json')) return response;
+  let data;
+  try { data = await response.json(); } catch { return response; }
+  const path = request.url.replace(/^[a-z]+:\/\/[^/]+/i, '').split('?')[0];
+  const meta = {route: path, count: Array.isArray(data) ? data.length : 1};
+  return Response.json({ok: true, data, meta}, {status: response.status, headers: response.headers});
+}

package/recipes/middleware/middleware/errors.mjs

@@ -0,0 +1,11 @@
+// Error boundary. Without it, a throwing function is a bare 502 from the runtime.
+// Nothing about the thrown error reaches the client; the guest console is silent,
+// so the correlation id is what an operator can search for.
+export default async function errorBoundary(request, context, next) {
+  try {
+    return await next();
+  } catch {
+    return Response.json({error: 'Temporarily unavailable', correlationId: context.state.correlationId ?? null},
+      {status: 500, headers: {'cache-control': 'no-store'}});
+  }
+}

package/recipes/middleware/middleware/etag.mjs

@@ -0,0 +1,18 @@
+// Conditional requests for function output: a weak ETag from a cheap FNV-1a
+// hash, plus 304 when the client already holds that version. Native static
+// and download routes already do this in the runtime; this is for JSON.
+function fnv1a(text) {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) { hash ^= text.charCodeAt(i); hash = Math.imul(hash, 0x01000193) >>> 0; }
+  return hash.toString(16).padStart(8, '0');
+}
+export default async function etag(request, context, next) {
+  const response = await next();
+  if (!response.ok || request.method !== 'GET' && request.method !== 'HEAD') return response;
+  const body = await response.text();
+  const tag = 'W/"' + fnv1a(body) + '"';
+  const headers = {...Object.fromEntries(response.headers), etag: tag, 'cache-control': 'public, max-age=60'};
+  const held = (request.headers.get('if-none-match') || '').split(',').map(s => s.trim());
+  if (held.includes(tag) || held.includes('*')) return new Response(null, {status: 304, headers: {etag: tag, 'cache-control': headers['cache-control']}});
+  return new Response(body, {status: response.status, headers});
+}