@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/recipes/middleware/urlcode.yaml

@@ -0,0 +1,127 @@
+version: "1"
+# Reusable middleware patterns, one route per module. Bindings are literal values
+# here; production projects use {secret: name} with an operator grant instead.
+# Rename or delete the routes you do not need; the modules are independent.
+routes:
+  /api/private:
+    description: Bearer token gate with a constant-time comparison
+    env:
+      API_TOKEN: {value: cookbook-token}
+    middleware:
+      - source: middleware/auth.mjs
+        export: bearer
+    respond: {json: {private: true}}
+  /admin/panel:
+    description: HTTP Basic authentication decoded inside the guest
+    env:
+      ADMIN_USER: {value: admin}
+      ADMIN_PASSWORD: {value: cookbook-password}
+    middleware:
+      - source: middleware/auth.mjs
+        export: basic
+    respond: {text: Admin panel}
+  /cors/data:
+    description: CORS allowlist with preflight handled before the handler
+    methods: [GET, HEAD, OPTIONS]
+    env:
+      ALLOWED_ORIGINS: {value: https://app.example.com https://admin.example.com}
+    middleware:
+      - source: middleware/cors.mjs
+    respond: {json: {shared: true}}
+  /traced:
+    description: Caller correlation id and Server-Timing on every response
+    middleware:
+      - source: middleware/request-id.mjs
+    respond: {text: Traced}
+  /maintenance:
+    description: Kill switch returning 503 unless a bypass header is presented
+    env:
+      MAINTENANCE: {value: "true"}
+      MAINTENANCE_BYPASS: {value: let-me-in}
+    middleware:
+      - source: middleware/maintenance.mjs
+    respond: {text: Still here}
+  /fragile:
+    description: Error boundary turning a thrown exception into a JSON 500
+    parameters:
+      - name: fail
+        in: query
+        schema: {type: boolean, default: false}
+    middleware:
+      - source: middleware/request-id.mjs
+      - source: middleware/errors.mjs
+    function:
+      source: functions/fail.mjs
+      args:
+        fail: {from: query, name: fail}
+  /api/items:
+    description: JSON envelope around a function response
+    middleware:
+      - source: middleware/envelope.mjs
+    function: {source: functions/items.mjs}
+  /negotiated:
+    description: Accept-driven JSON or plain-text representation, 406 otherwise
+    middleware:
+      - source: middleware/negotiate.mjs
+    function: {source: functions/status.mjs}
+  /resource:
+    description: Method override tunneling PUT, PATCH or DELETE through POST
+    methods: [GET, HEAD, POST, PUT, PATCH, DELETE]
+    middleware:
+      - source: middleware/methods.mjs
+        export: override
+    function: {source: functions/resource.mjs}
+  /versioned:
+    description: Weak ETag and 304 for function output
+    middleware:
+      - source: middleware/etag.mjs
+    function: {source: functions/catalog.mjs}
+  /experiment:
+    description: Sticky A/B bucket cookie choosing between two destinations
+    env:
+      VARIANT_URL: {value: https://example.com/landing-b}
+    middleware:
+      - source: middleware/bucket.mjs
+    redirect: {url: https://example.com/landing}
+  /welcome:
+    description: Accept-Language redirect to a localized destination
+    env:
+      LOCALES: {value: en de fr}
+      SITE: {value: https://example.com}
+    middleware:
+      - source: middleware/locale.mjs
+    redirect: {url: https://example.com/en/welcome}
+  /downloads/report:
+    description: Referer allowlist in front of a native download
+    env:
+      ALLOWED_REFERERS: {value: example.com www.example.com}
+    middleware:
+      - source: middleware/referer.mjs
+    download:
+      file: public/guide.txt
+      filename: report.txt
+      contentType: text/plain
+      cacheControl: no-store
+  /profile:
+    description: Body validated once in middleware, parsed object passed through state
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 4096
+        contentTypes: [application/json]
+        format: json
+    middleware:
+      - source: middleware/body.mjs
+    function: {source: functions/profile.mjs}
+  /inspect:
+    description: Authoring aid echoing inputs, args and redacted headers on demand
+    parameters:
+      - name: topic
+        in: query
+        schema: {type: string, default: routing}
+    env:
+      DEBUG: {value: "true"}
+    middleware:
+      - source: middleware/debug.mjs
+    respond: {text: Nothing to see}

package/recipes/protected-download/README.md

@@ -0,0 +1,22 @@
+# Protected download
+
+`/downloads/report` serves `files/report.txt` as an attachment, but only after
+the operator-installed `auth` extension authorizes the request (`auth: true`,
+the short form of `policies.extensions.auth`). The file is
+served natively: no guest code runs, and the response is forced to `no-store`.
+
+Like the `authenticated-json-api` recipe, this project declares the extension
+and needs an operator host file outside the project plus the canonical origin
+for every command:
+
+```sh
+urlcode validate --local --project . --host-file /operator/host.mjs --origin https://files.example.com
+urlcode test --project . --host-file /operator/host.mjs --origin https://files.example.com
+urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://files.example.com
+```
+
+Use the host file from the `authenticated-json-api` README with the config
+schema accepting `realm: downloads`; the bundled fixtures expect the demo token
+`demo-token`. A real deployment registers `urlcode-auth` instead. Replace
+`files/report.txt` with the real attachment and adjust `filename` and
+`contentType`. Cloudflare refuses extensions.

package/recipes/protected-download/files/report.txt

@@ -0,0 +1 @@
+Quarterly report (placeholder). Replace this file with the real attachment.

package/recipes/protected-download/recipe.yaml

@@ -0,0 +1,31 @@
+id: protected-download
+description: Native attachment download that only the operator-installed auth extension lets through.
+tags: [download, attachment, protected, auth, authenticated, file, private, extension, content-disposition, "401"]
+complexity: advanced
+capabilities: [download, enabled, extension, methods, policies.extensions]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused}
+routes: 1
+services:
+  - name: auth extension
+    description: An operator registry providing the `auth` extension; the authenticated-json-api README shows a minimal protocol fixture.
+grants:
+  - kind: extension
+    description: The registration pins projectSha256 to this exact revision, including the attachment.
+  - kind: origin
+    description: The canonical origin passed as --origin at every command that activates the project.
+inputs:
+  - name: attachment
+    file: files/report.txt
+    description: Replace the placeholder and adjust filename and contentType in urlcode.yaml.
+files: [urlcode.yaml, files/report.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project . --host-file /operator/host.mjs --origin https://files.example.com
+    - urlcode test --project . --host-file /operator/host.mjs --origin https://files.example.com
+    - urlcode audit --project . --expect-routes 1 --host-file /operator/host.mjs --origin https://files.example.com
+behavior:
+  - GET /downloads/report without credentials answers 401
+  - GET with the accepted credential answers 200, Content-Disposition attachment and Cache-Control no-store
+  - HEAD mirrors both cases with an empty body
+  - no guest code runs; the file is served natively and snapshotted at activation

package/recipes/protected-download/tests/requests.json

@@ -0,0 +1,32 @@
+[
+  {
+    "path": "/downloads/report",
+    "status": 401
+  },
+  {
+    "path": "/downloads/report",
+    "headers": {
+      "authorization": "Bearer demo-token"
+    },
+    "status": 200,
+    "expectBody": "Quarterly report (placeholder). Replace this file with the real attachment.\n",
+    "expectHeaders": {
+      "content-disposition": "attachment; filename=quarterly-report.txt",
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/downloads/report",
+    "method": "HEAD",
+    "headers": {
+      "authorization": "Bearer demo-token"
+    },
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/downloads/report",
+    "method": "HEAD",
+    "status": 401
+  }
+]

package/recipes/protected-download/urlcode.yaml

@@ -0,0 +1,15 @@
+version: "1"
+extensions:
+  auth:
+    version: "1"
+    config:
+      realm: downloads
+routes:
+  /downloads/report:
+    description: Attachment served natively, only after the auth extension authorizes the caller.
+    download:
+      file: files/report.txt
+      filename: quarterly-report.txt
+      contentType: text/plain
+      cacheControl: no-store
+    auth: true

package/recipes/redirect/README.md

@@ -0,0 +1,7 @@
+# Permanent documentation redirect
+
+Run `urlcode validate --local --project .` and `urlcode serve --project .`.
+`/docs?campaign=launch&private=discarded` redirects to
+`https://example.com/documentation?campaign=launch` with status 301.
+Replace the example destination before deploying. Incoming query parameters are
+not forwarded unless explicitly allowlisted.

package/recipes/redirect/recipe.yaml

@@ -0,0 +1,25 @@
+id: redirect
+description: Permanent redirect that forwards only an allowlisted query key.
+tags: [redirect, permanent, "301", query, passthrough, documentation, native]
+complexity: starter
+capabilities: [enabled, methods, redirect]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible}
+routes: 1
+inputs:
+  - name: destination
+    file: urlcode.yaml
+    description: Replace https://example.com/documentation with the real target.
+  - name: query.pass
+    file: urlcode.yaml
+    description: The query keys forwarded to the destination; everything else is dropped.
+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 1
+behavior:
+  - GET /docs?campaign=launch&private=x answers 301 to https://example.com/documentation?campaign=launch
+  - HEAD answers the same status with an empty body
+  - unknown paths answer 404

package/recipes/redirect/tests/requests.json

@@ -0,0 +1,19 @@
+[
+  {
+    "path": "/docs?campaign=launch&private=discarded",
+    "status": 301,
+    "expectHeaders": {
+      "location": "https://example.com/documentation?campaign=launch"
+    }
+  },
+  {
+    "path": "/docs",
+    "method": "HEAD",
+    "status": 301,
+    "expectBody": ""
+  },
+  {
+    "path": "/missing",
+    "status": 404
+  }
+]

package/recipes/redirect/urlcode.yaml

@@ -0,0 +1,9 @@
+version: "1"
+routes:
+  /docs:
+    description: Move documentation and preserve only the declared campaign key.
+    redirect:
+      url: https://example.com/documentation
+      status: 301
+      query:
+        pass: [campaign]

package/recipes/static-plus-api/README.md

@@ -0,0 +1,15 @@
+# Static site with a JSON API
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 3`.
+
+`/` serves `public/index.html`, `/assets/*` serves everything under
+`public/assets` (with `index.html` for the directory itself), and `/api/info`
+is a sandboxed function returning JSON built from literal `args`. Pages and
+assets are native: no guest code runs for them, and they are snapshotted at
+activation, so new files need a reload. Edit the HTML, add files under
+`public/assets`, and change or extend `functions/info.mjs`.
+
+The function needs the self-hosted runtime; drop `/api/info` to deploy the
+static part on a serverless target. Static mounts cannot escape their
+directory, and the recipe sets explicit caching so nothing is guessed.

package/recipes/static-plus-api/functions/info.mjs

@@ -0,0 +1,3 @@
+export default function info(request, {args}) {
+  return Response.json({name: args.name, version: args.version});
+}

package/recipes/static-plus-api/public/assets/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Assets</title></head>
+<body><p>Asset directory index.</p></body></html>

package/recipes/static-plus-api/public/assets/site.css

@@ -0,0 +1 @@
+body { font-family: system-ui, sans-serif; margin: 2rem; }

package/recipes/static-plus-api/public/index.html

@@ -0,0 +1,8 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Example site</title><link rel="stylesheet" href="/assets/site.css"></head>
+<body>
+<h1>Example site</h1>
+<p>Static pages are served natively; <a href="/api/info">/api/info</a> is a sandboxed function.</p>
+</body>
+</html>

package/recipes/static-plus-api/recipe.yaml

@@ -0,0 +1,29 @@
+id: static-plus-api
+description: A native static site (home page and an assets directory) next to one sandboxed JSON endpoint.
+tags: [static, site, page, html, assets, css, api, json, function, cache-control, website]
+complexity: intermediate
+capabilities: [enabled, function, methods, page, response.headers, static]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 3
+inputs:
+  - name: pages
+    file: public/index.html
+    description: The home page and everything under public/assets.
+  - name: args
+    file: urlcode.yaml
+    description: The literal name and version /api/info reports.
+  - name: handler
+    file: functions/info.mjs
+    description: Replace the literal JSON with the real endpoint.
+files: [urlcode.yaml, public/index.html, public/assets/index.html, public/assets/site.css, functions/info.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode validate --local --project .
+    - urlcode test --project .
+    - urlcode audit --project . --expect-routes 3
+behavior:
+  - GET / answers the home page as text/html with Cache-Control no-cache
+  - GET /assets/site.css answers text/css cached for one hour; /assets/ answers the directory index; missing files answer 404
+  - GET /api/info answers 200 {"name":"Example site","version":"1"} with no-store
+  - drop /api/info to deploy the static part on a serverless target

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

@@ -0,0 +1,56 @@
+[
+  {
+    "path": "/",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-cache"
+    }
+  },
+  {
+    "path": "/",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/assets/site.css",
+    "status": 200,
+    "expectBody": "body { font-family: system-ui, sans-serif; margin: 2rem; }\n",
+    "expectHeaders": {
+      "content-type": "text/css; charset=utf-8",
+      "cache-control": "public, max-age=3600"
+    }
+  },
+  {
+    "path": "/assets/",
+    "status": 200,
+    "expectHeaders": {
+      "content-type": "text/html; charset=utf-8"
+    }
+  },
+  {
+    "path": "/assets/site.css",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/assets/missing.css",
+    "status": 404
+  },
+  {
+    "path": "/api/info",
+    "status": 200,
+    "expectBody": "{\"name\":\"Example site\",\"version\":\"1\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/api/info",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  }
+]

package/recipes/static-plus-api/urlcode.yaml

@@ -0,0 +1,23 @@
+version: "1"
+routes:
+  /:
+    description: The site's home page served natively from public/index.html.
+    page:
+      file: public/index.html
+      cacheControl: no-cache
+  /assets/*:
+    description: Every file under public/assets, with a directory index and one-hour caching.
+    static:
+      directory: public/assets
+      index: index.html
+      cacheControl: public, max-age=3600
+  /api/info:
+    description: A small JSON endpoint next to the static site, computed in the sandbox.
+    function:
+      source: functions/info.mjs
+      args:
+        name: Example site
+        version: "1"
+    response:
+      headers:
+        Cache-Control: no-store

package/recipes/typescript/README.md

@@ -0,0 +1,7 @@
+# Build-time TypeScript guest
+
+Run `urlcode build-typescript --project . --out ../hello-built` with a new output
+directory, then `urlcode validate --local --project ../hello-built` and
+`urlcode serve --project ../hello-built`. GET `/hello` returns JSON.
+TypeScript is transpiled ahead of time. The runtime executes only the emitted
+JavaScript in QuickJS/WASM. The build does not type-check or read tsconfig.json.

package/recipes/typescript/functions/hello.ts

@@ -0,0 +1,5 @@
+interface Greeting { message: string }
+export default function hello(): Response {
+  const greeting: Greeting = {message: 'Hello from a compiled TypeScript guest'};
+  return Response.json(greeting);
+}

package/recipes/typescript/recipe.yaml

@@ -0,0 +1,23 @@
+id: typescript
+description: Typed guest function transpiled ahead of time; only the emitted JavaScript runs in the sandbox.
+tags: [typescript, function, build, typed, compile, sandbox]
+complexity: intermediate
+capabilities: [enabled, function, methods]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 1
+inputs:
+  - name: handler
+    file: functions/hello.ts
+    description: The typed guest; keep to the Request/Response sandbox API.
+files: [urlcode.yaml, functions/hello.ts, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode build-typescript --project . --out ../hello-built
+    - urlcode validate --local --project ../hello-built
+    - urlcode test --project ../hello-built
+    - urlcode audit --project ../hello-built --expect-routes 1
+behavior:
+  - after the build, GET /hello answers 200 JSON from the compiled guest
+  - the unbuilt project does not activate; .ts sources never run
+  - POST answers 405

package/recipes/typescript/tests/requests.json

@@ -0,0 +1,18 @@
+[
+  {
+    "path": "/hello",
+    "status": 200,
+    "expectBody": "{\"message\":\"Hello from a compiled TypeScript guest\"}"
+  },
+  {
+    "path": "/hello",
+    "method": "HEAD",
+    "status": 200,
+    "expectBody": ""
+  },
+  {
+    "path": "/hello",
+    "method": "POST",
+    "status": 405
+  }
+]

package/recipes/typescript/urlcode.yaml

@@ -0,0 +1,5 @@
+version: "1"
+routes:
+  /hello:
+    function:
+      source: functions/hello.ts

package/recipes/webhook-receiver/README.md

@@ -0,0 +1,16 @@
+# Webhook receiver
+
+Run `urlcode validate --local --project .`, `urlcode test --project .` and
+`urlcode audit --project . --expect-routes 1`.
+
+`POST /webhook` accepts at most 64 KiB of `application/json`. The runtime
+rejects other methods (405), other content types (415), oversized bodies (413)
+and malformed JSON (400) before the sandbox runs. The function then requires an
+`X-Webhook-Event` header and a JSON object carrying a string `id`, and answers
+`202 {"received":true,...}`.
+
+This recipe verifies shape, not origin. Nothing here checks a signature: the
+guest has no crypto API and no network access, so signed webhooks belong behind
+an operator-installed extension or a trusted host in front of this route. Edit
+`functions/receive.mjs` to check the fields your sender guarantees, and keep
+the body limit as small as the sender allows.

package/recipes/webhook-receiver/functions/receive.mjs

@@ -0,0 +1,16 @@
+// The runtime has already enforced method, content type, size and JSON syntax.
+// The guest checks the shape it cares about and acknowledges; it has no network
+// access, so forwarding happens through a declared route signal or a host process
+// that reads the runtime log, never from here.
+const eventPattern = /^[a-z][a-z0-9_.-]{0,63}$/;
+export default async function receive(request) {
+  const event = request.headers.get('x-webhook-event');
+  if (!event || !eventPattern.test(event)) {
+    return Response.json({error: 'missing or invalid X-Webhook-Event header'}, {status: 400});
+  }
+  const payload = await request.json();
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload) || typeof payload.id !== 'string') {
+    return Response.json({error: 'body must be a JSON object with a string id'}, {status: 422});
+  }
+  return Response.json({received: true, event, id: payload.id}, {status: 202});
+}

package/recipes/webhook-receiver/recipe.yaml

@@ -0,0 +1,26 @@
+id: webhook-receiver
+description: Accept a bounded JSON event that names its type in a header, check its shape and acknowledge with 202.
+tags: [webhook, receiver, event, post, json, body, "202", callback, ingest, function]
+complexity: starter
+capabilities: [enabled, function, methods, request.body, response.headers]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused}
+routes: 1
+inputs:
+  - name: shape check
+    file: functions/receive.mjs
+    description: The header name, event pattern and payload fields the sender guarantees.
+  - name: maxBytes
+    file: urlcode.yaml
+    description: The body limit (64 KiB); keep it as small as the sender allows.
+files: [urlcode.yaml, functions/receive.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 /webhook with application/json, X-Webhook-Event and a string id answers 202 {"received":true,"event":...,"id":...}
+  - a missing event header answers 400; a body that is not an object with a string id answers 422
+  - other methods 405, other content types 415, oversized bodies 413 and malformed JSON 400 before the sandbox runs
+  - the guest has no crypto or network API, so signatures are not verified here; put signed webhooks behind an operator extension or trusted host

package/recipes/webhook-receiver/tests/requests.json

@@ -0,0 +1,59 @@
+[
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "{\"id\":\"evt_123\",\"total\":42}",
+    "status": 202,
+    "expectBody": "{\"received\":true,\"event\":\"order.created\",\"id\":\"evt_123\"}",
+    "expectHeaders": {
+      "cache-control": "no-store"
+    }
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json"
+    },
+    "body": "{\"id\":\"evt_123\"}",
+    "status": 400
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "[1,2,3]",
+    "status": 422
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "application/json",
+      "x-webhook-event": "order.created"
+    },
+    "body": "{not json",
+    "status": 400
+  },
+  {
+    "path": "/webhook",
+    "method": "POST",
+    "headers": {
+      "content-type": "text/plain",
+      "x-webhook-event": "order.created"
+    },
+    "body": "id=1",
+    "status": 415
+  },
+  {
+    "path": "/webhook",
+    "status": 405
+  }
+]

package/recipes/webhook-receiver/urlcode.yaml

@@ -0,0 +1,16 @@
+version: "1"
+routes:
+  /webhook:
+    description: Accept a bounded JSON event body that names its event type in a header.
+    methods: [POST]
+    request:
+      body:
+        required: true
+        maxBytes: 65536
+        contentTypes: [application/json]
+        format: json
+    function:
+      source: functions/receive.mjs
+    response:
+      headers:
+        Cache-Control: no-store