@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

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});
+}

package/recipes/middleware/middleware/locale.mjs

@@ -0,0 +1,20 @@
+// Language redirect from Accept-Language, like Next.js i18n middleware. Only
+// languages listed in LOCALES are chosen; the native redirect is the default.
+// `Response.redirect()`'s headers are immutable (a trusted route's real
+// `Response` enforces the Fetch standard here, unlike the sandbox's guest
+// API), so that branch builds its own `Response` with headers up front.
+export default async function locale(request, context, next) {
+  const supported = (context.env.LOCALES || '').split(/\s+/).filter(Boolean);
+  const ranked = (request.headers.get('accept-language') || '').split(',').map((part, index) => {
+    const [tag, ...params] = part.trim().split(';');
+    const q = params.map(p => p.trim()).find(p => p.startsWith('q='));
+    return {lang: tag.trim().toLowerCase().split('-')[0], q: q ? Number(q.slice(2)) || 0 : 1, index};
+  }).filter(p => p.q > 0).sort((a, b) => b.q - a.q || a.index - b.index);
+  const chosen = ranked.find(p => supported.includes(p.lang))?.lang;
+  if (chosen && chosen !== supported[0]) {
+    return new Response(null, { status: 302, headers: { location: context.env.SITE + '/' + chosen + '/welcome', vary: 'accept-language' } });
+  }
+  const response = await next();
+  response.headers.set('vary', 'accept-language');
+  return response;
+}

package/recipes/middleware/middleware/maintenance.mjs

@@ -0,0 +1,10 @@
+// A kill switch: return 503 while MAINTENANCE is on, unless the caller presents
+// the bypass token. Flip the binding and restart; no code change is needed.
+export default async function maintenance(request, context, next) {
+  const active = context.env.MAINTENANCE === 'true';
+  const bypass = context.env.MAINTENANCE_BYPASS;
+  if (active && !(bypass && request.headers.get('x-maintenance-bypass') === bypass)) {
+    return new Response('Down for maintenance\n', {status: 503, headers: {'retry-after': '120', 'cache-control': 'no-store'}});
+  }
+  return next();
+}

package/recipes/middleware/middleware/methods.mjs

@@ -0,0 +1,15 @@
+// Method override for clients that can only send POST (Express method-override).
+// The route still declares every real method; only a bounded set may be tunneled.
+const tunnelable = ['PUT', 'PATCH', 'DELETE'];
+export async function override(request, context, next) {
+  const requested = (request.headers.get('x-http-method-override') || '').toUpperCase();
+  if (request.method === 'POST' && requested) {
+    if (!tunnelable.includes(requested)) {
+      return new Response('Method override not allowed\n', {status: 405, headers: {allow: tunnelable.join(', ')}});
+    }
+    context.state.method = requested;
+  } else {
+    context.state.method = request.method;
+  }
+  return next();
+}

package/recipes/middleware/middleware/negotiate.mjs

@@ -0,0 +1,20 @@
+// Content negotiation in the spirit of Express res.format. The handler always
+// produces JSON; this converts it to plain text when the client prefers that.
+function preferences(accept) {
+  return (accept || '*/*').split(',').map((part, index) => {
+    const [type, ...params] = part.trim().split(';');
+    const q = params.map(p => p.trim()).find(p => p.startsWith('q='));
+    return {type: type.trim().toLowerCase(), q: q ? Number(q.slice(2)) || 0 : 1, index};
+  }).filter(p => p.q > 0).sort((a, b) => b.q - a.q || a.index - b.index);
+}
+export default async function negotiate(request, context, next) {
+  const ranked = preferences(request.headers.get('accept'));
+  const choice = ranked.find(p => ['application/json', 'text/plain', 'application/*', 'text/*', '*/*'].includes(p.type));
+  if (!choice) return new Response('Not acceptable: application/json or text/plain\n', {status: 406});
+  const response = await next();
+  response.headers.set('vary', 'accept');
+  if (!response.ok || !['text/plain', 'text/*'].includes(choice.type)) return response;
+  const value = await response.json();
+  const lines = Object.entries(value).map(([key, item]) => key + ': ' + String(item)).join('\n') + '\n';
+  return new Response(lines, {status: response.status, headers: {...Object.fromEntries(response.headers), 'content-type': 'text/plain; charset=utf-8'}});
+}

