@jimhoyd/urlcode 0.4.2 → 0.4.7

package/docs/ORGANIZATION.md

@@ -1,135 +0,0 @@
-# Organize routes your way
-
-`urlcode.yaml` is the project entry point. The rest of the folder structure is
-yours. Use one file for a few links or split routes by feature, team, campaign,
-customer or another useful grouping. Folder names do not create URL prefixes.
-Explicit file composition is already implemented; no new runtime mode is needed.
-
-## One file
-
-```yaml
-# urlcode.yaml
-version: "1"
-routes:
-  /go:
-    redirect:
-      url: https://example.com
-```
-
-## Multiple files and nested folders
-
-The public [urlcode-template](https://github.com/jimhoyd-com/urlcode-template)
-contains a function route and a redirect, organized like this:
-
-```text
-urlcode.yaml
-routes/
-  functions.yaml
-  marketing/
-    links.yaml
-functions/
-  hello.mjs
-tests/
-  requests.json
-```
-
-Entry point:
-
-```yaml
-# urlcode.yaml
-version: "1"
-includes:
-  - routes/functions.yaml
-  - routes/marketing/links.yaml
-routes: {}
-```
-
-Function route:
-
-```yaml
-# routes/functions.yaml
-version: "1"
-routes:
-  /hello:
-    function:
-      source: functions/hello.mjs
-```
-
-Function source for this short example:
-
-```js
-// functions/hello.mjs
-export default function hello() {
-  return Response.json({ message: "Hello!" });
-}
-```
-
-Redirect route:
-
-```yaml
-# routes/marketing/links.yaml
-version: "1"
-routes:
-  /go:
-    redirect:
-      url: https://example.com
-```
-
-These produce `/hello` and `/go`, not `/routes/hello` or `/marketing/go`. The
-actual template adds a validated `{name}` input to the function example. You can
-also colocate code with a feature, for example `features/support/routes.yaml`
-and `features/support/hello.mjs`; use `source: features/support/hello.mjs`.
-
-## Mix inline and included routes
-
-Keep a few common routes in the entry point while splitting larger groups:
-
-```yaml
-version: "1"
-includes:
-  - routes/functions.yaml
-  - routes/marketing/links.yaml
-routes:
-  /status:
-    respond:
-      json: {ok: true}
-```
-
-With the example files above, the combined project has three routes. Update your
-reviewed `--expect-routes` count when adding/removing a route. Simply moving a
-route between files does not change the count or its URL.
-
-## Composition rules
-
-- All file references are relative to the project root containing `urlcode.yaml`,
-  including `includes`, function `source`, and asset `file`/`directory` references.
-  They are never relative to the included YAML file.
-- Each file declares `version: "1"` and `routes`. The entry point uses `routes: {}`
-  when all routes live in includes. `.yaml` and `.yml` work.
-- Includes list explicit files, including paths through nested folders. There is
-  no directory auto-discovery, glob expansion or remote configuration download.
-- Put all includes in `urlcode.yaml`; included files cannot include other files.
-- Duplicate files or route paths fail validation. Include order does not provide
-  overrides or change route-matching precedence.
-- References must stay inside the project. Missing files and escaping symlinks
-  fail validation. Do not use secret files as configuration.
-- Current limits: 256 included files, 32 MiB per YAML file, 64 MiB aggregate YAML and 100,000 total routes. Parser-worker and compilation limits also apply; see [capacity](CAPACITY.md).
-  These limits apply to the combined project, not separately per folder.
-
-`dev` reloads changes to ordinary project YAML files and keeps the last valid
-snapshot if a change is invalid. Configuration in hidden/build/dependency
-folders or behind symlink targets is outside the normal watcher: use ordinary
-source folders or restart after such changes. File grouping does not weaken
-function isolation or operator binding requirements.
-
-`validate`, `routes`, `test`, `audit` and `benchmark` all use the same merged
-project. To move files safely: edit the include list and any changed project-root
-references, validate, then run the audit with the same expected count. Paths
-inside a moved route file need no change when their target files remain in place.
-See the [implemented contract](SPECIFICATION.md) and [readiness guide](READINESS.md).
-
-See [route matching and new links](ROUTING.md) for parameter/wildcard semantics,
-priority rules and activation of newly added definitions.
-
-For layout choices, naming, readable YAML/functions, middleware responsibilities
-and safe refactoring, see [organization and readability practices](BEST-PRACTICES.md).

package/docs/PERFORMANCE.md

@@ -1,72 +0,0 @@
-# Performance checks
-
-Run from the runtime checkout:
-
-```sh
-npm run benchmark -- 1000
-npm run benchmark -- 10000
-npm run benchmark -- 100000
-```
-
-Each invocation generates a temporary literal-redirect collection, measures
-YAML load/compile/server startup, warms up 100 requests, then runs 5,000 real
-loopback HTTP requests with 16 keep-alive connections. It verifies every status
-and destination, never follows redirects, cleans up its process/files and
-prints JSON with hardware/runtime, startup, memory, throughput and latency.
-
-Initial local measurements on 2026-09-16: Apple M4 Pro, 48 GiB RAM, macOS arm64,
-Node 26.8.2. These are short development runs on a shared machine, not an SLA,
-sizing recommendation, soak result or comparison against other products.
-
-| Routes | Startup | RSS after startup | Redirect requests/s | p95 latency |
-|---|---:|---:|---:|---:|
-| 1,000 | 29 ms | 86 MiB | 29,398 | 0.87 ms |
-| 10,000 | 168 ms | 186 MiB | 28,458 | 0.85 ms |
-| 100,000 (after parser fix) | 1,431 ms | 621 MiB | 28,563 | 0.85 ms |
-
-These runs use the improved parser; the original 100,000-route startup took
-42,493 ms. A string-key-only duplicate check reduced that to
-1,431 ms while retaining duplicate rejection tests. Parser transient allocation
-still contributes significantly to RSS; 100k startup exceeds the illustrative
-512 MiB container limit. Do not size from routing data alone.
-
-Before a stable production release, repeat on supported Node 22/24/26 deployment
-hardware, measure long-running memory/reloads and tail latency under sustained
-traffic, include mixed parameter/function workloads and overload/recovery, and
-set regression budgets from repeatable evidence. Worker concurrency and slow
-upstream services need separate tests; literal redirect throughput does not
-predict function throughput. Runtime logs were disabled for these measurements.
-
-The 5,000 measured requests do not exercise every route in the larger datasets.
-Client and server share a process; these runs exclude TLS/proxy overhead and
-production logging. No NGINX comparison has been measured. Use the
-[capacity model](CAPACITY.md) and [recovery drills](RESILIENCE.md) when designing
-a deployment benchmark; do not extrapolate native redirect RPS to middleware.
-
-## TypeScript conversion, 2026-09-17
-
-The runtime source became TypeScript, shipped as `dist/`: Node's own type
-stripping with the specifier extension rewritten, so `dist/x.js` is
-byte-equivalent to `src/x.ts` with the types removed (same lines, same
-columns; no bundling, minification or syntax transform). The published
-package therefore runs the same JavaScript it ran before. Measured on the same
-machine (Intel Xeon 2.80 GHz, 16 GiB, Linux, Node 22.22.2), a plain-JavaScript
-worktree of the pre-conversion commit against `dist/cli.js`, three alternating
-runs each, medians of medians:
-
-| Check | Before (JavaScript source) | After (`dist/`) |
-|---|---:|---:|
-| CLI cold start, `validate --project starters/default` (20 spawns) | 798.6 ms | 797.8 ms |
-| CLI cold start, `routes --project starters/default` | 795.1 ms | 770.9 ms |
-| CLI cold start, `--help` | 331.0 ms | 328.4 ms |
-| `npm run benchmark -- 1000` requests/s (6 runs) | 4,640–4,927 | 4,657–4,914 |
-| `npm run benchmark -- 1000` p95 | 5.77–6.00 ms | 5.65–5.96 ms |
-| `npm run benchmark -- 1000` RSS after startup | 95–100 MiB | 95–100 MiB |
-| `cli benchmark --project starters/default` (function route) | 1,188 req/s, p95 3.50 ms | 1,265 req/s, p95 3.28 ms |
-
-Every difference is inside run-to-run spread; the gates (cold start within 2 %,
-throughput within noise, RSS within 5 MiB) were met. Running the `.ts` source
-directly (`node src/cli.ts`, the developer loop) costs about +190 ms of cold
-start and +35 MiB RSS for the stripping itself; that mode never ships.
-Container time-to-ready was not measured here (no Docker in that environment);
-CI's readiness loop covers it.

package/docs/PLUGINS.md

@@ -1,271 +0,0 @@
-# Host plugins
-
-A plugin is host code an operator passes to the runtime in JavaScript or
-TypeScript. It sees
-every request after the route is matched and before the handler runs, may
-answer it outright, and sees every response before it is written. The
-declarative [policies](POLICIES.md) are implemented on the same hook names,
-so first-party and operator behavior share one code path and one test seam.
-
-Plugins are not part of the project format. Nothing in YAML names a plugin or
-an npm package; the operator application passes them to `startServer`,
-`createRuntime`, `createVercelHandler` or `createLambdaHandler`. A project stays
-portable while an operator can still add a shared-store limiter, a verified-bot
-check or a purge endpoint. Plugins run in the host process with the host's
-privileges: they are the operator's trust boundary, not the project's, and the
-runtime does not sandbox, review or limit what a plugin does with a request.
-Treat a plugin like any other dependency of the operator application.
-
-## Passing plugins
-
-```js
-import { startServer } from '@jimhoyd/urlcode';
-
-await startServer({
-  project: './site',
-  trustedProxies: ['10.0.0.0/8'],
-  plugins: [auditPlugin],
-});
-```
-
-`createRuntime(project, { plugins })` takes the same array for embedding
-without the HTTP server. `createVercelHandler({ plugins })` and
-`createLambdaHandler({ plugins })` pass it through to the adapter's runtime
-with the target set to `vercel` or `aws`. The Cloudflare build takes no
-plugins: the Worker carries only compiled policies. `runtime.plugins` lists
-the activated `{ name, version }` pairs.
-
-## Plugin shape
-
-```js
-const auditPlugin = {
-  name: 'audit',                 // ^[a-z][a-z0-9-]{0,63}$, unique per runtime
-  version: '1.0.0',              // any string up to 64 characters
-  targets: ['node', 'vercel'],   // subset of node, vercel, aws, cloudflare
-  credentialHeaders: ['Cookie', 'Authorization'], // optional; withheld from guests
-  async onActivate(runtime) {},                    // may throw to refuse activation
-  async onRequest(request) {},                     // return a result to short-circuit
-  async onResponse(request, result) { return result; }, // return the result to send
-  onError(request, error) {},                      // observe a thrown error
-  async onClose() {},                              // release resources
-};
-```
-
-The package ships declarations for this contract: `Plugin` and
-`PluginRuntime` (what `onActivate` receives) from `@jimhoyd/urlcode/plugins`, with
-`PolicyRequest`, `HandlerResult`, `HeaderPair`, `TargetName` and `TestPlan`
-re-exported beside them, and `HostPlugin` (the same type) from `urlcode`. The
-same plugin in TypeScript:
-
-```ts
-import type { Plugin, PolicyRequest, HandlerResult } from '@jimhoyd/urlcode/plugins';
-
-const auditPlugin: Plugin = {
-  name: 'audit',
-  version: '1.0.0',
-  targets: ['node', 'vercel'],
-  onRequest(request: PolicyRequest): HandlerResult | undefined {
-    if (request.path === '/deny') return { status: 451, headers: [], body: new Uint8Array(0) };
-    return undefined;
-  },
-  onResponse(request, result) { return { ...result, headers: [...result.headers, ['x-plugin', 'seen']] }; },
-};
-```
-
-Validation happens at activation, before any request: at most 32 plugins,
-each an object with a kebab-case `name` no other plugin uses, a `version`
-string and a `targets` array of known target names; every declared hook must
-be a function and at least one must be present. A plugin whose `targets` does
-not include the runtime's target is refused with
-`Plugin "name" does not support the vercel target`, mirroring how adapters
-refuse routes, so the same operator application fails fast where a plugin's
-assumptions do not hold.
-
-`onActivate(runtime)` receives `{ testPlan(), version, root, target }`.
-`testPlan()` returns the route inventory (`inventory[].policies` names the
-effective policies per route) and `policies`, the per-route policy summaries
-with their `target` value, so a plugin can inspect what it is joining and
-throw to refuse. Hooks may be async; the runtime awaits them.
-
-## The request object
-
-Every request hook receives the same object the policies see, built once per
-request by `policyRequest` in `src/policies.ts`:
-
-| Field | Value |
-|---|---|
-| `method` | Request method, upper case |
-| `target` | Raw request target (path plus query string) as received |
-| `path` | Parsed path |
-| `params` | Route parameter values by name |
-| `query` | Parsed query as `URLSearchParams` |
-| `headers` | Request `Headers` |
-| `headerCounts` | Occurrences per header name, lower case, so a duplicated scalar header can be detected (empty on Cloudflare, where the platform joins repeats) |
-| `client` | Client address as the host resolved it through `--trusted-proxies` or the platform's connection address, or `null` when none could be resolved. Never a raw forwarded header |
-| `origin` | Public origin the runtime was told (`--origin`, `URLCODE_ORIGIN` or the platform's), used for HSTS and absolute URLs |
-| `route` | The matched route's configured pattern, never request text |
-| `secrets` | `true` when the route declares secret bindings |
-
-The object identity is stable for the life of the request, so a plugin may key
-a `WeakMap` on it to carry state from `onRequest` to `onResponse`. Nothing on
-it reaches the guest: there is no sandbox handle, no deadline, no `env` or
-`secrets` values and no binding. A plugin cannot extend or shorten a function's
-deadline, read or write guest state, or obtain a binding the operator policy
-did not grant to the route.
-
-## Withholding credential headers from application code
-
-An operator plugin may declare `credentialHeaders: ['Cookie', 'Authorization']`.
-Each list contains at most 64 unique HTTP header names, compared
-case-insensitively, each at most 128 characters. The runtime validates the lists
-and captures their union before activation hooks run. Later mutation of a plugin
-object does not weaken the running boundary; a reload captures a new declaration.
-No YAML key can enable, disable or override this operator setting.
-
-The union applies to every matched route in that runtime, including public
-functions and guest middleware on native routes. Before processing application
-inputs, the runtime makes a separate header copy and removes those names. Guest
-`Request.headers`, `ctx.inputs.header` and header-derived `ctx.args` receive no
-corresponding values. Header schema defaults are also omitted from the guest
-context for those names. A required protected header input without a default fails with
-`Missing required parameter`, even when the original request supplied it;
-projects should not declare credential inputs that the operator withholds.
-Native redirect query mappings also use this sanitized application context, so
-they cannot reflect a withheld header into a response visible to middleware.
-Selecting `Cookie` removes the entire header, not just one named cookie.
-
-Host request/response/error hooks, first-party policies and request-body checks
-retain the original headers. The runtime does not mutate the caller's Headers
-object. Existing applications behave exactly as before when no plugin declares
-credential headers. Plugins still need at least one lifecycle or request hook;
-a header list alone is not a complete plugin.
-
-This is a data boundary, not authentication, authorization or cache protection.
-It does not create a principal, validate a token, protect a route, or prevent
-shared caching. In particular, withholding Cookie or Authorization from guests
-does not make a personalized response safe to cache. Operators must separately
-configure the appropriate authentication and cache behavior. It also does not
-redact URL/query/body content, explicit binding grants, logs or values deliberately
-reflected by trusted host plugins. Host plugins retain full access to the request
-and remain trusted operator code.
-
-## Results
-
-A result is what the runtime writes:
-
-```js
-{ status: 429, headers: [['content-type', 'text/plain; charset=utf-8'], ['retry-after', '30']], body: Buffer.from('Too many requests\n') }
-```
-
-`headers` is an array of `[name, value]` pairs; `body` is a `Buffer`
-(a `Uint8Array` on Cloudflare). `onRequest` returns such a result to answer the
-request without running the handler, or `undefined` to continue. `onResponse`
-returns the result to send; returning `undefined` keeps the one it was given.
-Replace rather than mutate. Every result still passes through the shared
-response writer on the way out: the status must be an integer from 200 to 599,
-header names and values are validated (an invalid one fails the request as a
-function's would), hop-by-hop headers and `Content-Length` are dropped and
-recomputed, `X-Request-Id` and `X-Content-Type-Options: nosniff` are added, and
-`Cache-Control: no-store` is added when the result carries no `Cache-Control`.
-HEAD and 204/205/304 results are sent without a body.
-
-## Ordering
-
-Plugins wrap everything else. On the request side the first plugin in the
-array runs first, then the second, then the policies (`agents`, `throttle`,
-`cache`), then the route contract and the handler. On the response side the
-policies run, then plugins in reverse: the first plugin sees the request first
-and the response last, the standard onion. A short-circuit from any
-`onRequest` skips the remaining plugins, every policy request hook and the
-handler, and goes straight to the response side; the response hooks of
-policies with a request phase are skipped for it (nothing is cached, no
-rate-limit headers), security headers and compression still apply, and every
-plugin's `onResponse` still runs.
-
-`onError` hooks run in reverse order for an error the runtime throws after
-the request object exists (404 for a disabled route is thrown before it; a
-405 is an ordinary result and reaches `onResponse`). They observe only: a
-throw inside `onError` is swallowed and the outcome stands. A policy's error
-hook may answer with a fallback instead; when one does, plugin `onError`
-hooks do not run and plugin `onResponse` hooks see the fallback (no
-first-party policy returns one today). `onClose` runs in reverse order when
-the runtime closes, after the policies have released their state; a throw
-there is ignored.
-
-On a reload the same plugin objects are activated again: `onActivate` runs
-for the new runtime before `onClose` runs for the retired one, so plugin
-state persists unless `onClose` discards it. An `onActivate` that throws
-rejects the reload and the old runtime keeps serving.
-
-## What a plugin cannot do
-
-- Reach inside the guest, extend a deadline or see bindings: the request
-  object carries none of those, and there is no other handle.
-- Change a project's routes or policies after activation; `onActivate` can
-  refuse, not rewrite.
-- Be selected from YAML. A project cannot require a plugin, and a plugin's
-  presence does not change how the project validates.
-- Change a thrown error's status or body from `onError`.
-- Run on Cloudflare: the Worker carries compiled policies only.
-
-## Sketches
-
-Both examples are sketches, not shipped code: they omit error handling,
-configuration and the store or verifier they depend on.
-
-### Shared-store throttle
-
-The built-in `throttle` keeps counters per instance. Across replicas an
-operator needs a shared store; a plugin keys it on the resolved client and the
-route pattern, both of which the request object already carries.
-
-```js
-// Sketch. `store.increment(key, windowSeconds)` is a fixed-window counter
-// in a shared store and returns the count after increment.
-export function sharedThrottle({ store, quota, window }) {
-  return {
-    name: 'shared-throttle', version: '0.1.0', targets: ['node', 'vercel', 'aws'],
-    async onRequest(req) {
-      const key = `${req.route}|${req.client ?? 'shared'}`;
-      const used = await store.increment(key, window);
-      if (used <= quota) return undefined;
-      return {
-        status: 429,
-        headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store'], ['retry-after', String(window)]],
-        body: Buffer.from('Too many requests\n'),
-      };
-    },
-  };
-}
-```
-
-Combine it with `policies.throttle: false` on the routes it covers, or keep
-the built-in policy as a per-instance ceiling underneath it.
-
-### Verified-bot allow
-
-The `agents` policy matches strings only. Verifying that a request claiming to
-be a search crawler really comes from one (reverse DNS as the major engines
-document, or an HTTP Message Signature per the web-bot-auth drafts) needs a
-network lookup and a cache, so it is a plugin. The sketch answers 403 to a
-claimed crawler whose address does not verify and lets everything else
-continue to the `agents` policy.
-
-```js
-// Sketch. `verify(address)` resolves the address back to the crawler's
-// documented domains and caches the answer; it is not part of the runtime.
-export function verifiedBots({ verify, claims = /Googlebot|bingbot/i }) {
-  return {
-    name: 'verified-bots', version: '0.1.0', targets: ['node'],
-    async onRequest(req) {
-      const agent = req.headers.get('user-agent') || '';
-      if (!claims.test(agent) || !req.client) return undefined;
-      if (await verify(req.client)) return undefined;
-      return { status: 403, headers: [['content-type', 'text/plain; charset=utf-8'], ['cache-control', 'no-store']], body: Buffer.from('Forbidden\n') };
-    },
-  };
-}
-```
-
-A plugin that logs should follow the policies' rule: record the route pattern
-and the outcome, not the client address or the User-Agent string.