@jimhoyd/urlcode 0.4.2 → 0.4.7

package/examples/body-validation/tests/requests.json

@@ -0,0 +1,15 @@
+[
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json"},"body":"{\"title\":\"Buy milk\"}","status":201,"expectBody":"{\"ok\":true}"},
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json"},"body":"{\"title\":5}","status":422},
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json"},"body":"{\"title\":\"x\",\"extra\":1}","status":422},
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json","accept":"application/json"},"body":"{\"title\":5}","status":422,"expectHeaders":{"content-type":"application/json"},"expectBody":"{\"error\":\"body_validation_failed\",\"message\":\"Request body failed validation\",\"issues\":[{\"pointer\":\"/title\",\"keyword\":\"type\",\"message\":\"must be a string\",\"expected\":\"string\"}]}"},
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json","accept":"*/*"},"body":"{\"title\":5}","status":422,"expectHeaders":{"content-type":"text/plain; charset=utf-8"},"expectBody":"Request body failed validation\n/title must be a string\n"},
+  {"path":"/todos","method":"POST","headers":{"content-type":"application/json"},"body":"{nope","status":400},
+  {"path":"/todos","method":"POST","headers":{"content-type":"text/plain"},"body":"hi","status":415},
+  {"path":"/todos/123e4567-e89b-42d3-a456-426614174000","status":200,"expectBody":"{\"ok\":true}"},
+  {"path":"/todos/123e4567-e89b-42d3-a456-426614174000","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/todos/not-a-uuid","status":400},
+  {"path":"/tags?slug=ok-1","status":200,"expectBody":"{\"ok\":true}"},
+  {"path":"/tags?slug=ok-1","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/tags?slug=Bad_Slug","status":400}
+]

package/examples/body-validation/urlcode.yaml

@@ -0,0 +1,34 @@
+version: "1"
+routes:
+  /todos:
+    methods: [POST]
+    request:
+      body:
+        maxBytes: 4096
+        contentTypes: [application/json]
+        format: json
+        required: true
+        schema:
+          type: object
+          required: [title]
+          additionalProperties: false
+          properties:
+            title: {type: string, minLength: 1, maxLength: 200}
+            description: {type: string, maxLength: 2000}
+            completed: {type: boolean}
+    respond:
+      status: 201
+      json: {ok: true}
+  /todos/{id}:
+    parameters:
+      - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
+    respond:
+      json: {ok: true}
+  /tags:
+    parameters:
+      - name: slug
+        in: query
+        required: true
+        schema: {type: string, pattern: "^[a-z0-9-]+$", maxLength: 32}
+    respond:
+      json: {ok: true}

package/examples/coverage-waiver/README.md

@@ -0,0 +1,8 @@
+# Audit coverage waiver
+
+`urlcode audit --project examples/coverage-waiver` reports `ready: true` although
+`POST /notes` has no fixture, because the route declares `coveredElsewhere` for
+that method with a reason. The pair is still listed under `waivedRouteMethods`.
+A waiver is honored only when the route has another passing normal-response
+fixture (here `GET`). See
+[readiness](../../docs/READINESS.md#waive-a-method-covered-elsewhere).

package/examples/coverage-waiver/example.yaml

@@ -0,0 +1,16 @@
+id: coverage-waiver
+description: A stateful POST route waived from audit coverage with a required reason, kept visible under waivedRouteMethods.
+tags: [audit, readiness, coverage, waiver, covered-elsewhere,function, post]
+complexity: intermediate
+capabilities: [enabled, function, methods]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 1
+files: [urlcode.yaml, functions/notes.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/coverage-waiver
+    - node src/cli.ts test --project examples/coverage-waiver
+    - node src/cli.ts audit --project examples/coverage-waiver --expect-routes 1
+behavior:
+  - POST /notes is waived from coverage with a reason; GET is asserted by a fixture; the waiver is listed by audit, not hidden

package/examples/coverage-waiver/functions/notes.mjs

@@ -0,0 +1,2 @@
+export default (request) =>
+  request.method === 'POST' ? new Response('created', { status: 201 }) : new Response('notes');

package/examples/coverage-waiver/tests/requests.json

@@ -0,0 +1,3 @@
+[
+  { "path": "/notes", "status": 200, "expectBody": "notes" }
+]

package/examples/coverage-waiver/urlcode.yaml

@@ -0,0 +1,10 @@
+version: "1"
+routes:
+  /notes:
+    methods: [GET, POST]
+    # POST creates a note in a real store, so a fixture would mutate it. The
+    # reason is required and is listed by `urlcode audit` under waivedRouteMethods.
+    coveredElsewhere:
+      POST: "Creates a note; covered by the store's integration tests, not by a repeatable fixture."
+    function:
+      source: functions/notes.mjs

package/examples/data-dir/README.md

@@ -0,0 +1,39 @@
+# Data directory example
+
+A trusted function that reads files from a directory the operator picks. The
+project declares only the *name* `DATA_DIR`; the host supplies the value, so a
+test run, a benchmark or a deployment can point the same reviewed project at a
+different directory without copying it.
+
+```yaml
+routes:
+  /notes/{name}:
+    function: functions/note.mjs
+    env:
+      DATA_DIR: {env: DATA_DIR}
+```
+
+The function receives the resolved value as `env.DATA_DIR` in its second
+argument. It does not read `process.env`, so the binding stays visible to
+`permissions` and `audit`. Validate the request-supplied file name before
+joining it to the directory; the function does that with an allowlist pattern.
+
+There is no default: a binding the operator did not grant, or a `DATA_DIR` that
+is not set, refuses to activate rather than falling back to a directory the
+project chose. Use `{value: ...}` only for a fixed literal.
+
+Run it from the runtime checkout. The policy lives outside the project, and the
+`--policy` file must be regenerated whenever the config or function changes:
+
+```sh
+urlcode permissions --project examples/data-dir > /path/outside/project/policy.json
+export DATA_DIR=./examples/data-dir/data        # relative paths resolve from the process working directory
+urlcode validate --local --project examples/data-dir --policy /path/outside/project/policy.json
+urlcode test --project examples/data-dir --policy /path/outside/project/policy.json
+urlcode audit --project examples/data-dir --expect-routes 1 --policy /path/outside/project/policy.json
+```
+
+For local development, `DATA_DIR=...` may live in an ignored `.env.local`;
+production `serve` reads only the process environment. See
+[bindings](../../docs/yaml/organization.md#12-environment-and-secret-references)
+and [policy setup](../../docs/FUNCTION-SECURITY.md).

package/examples/data-dir/data/welcome.txt

@@ -0,0 +1 @@
+hello from the data directory

package/examples/data-dir/example.yaml

@@ -0,0 +1,22 @@
+id: data-dir
+description: A trusted function reads files from a data directory the operator chooses through an {env} binding, so a test or deployment can point the same project at another directory.
+tags: [env, binding, data, directory, file, function, trusted, policy, operator, data-dir]
+complexity: intermediate
+capabilities: [bindings, enabled, function, methods, parameters]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 1
+grants:
+  - kind: env
+    description: The exact name DATA_DIR granted to /notes/{name} in an operator policy outside the project (urlcode permissions prints the proposal). The process environment supplies its value.
+files: [urlcode.yaml, functions/note.mjs, data/welcome.txt, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - urlcode permissions --project examples/data-dir > /path/outside/project/policy.json
+    - DATA_DIR=./examples/data-dir/data urlcode validate --local --project examples/data-dir --policy /path/outside/project/policy.json
+    - DATA_DIR=./examples/data-dir/data urlcode test --project examples/data-dir --policy /path/outside/project/policy.json
+    - DATA_DIR=./examples/data-dir/data urlcode audit --project examples/data-dir --expect-routes 1 --policy /path/outside/project/policy.json
+behavior:
+  - GET /notes/welcome answers 200 with the text of $DATA_DIR/welcome.txt
+  - an unknown or malformed name answers 404 or 400 and never reaches outside the directory
+  - without a policy grant, or with DATA_DIR unset, the project refuses to activate

package/examples/data-dir/functions/note.mjs

@@ -0,0 +1,18 @@
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+
+const safeName = /^[a-z0-9-]{1,64}$/;
+
+// Trusted function: `env.DATA_DIR` is the operator-resolved {env: DATA_DIR}
+// binding, so the host chooses the directory and this code never reads
+// process.env. The name is still request data: validate it before joining.
+export default async function note(request, {args, env}) {
+  if (!safeName.test(args.name)) return Response.json({error: 'unknown note'}, {status: 404});
+  try {
+    const text = await readFile(join(env.DATA_DIR, `${args.name}.txt`), 'utf8');
+    return Response.json({name: args.name, text: text.trimEnd()});
+  } catch (error) {
+    if (error.code === 'ENOENT') return Response.json({error: 'unknown note'}, {status: 404});
+    throw error;
+  }
+}

package/examples/data-dir/tests/requests.json

@@ -0,0 +1,6 @@
+[
+  {"path":"/notes/welcome","status":200,"expectBody":"{\"name\":\"welcome\",\"text\":\"hello from the data directory\"}"},
+  {"path":"/notes/welcome","method":"HEAD","status":200,"expectBody":""},
+  {"path":"/notes/missing","status":404},
+  {"path":"/notes/..%2Fsecret","status":400}
+]

package/examples/data-dir/urlcode.yaml

@@ -0,0 +1,6 @@
+version: "1"
+routes:
+  /notes/{name}:
+    function: functions/note.mjs
+    env:
+      DATA_DIR: {env: DATA_DIR}

package/examples/lifecycle/README.md

@@ -0,0 +1,15 @@
+# Create, read, update, restart
+
+One ordered fixture in `tests/requests.json` walks a note through its whole life:
+
+```sh
+urlcode test --project examples/lifecycle
+```
+
+The fixture is a `steps` list. The POST captures the new note's `id` (from the JSON
+body) and its `Location` (from a header); later steps use them as `{{id}}` and
+`{{where}}`. The `{"restart": true}` step closes the runtime and starts it again on
+the same project and data directory, so the last request proves the note survived.
+The function keeps notes under `URLCODE_DATA_DIR`, which `urlcode test` points at a
+fresh temporary directory for each run. All data is synthetic. See the
+[fixture reference](../../docs/READINESS.md#multi-step-fixtures).

package/examples/lifecycle/example.yaml

@@ -0,0 +1,19 @@
+id: lifecycle
+description: Create, read, update, restart and read again, driven by one ordered fixture with captured values and a restart step, with no hand-written test harness.
+tags: [fixtures, steps, capture, restart, lifecycle, persistence, data-directory, testing, function]
+complexity: intermediate
+capabilities: [bindings, enabled, function, methods, parameters, request.body]
+targets: {self-hosted: compatible, aws: refused, vercel: refused, cloudflare: refused, static: refused}
+routes: 2
+grants:
+  - kind: env
+    description: URLCODE_DATA_DIR, the data directory. `urlcode test` and `urlcode audit` grant it themselves for their own throwaway directory; a real deployment needs an operator policy grant and a directory that outlives the process.
+files: [urlcode.yaml, functions/notes.mjs, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts test --project examples/lifecycle
+    - node src/cli.ts audit --project examples/lifecycle --expect-routes 2
+behavior:
+  - a note created by POST /notes is readable, replaceable and still present after the runtime restarts on the same data directory
+  - the id and Location the create response returns are captured and substituted into later steps as {{id}} and {{where}}

package/examples/lifecycle/functions/notes.mjs

@@ -0,0 +1,29 @@
+import { randomBytes } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Trusted first-party code: it writes to the data directory.
+// The directory comes from a declared env binding; `urlcode test` gives every run a fresh one.
+const file = (env, id) => join(env.DATA_DIR, `note-${id}.json`);
+
+export async function create(request, { env }) {
+  const { text } = await request.json();
+  const id = randomBytes(4).toString('hex');
+  await writeFile(file(env, id), JSON.stringify({ id, text, version: 1 }));
+  return new Response(JSON.stringify({ id, text, version: 1 }), {
+    status: 201, headers: { 'content-type': 'application/json', location: `/notes/${id}` },
+  });
+}
+
+export async function note(request, { args, env }) {
+  // The id becomes part of a file name: accept only what create() issues.
+  if (!/^[0-9a-f]{8}$/.test(args.id)) return Response.json({ error: 'not found' }, { status: 404 });
+  let current;
+  try { current = JSON.parse(await readFile(file(env, args.id), 'utf8')); }
+  catch { return Response.json({ error: 'not found' }, { status: 404 }); }
+  if (request.method === 'PUT') {
+    current = { ...current, text: (await request.json()).text, version: current.version + 1 };
+    await writeFile(file(env, args.id), JSON.stringify(current));
+  }
+  return Response.json(current);
+}

package/examples/lifecycle/tests/requests.json

@@ -0,0 +1,12 @@
+[
+  {"path":"/notes/deadbeef","status":404},
+  {"steps":[
+    {"path":"/notes","method":"POST","headers":{"content-type":"application/json"},"body":"{\"text\":\"first\"}","status":201,"expectHeaders":{"content-type":"application/json"},
+     "capture":{"id":{"json":"id"},"where":{"header":"location"}}},
+    {"path":"{{where}}","status":200,"expectBody":"{\"id\":\"{{id}}\",\"text\":\"first\",\"version\":1}"},
+    {"path":"/notes/{{id}}","method":"PUT","headers":{"content-type":"application/json"},"body":"{\"text\":\"second\"}","status":200,
+     "expectBody":"{\"id\":\"{{id}}\",\"text\":\"second\",\"version\":2}"},
+    {"restart":true},
+    {"path":"/notes/{{id}}","status":200,"expectBody":"{\"id\":\"{{id}}\",\"text\":\"second\",\"version\":2}"}
+  ]}
+]

package/examples/lifecycle/urlcode.yaml

@@ -0,0 +1,29 @@
+version: "1"
+routes:
+  /notes:
+    description: Create a note; the response carries its id and Location
+    sandboxReason: Reviewed first-party code; it writes to the data directory, so it is trusted deliberately.
+    methods: [POST]
+    request:
+      body: {required: true, maxBytes: 1024, contentTypes: [application/json]}
+    function: {source: functions/notes.mjs, export: create}
+    env:
+      DATA_DIR: {env: URLCODE_DATA_DIR}
+  /notes/{id}:
+    description: Read or replace one note, kept in a file under the data directory
+    sandboxReason: Reviewed first-party code; it writes to the data directory, so it is trusted deliberately.
+    methods: [GET, PUT]
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema: {type: string, minLength: 8, maxLength: 8}
+    request:
+      body: {maxBytes: 1024, contentTypes: [application/json]}
+    function:
+      source: functions/notes.mjs
+      export: note
+      args:
+        id: {from: path, name: id}
+    env:
+      DATA_DIR: {env: URLCODE_DATA_DIR}

package/examples/not-found/README.md

@@ -0,0 +1,10 @@
+# Custom 404 page
+
+`site.notFound` names an HTML file that answers every GET or HEAD matching no
+route, with status 404 and `text/html`. See
+[site conventions](../../docs/SITE.md#notfound--404html).
+
+```sh
+node src/cli.ts test --project examples/not-found
+node src/cli.ts build --target static --project examples/not-found   # writes 404.html
+```

package/examples/not-found/example.yaml

@@ -0,0 +1,17 @@
+id: not-found
+description: A branded 404 page for unmatched routes with one site.notFound key, served with status 404 and buildable as 404.html for static hosting.
+tags: ['404', not-found, error-page, site, html, static]
+complexity: starter
+capabilities: [enabled, methods, page]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: refused, static: compatible}
+routes: 2
+files: [urlcode.yaml, public/index.html, public/404.html, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/not-found
+    - node src/cli.ts test --project examples/not-found
+    - node src/cli.ts audit --project examples/not-found --expect-routes 2
+behavior:
+  - an unmatched GET or HEAD is answered with the page and status 404
+  - other methods keep the plain-text 404

package/examples/not-found/public/404.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Page not found</title></head>
+<body><h1>Page not found</h1><p>That address matches nothing here. <a href="/">Go home</a>.</p></body></html>

package/examples/not-found/public/index.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Home</title></head>
+<body><h1>Home</h1><p>Request any other path to see the 404 page.</p></body></html>

package/examples/not-found/tests/requests.json

@@ -0,0 +1,7 @@
+[
+  {"path": "/", "status": 200, "expectHeaders": {"content-type": "text/html; charset=utf-8"}},
+  {"path": "/nope", "status": 404, "expectHeaders": {"content-type": "text/html; charset=utf-8", "cache-control": "no-store"}},
+  {"path": "/nope", "method": "HEAD", "status": 404, "expectBody": ""},
+  {"path": "/nope", "method": "POST", "status": 404, "expectBody": "Not found\n"},
+  {"path": "/404.html", "status": 200}
+]

package/examples/not-found/urlcode.yaml

@@ -0,0 +1,7 @@
+version: "1"
+site:
+  notFound: public/404.html
+routes:
+  /:
+    page:
+      file: public/index.html

package/examples/shared-blocks/README.md

@@ -0,0 +1,11 @@
+# Shared request and response.headers blocks
+
+```sh
+urlcode test --project examples/shared-blocks
+urlcode routes --project examples/shared-blocks
+```
+
+`shared` names reusable `request` and `response.headers` blocks; a route picks
+one with `use`. `/orders/preview` overrides `request` and keeps the shared
+headers; `/health` overrides `response` and drops the shared headers. `routes`
+prints the resolved result. See [the specification](../../docs/SPECIFICATION.md).

package/examples/shared-blocks/example.yaml

@@ -0,0 +1,17 @@
+id: shared-blocks
+description: Top-level shared request and response.headers blocks that routes select by name with use, resolved at load time.
+tags: [shared, use, reuse, request, response.headers, respond, deduplicate]
+complexity: starter
+capabilities: [enabled, methods, request.body, respond, response.headers]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
+routes: 4
+grants: []
+files: [urlcode.yaml, tests/requests.json, README.md]
+tests:
+  fixtures: tests/requests.json
+  commands:
+    - node src/cli.ts validate --local --project examples/shared-blocks
+    - node src/cli.ts test --project examples/shared-blocks
+    - node src/cli.ts audit --project examples/shared-blocks --expect-routes 4
+behavior:
+  - a route's own request or response key replaces the shared block whole; nothing is deep merged

package/examples/shared-blocks/tests/requests.json

@@ -0,0 +1,7 @@
+[
+  {"path":"/orders","method":"POST","headers":{"content-type":"application/json"},"body":"{\"a\":1}","status":200,"expectBody":"{\"accepted\":true}","expectHeaders":{"cache-control":"no-store","x-api-version":"1"}},
+  {"path":"/orders","method":"POST","status":400},
+  {"path":"/orders/preview","method":"POST","headers":{"content-type":"application/json"},"body":"{\"a\":1}","status":200,"expectHeaders":{"cache-control":"no-store","x-api-version":"1"}},
+  {"path":"/about","status":200,"expectBody":"About this service","expectHeaders":{"cache-control":"public, max-age=300"}},
+  {"path":"/health","status":200,"expectHeaders":{"cache-control":"no-store"}}
+]

package/examples/shared-blocks/urlcode.yaml

@@ -0,0 +1,37 @@
+version: "1"
+# Named blocks a route selects with `use`. Resolved at load time: `urlcode routes`
+# and `urlcode audit` show each route with the block already applied.
+shared:
+  json-api:
+    request:
+      body: {required: true, maxBytes: 4096, contentTypes: [application/json], format: json}
+    response:
+      headers:
+        Cache-Control: no-store
+        X-Api-Version: "1"
+  plain-page:
+    response:
+      headers:
+        Cache-Control: public, max-age=300
+routes:
+  /orders:
+    methods: [POST]
+    use: json-api
+    respond: {json: {accepted: true}}
+  /orders/preview:
+    methods: [POST]
+    use: json-api
+    # The route's own request replaces the shared one as a whole; response.headers still comes from json-api.
+    request:
+      body: {maxBytes: 512, contentTypes: [application/json]}
+    respond: {json: {preview: true}}
+  /about:
+    use: plain-page
+    respond: {text: About this service}
+  /health:
+    use: plain-page
+    # An own response block wins whole: the shared Cache-Control does not leak in.
+    response:
+      headers:
+        Cache-Control: no-store
+    respond: {json: {ok: true}}