package/recipes/middleware/middleware/referer.mjs

@@ -0,0 +1,12 @@
+// Hotlink protection for a download: the Referer host must be on the allowlist.
+// Referers are advisory, so this deters casual embedding rather than securing anything.
+function host(referer) {
+  const match = /^https?:\/\/([^/:?#]+)/i.exec(referer || '');
+  return match ? match[1].toLowerCase() : null;
+}
+export default async function referer(request, context, next) {
+  const allowed = (context.env.ALLOWED_REFERERS || '').split(/\s+/).filter(Boolean);
+  const from = host(request.headers.get('referer'));
+  if (from === null || !allowed.includes(from)) return new Response('Direct download links are not permitted\n', {status: 403});
+  return next();
+}

package/recipes/middleware/middleware/request-id.mjs

@@ -0,0 +1,16 @@
+// Correlation id and timing headers (Hono requestId/timing, Express response-time).
+// The runtime already stamps its own x-request-id on every reply; this carries the
+// caller's id instead so a client can match its logs to yours. The guest has no
+// crypto, so a generated id is a trace label, never a secret.
+const validId = /^[A-Za-z0-9._-]{1,64}$/;
+export default async function correlation(request, context, next) {
+  const started = Date.now();
+  const incoming = request.headers.get('x-correlation-id');
+  context.state.correlationId = incoming !== null && validId.test(incoming)
+    ? incoming
+    : started.toString(36) + '-' + Math.floor(Math.random() * 0xffffffff).toString(36);
+  const response = await next();
+  response.headers.set('x-correlation-id', context.state.correlationId);
+  response.headers.set('server-timing', 'app;dur=' + (Date.now() - started));
+  return response;
+}

package/recipes/middleware/public/guide.txt

@@ -0,0 +1 @@
+URLCode guide

package/recipes/middleware/recipe.yaml

@@ -0,0 +1,50 @@
+id: middleware
+description: Fourteen reusable middleware patterns around fifteen routes, mirroring the cookbook's middleware modules.
+tags: [middleware, auth, bearer, basic, cors, tracing, request-id, errors, etag, caching, maintenance, negotiation, locale, referer, method-override, envelope, validation, debug, bucket, experiment]
+complexity: advanced
+capabilities: [bindings, download, enabled, function, methods, middleware, parameters, redirect, request.body, respond]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 15
+inputs:
+  - name: credentials
+    file: urlcode.yaml
+    description: The literal demo token and password bound as env values; bind real secrets through operator-granted secrets instead.
+  - name: allowlists
+    file: middleware/cors.mjs
+    description: Allowed browser origins here and the referers, locales and buckets in the sibling modules.
+files:
+  - urlcode.yaml
+  - middleware/auth.mjs
+  - middleware/body.mjs
+  - middleware/bucket.mjs
+  - middleware/cors.mjs
+  - middleware/debug.mjs
+  - middleware/envelope.mjs
+  - middleware/errors.mjs
+  - middleware/etag.mjs
+  - middleware/locale.mjs
+  - middleware/maintenance.mjs
+  - middleware/methods.mjs
+  - middleware/negotiate.mjs
+  - middleware/referer.mjs
+  - middleware/request-id.mjs
+  - functions/catalog.mjs
+  - functions/fail.mjs
+  - functions/items.mjs
+  - functions/profile.mjs
+  - functions/resource.mjs
+  - functions/status.mjs
+  - public/guide.txt
+  - tests/requests.json
+  - README.md
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 15
+behavior:
+  - /api/private answers 401 without the bearer token and JSON with it
+  - OPTIONS /cors/data from an allowed origin answers 204 with CORS headers
+  - /maintenance answers 503; /fragile?fail=true answers a JSON error carrying the correlation id
+  - /versioned answers a weak ETag and 304 on a matching If-None-Match