@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/examples/cookbook/example.yaml

@@ -0,0 +1,17 @@
+id: cookbook
+description: Forty runnable routes covering every handler, middleware, inputs, body validation, headers, assets, includes, host policies and site conventions; route-index.json tags each one.
+tags: [cookbook, reference, routes, handlers, middleware, policies, site, includes, parameters, cookies, methods, expiry, assets, everything]
+complexity: advanced
+capabilities: [bindings, download, enabled, expires, function, methods, middleware, page, parameters, policies.agents, policies.cache, policies.security, policies.throttle, redirect, request.body, respond, response.headers, static]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 40
+files: [urlcode.yaml, routes/code.yaml, routes/redirects.yaml, routes/responses.yaml, routes/files.yaml, routes/policies.yaml, routes/middleware.yaml, route-index.json, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/cookbook
+    - node src/cli.ts test --project examples/cookbook
+    - node src/cli.ts audit --project examples/cookbook --expect-routes 40
+behavior:
+  - urlcode examples search finds single routes here through the generated route-index.json
+  - fifteen routes exercise the fourteen middleware modules that the middleware recipe copies

package/examples/cookbook/functions/catalog.mjs

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

package/examples/cookbook/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/examples/cookbook/functions/items.mjs

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

package/examples/cookbook/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/examples/cookbook/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/examples/cookbook/functions/status.mjs

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

package/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/middleware/locale.mjs

@@ -0,0 +1,16 @@
+// Language redirect from Accept-Language, like Next.js i18n middleware. Only
+// languages listed in LOCALES are chosen; the native redirect is the default.
+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;
+  const response = chosen && chosen !== supported[0]
+    ? Response.redirect(context.env.SITE + '/' + chosen + '/welcome', 302)
+    : await next();
+  response.headers.set('vary', 'accept-language');
+  return response;
+}

package/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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/examples/cookbook/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;
+}