@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/recipes/middleware/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/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}
+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

package/recipes/middleware/tests/requests.json

@@ -0,0 +1,528 @@
+[
+  {
+    "path": "/api/private",
+    "status": 401,
+    "expectHeaders": {
+      "www-authenticate": "Bearer realm=\"cookbook\""
+    }
+  },
+  {
+    "path": "/api/private",
+    "status": 401,
+    "headers": {
+      "authorization": "Bearer wrong-token"
+    }
+  },
+  {
+    "path": "/api/private",
+    "status": 200,
+    "headers": {
+      "authorization": "Bearer cookbook-token"
+    },
+    "expectBody": "{\"private\":true}"
+  },
+  {
+    "path": "/api/private",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Bearer cookbook-token"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/admin/panel",
+    "status": 401,
+    "expectHeaders": {
+      "www-authenticate": "Basic realm=\"cookbook\", charset=\"UTF-8\""
+    }
+  },
+  {
+    "path": "/admin/panel",
+    "status": 401,
+    "headers": {
+      "authorization": "Basic YWRtaW46d3Jvbmc="
+    }
+  },
+  {
+    "path": "/admin/panel",
+    "status": 200,
+    "headers": {
+      "authorization": "Basic YWRtaW46Y29va2Jvb2stcGFzc3dvcmQ="
+    },
+    "expectBody": "Admin panel"
+  },
+  {
+    "path": "/admin/panel",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Basic YWRtaW46Y29va2Jvb2stcGFzc3dvcmQ="
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/cors/data",
+    "status": 204,
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://app.example.com",
+      "access-control-request-method": "GET"
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://app.example.com",
+      "access-control-allow-methods": "GET, HEAD, OPTIONS",
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 204,
+    "method": "OPTIONS",
+    "headers": {
+      "origin": "https://evil.example.net"
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "headers": {
+      "origin": "https://admin.example.com"
+    },
+    "expectBody": "{\"shared\":true}",
+    "expectHeaders": {
+      "access-control-allow-origin": "https://admin.example.com"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "expectBody": "{\"shared\":true}",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/cors/data",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": "",
+    "expectHeaders": {
+      "vary": "origin"
+    }
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "trace-123"
+    },
+    "expectBody": "Traced",
+    "expectHeaders": {
+      "x-correlation-id": "trace-123"
+    }
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "not valid!"
+    },
+    "expectBody": "Traced"
+  },
+  {
+    "path": "/traced",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/maintenance",
+    "status": 503,
+    "expectBody": "Down for maintenance\n",
+    "expectHeaders": {
+      "retry-after": "120"
+    }
+  },
+  {
+    "path": "/maintenance",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "x-maintenance-bypass": "let-me-in"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/maintenance",
+    "status": 200,
+    "headers": {
+      "x-maintenance-bypass": "let-me-in"
+    },
+    "expectBody": "Still here"
+  },
+  {
+    "path": "/fragile",
+    "status": 200,
+    "headers": {
+      "x-correlation-id": "r-1"
+    },
+    "expectBody": "{\"healthy\":true}",
+    "expectHeaders": {
+      "x-correlation-id": "r-1"
+    }
+  },
+  {
+    "path": "/fragile?fail=true",
+    "status": 500,
+    "headers": {
+      "x-correlation-id": "r-2"
+    },
+    "expectBody": "{\"error\":\"Temporarily unavailable\",\"correlationId\":\"r-2\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/fragile",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/fragile?fail=true",
+    "status": 500,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/fragile?fail=perhaps",
+    "status": 400
+  },
+  {
+    "path": "/api/items",
+    "status": 200,
+    "expectBody": "{\"ok\":true,\"data\":[{\"id\":1,\"name\":\"first\"},{\"id\":2,\"name\":\"second\"}],\"meta\":{\"route\":\"/api/items\",\"count\":2}}"
+  },
+  {
+    "path": "/api/items",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "expectBody": "{\"service\":\"cookbook\",\"state\":\"ok\"}",
+    "expectHeaders": {
+      "vary": "accept"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "headers": {
+      "accept": "application/json"
+    },
+    "expectBody": "{\"service\":\"cookbook\",\"state\":\"ok\"}"
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "headers": {
+      "accept": "text/plain, application/json;q=0.5"
+    },
+    "expectBody": "service: cookbook\nstate: ok\n",
+    "expectHeaders": {
+      "content-type": "text/plain; charset=utf-8"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 406,
+    "headers": {
+      "accept": "image/png"
+    }
+  },
+  {
+    "path": "/negotiated",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "expectBody": "{\"method\":\"GET\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "POST",
+    "expectBody": "{\"method\":\"POST\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "POST",
+    "headers": {
+      "x-http-method-override": "delete"
+    },
+    "expectBody": "{\"method\":\"DELETE\",\"tunneled\":true}"
+  },
+  {
+    "path": "/resource",
+    "status": 405,
+    "method": "POST",
+    "headers": {
+      "x-http-method-override": "TRACE"
+    },
+    "expectHeaders": {
+      "allow": "PUT, PATCH, DELETE"
+    }
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "PUT",
+    "expectBody": "{\"method\":\"PUT\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "PATCH",
+    "expectBody": "{\"method\":\"PATCH\",\"tunneled\":false}"
+  },
+  {
+    "path": "/resource",
+    "status": 200,
+    "method": "DELETE",
+    "expectBody": "{\"method\":\"DELETE\",\"tunneled\":false}"
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "expectBody": "{\"version\":3,\"items\":[\"alpha\",\"beta\"]}",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\"",
+      "cache-control": "public, max-age=60"
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 304,
+    "headers": {
+      "if-none-match": "W/\"b4124e8a\""
+    },
+    "expectBody": "",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "headers": {
+      "if-none-match": "W/\"stale\""
+    },
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/versioned",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": "",
+    "expectHeaders": {
+      "etag": "W/\"b4124e8a\""
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "headers": {
+      "cookie": "bucket=a"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing",
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "headers": {
+      "cookie": "theme=light; bucket=b"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing-b",
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "expectHeaders": {
+      "vary": "cookie"
+    }
+  },
+  {
+    "path": "/experiment",
+    "status": 302,
+    "method": "HEAD",
+    "headers": {
+      "cookie": "bucket=a"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/landing"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "expectHeaders": {
+      "location": "https://example.com/en/welcome",
+      "vary": "accept-language"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "de-DE,de;q=0.9,en;q=0.8"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/de/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "fr-CA"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/fr/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "headers": {
+      "accept-language": "ja"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/en/welcome"
+    }
+  },
+  {
+    "path": "/welcome",
+    "status": 302,
+    "method": "HEAD",
+    "headers": {
+      "accept-language": "de"
+    },
+    "expectHeaders": {
+      "location": "https://example.com/de/welcome"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 403
+  },
+  {
+    "path": "/downloads/report",
+    "status": 403,
+    "headers": {
+      "referer": "https://evil.example.net/page"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 200,
+    "headers": {
+      "referer": "https://www.example.com/docs"
+    },
+    "expectBody": "URLCode guide\n",
+    "expectHeaders": {
+      "content-disposition": "attachment; filename=report.txt"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "status": 200,
+    "method": "HEAD",
+    "headers": {
+      "referer": "https://example.com/"
+    },
+    "expectBody": ""
+  },
+  {
+    "path": "/profile",
+    "status": 201,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"Ada\",\"age\":36}",
+    "expectBody": "{\"welcome\":\"Ada\",\"age\":36}"
+  },
+  {
+    "path": "/profile",
+    "status": 422,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"name\":\"\",\"age\":-1,\"role\":\"x\"}",
+    "expectBody": "{\"errors\":[\"name must be 1-80 characters\",\"age must be an integer from 0 to 150\",\"unknown field role\"]}"
+  },
+  {
+    "path": "/profile",
+    "status": 400,
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "["
+  },
+  {
+    "path": "/profile",
+    "status": 405
+  },
+  {
+    "path": "/inspect?topic=middleware",
+    "status": 200,
+    "expectBody": "Nothing to see"
+  },
+  {
+    "path": "/inspect?topic=middleware",
+    "status": 200,
+    "headers": {
+      "x-debug": "1",
+      "authorization": "Bearer hidden"
+    },
+    "expectHeaders": {
+      "cache-control": "no-store",
+      "content-type": "application/json"
+    }
+  },
+  {
+    "path": "/inspect",
+    "status": 200,
+    "method": "HEAD",
+    "expectBody": ""
+  }
+]