@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/LOAD-TESTING.md

@@ -1,91 +0,0 @@
-# Load testing a deployment
-
-`urlcode benchmark` sends a project's own workload at a running runtime and
-reports throughput, tail latency and how many requests were refused. It answers
-one question — *does this deployment meet its budget under this load* — and
-nothing else. It is not a capacity model, not a soak harness and not a
-substitute for the drills in [release readiness](RELEASE-READINESS.md).
-
-## Measure the deployment, not a fresh local snapshot
-
-By default the command starts a private runtime and loads that. Useful for a
-regression budget in CI; useless for judging a deployment, because it bypasses
-your TLS termination, proxy, network and host.
-
-`--target` sends the same workload at something already running:
-
-```sh
-urlcode benchmark --project . --target https://links.example \
-  --requests 5000 --concurrency 8 --warmup 100 --max-p95-ms 50
-```
-
-The project is still required: it supplies the routes and fixtures that make up
-the workload. Load goes to the target; the local runtime is only consulted for
-the plan. `rssMiB` is `null` in this mode, because the memory of the machine
-running the benchmark says nothing about the machine under test.
-
-Point `--target` only at systems you operate. A load generator aimed at someone
-else's host is an attack, whatever the intent.
-
-## Warm up before measuring
-
-`--warmup N` sends and discards N requests first. A cold asset snapshot, an
-empty connection pool and a just-started function worker are not what a latency
-budget is about. Warm-up traffic reaches the deployment and is excluded from
-every statistic; `warmupRequests` records how many.
-
-## Reading the report
-
-| Field | Meaning |
-|---|---|
-| `pass` | Every request completed, none failed, and `p95Ms` met `--max-p95-ms` if given. |
-| `completed` / `complete` | How many requests ran. Short of `requested` means the `--seconds` budget ended the run first — the numbers describe a shorter run than you asked for. |
-| `failed` | Responses that did not match the expectation for that case. |
-| `transportErrors` | Connections that never produced a response: refused, reset or timed out. Distinct from a deployment deliberately refusing work. |
-| `shedResponses` | 503 and 504 responses — admission, function-pool capacity or a deadline. Not errors so much as the runtime protecting itself. |
-| `p50Ms` / `p95Ms` / `p99Ms` | Latency percentiles over completed requests. |
-| `statuses` | Full status histogram, so a "pass" that is secretly all redirects is visible. |
-| `rssMiB` | Local mode only. |
-
-## A worked example
-
-Against the default starter, which has one function route:
-
-```
-$ urlcode serve --project starters/default --port 3456
-$ urlcode benchmark --project starters/default --target http://127.0.0.1:3456 \
-    --requests 60 --warmup 10 --concurrency 4
-pass: false   failed: 6   shedResponses: 6   p95Ms: 6.7
-```
-
-Six of sixty requests were shed. Not a bug: `serve` runs **2 function workers**
-by default, so a concurrency of 4 exceeds the pool and the runtime returns 503
-rather than queueing without bound. Raising the pool:
-
-```
-$ urlcode serve --project starters/default --port 3457 --workers 8
-$ urlcode benchmark ... --concurrency 4
-pass: true    failed: 0   shedResponses: 0   statuses: {"200":24,"302":36}
-```
-
-That is the loop this tool exists for: measure, read `shedResponses`, tune the
-[capacity controls](CAPACITY.md), measure again. More workers cost memory and
-CPU; the right number is the one your workload and host justify, not the
-largest one that makes a number go green.
-
-## What a passing run does not prove
-
-- **GET and HEAD only.** Function routes with request bodies are not exercised.
-  `workload` states this in every report.
-- **Redirects are not followed**, so a redirect's destination is never loaded.
-- **One client, one host, no slow peers.** Tail latency under adversarial
-  clients, connection churn or packet loss is not measured.
-- **Not a soak.** `--seconds` caps at 300. Memory drift, file-descriptor leaks
-  and log-volume growth need a long run watched through
-  [monitoring](MONITORING.md).
-- **A number from one environment is not a claim about another.** Record the
-  runtime and application revisions, host, and command with any figure you keep.
-
-`scripts/operational-drills.ts` covers the adjacent ground — mixed
-native/function load, an invalid reload and rollback — as a local proof,
-never a statement about production.

package/docs/LOCAL-DEVELOPMENT.md

@@ -1,102 +0,0 @@
-# Local development
-
-Use Node.js 22.18+ and npm (CI targets Node 22, 24 and 26). The runtime is
-written in TypeScript and runs from source with no build step: `npm run dev`
-is `node src/cli.ts`, which Node runs through its own type stripping (that is
-why a contributor needs 22.18, while an installed package still runs on 22.13).
-`npm run typecheck` is the type gate and part of `npm run verify`.
-`npm run build` emits the JavaScript in `dist/` that the package and container
-ship, together with the declarations; `dist` is never committed. Make is an optional
-shortcut layer; npm and the CLI work on Windows, macOS and Linux. No global
-package install, hosting account, database or Docker is needed for the local loop.
-
-For the repository's prose-only checks, CI selection and release helper commands,
-see [the development pipeline](DEVELOPMENT-PIPELINE.md).
-
-## Try the runtime
-
-From the runtime checkout, `make dev` installs locked dependencies if needed and
-starts the function/redirect starter at http://127.0.0.1:3000. Without Make, run `npm ci`
-once, then `npm run dev`. Dependency installation requires npm registry access;
-the examples themselves work locally.
-
-Try `/hello/Ada` (sandboxed function) and `/go` (redirect).
-For pages/files/downloads, run `make dev PROJECT=examples/assets` instead. Edit the files in
-`starters/default/` to experiment. `dev` watches configuration, source and assets;
-invalid edits leave the last valid snapshot running. Ctrl+C drains and stops it.
-Runtime source changes under `src/` require restarting the dev command; project
-reload is not a runtime-code watcher.
-
-## Own an application
-
-Run `make init DEST=../my-links`, then
-`make dev PROJECT=../my-links`. The CLI equivalents from the runtime checkout:
-
-```sh
-npm run init -- ../my-links
-npm run dev -- --project ../my-links
-npm run validate -- --project ../my-links
-npm run test:project -- --project ../my-links
-```
-
-There is one starter, containing both examples. Initialization never overwrites
-an existing directory. Once created, edits belong to your app repository; upgrading
-the runtime does not regenerate them. Each starter has a Makefile for its own
-`dev`, `serve`, `validate`, `test` and `doctor` commands. It uses an installed
-`urlcode`, or an explicit runtime command:
-
-```sh
-cd ../my-links
-make dev URLCODE='node /path/to/urlcode/src/cli.ts'
-# Without Make or a global install:
-node /path/to/urlcode/src/cli.ts dev
-```
-
-## Command reference (runtime checkout)
-
-| Make | npm | Purpose |
-|---|---|---|
-| `make setup` | `npm ci` | Install exact dependencies; replaces node_modules |
-| `make dev` | `npm run dev` | Watched function/redirect starter, local dotenv |
-| `make validate` | `npm run validate` | Validate the app and local bindings |
-| `make test-project` | `npm run test:project` | App HTTP assertions, redirects not followed |
-| `make test` | `npm test` | Runtime unit, HTTP and sandbox tests |
-| — | `npm run typecheck` | Strict TypeScript check of runtime, scripts, tests and benchmarks |
-| `make verify` | `npm run verify` | Lint, type check, syntax/JSON checks and runtime tests |
-| — | `npm run build` | Emit `dist/` (stripped JavaScript and declarations); never committed |
-| `make test-package` | `npm run test:package` | Actual archive install and starter tests; registry access |
-| `make serve` | `npm run serve` | Fixed snapshot, no watcher or dotenv |
-| `make doctor` | `npm run doctor` | Runtime/platform details |
-
-Run `make help` for shortcuts. `PROJECT` defaults to `starters/default`; `HOST`
-to `127.0.0.1`; `PORT` to `3000`. Quote paths containing spaces:
-
-```sh
-make dev PROJECT="../my-links demo" PORT=3001
-npm run dev -- --project "../my-links demo" --port 3001
-```
-
-Make automatically runs `npm ci` when its dependency marker is missing or older
-than package metadata. Use `make setup` after manually changing node_modules.
-Do not run setup concurrently with a running dev server or tests.
-
-## Environment and troubleshooting
-
-`.env.local` belongs in the selected app directory and is ignored by Git; process
-environment values take precedence. No starter requires secret values. Do not
-copy placeholder credentials into a working secret store. External env/secret
-bindings still need an operator policy outside the app, pinned to its config/code.
-Inspect and set it up using the [security guide](FUNCTION-SECURITY.md); pass it
-through the CLI, for example `npm run dev -- --project ../my-links --policy /path/to/policy.json`.
-Local convenience never bypasses the function sandbox or grants permissions.
-
-- Port busy: change `PORT=3001` or pass `--port 3001` through npm.
-- Missing Make: use the npm commands; Make is not a runtime dependency.
-- Invalid edits: run validation for diagnostics; fix the project and the watcher retries.
-- Changed runtime source: stop and restart dev, then `npm run typecheck`. Changed app source: reload is automatic.
-- Missing dependency or wrong Node: check `node --version`, then `npm ci`.
-- Need access from another device: explicitly use `HOST=0.0.0.0` or `--host 0.0.0.0`;
-  this exposes the development listener to your network. Loopback remains the default.
-
-Production deployment uses `serve` behind the HTTPS setup described in
-[operations](OPERATIONS.md). These shortcuts do not provision providers or select a license.

package/docs/MIDDLEWARE-EXAMPLES.md

@@ -1,75 +0,0 @@
-# Middleware examples
-
-Fourteen reusable middleware modules covering fifteen patterns (`auth.mjs`
-exports both `bearer` and `basic`), each in
-[`examples/cookbook/middleware`](../examples/cookbook/middleware) with a route in
-[`routes/middleware.yaml`](../examples/cookbook/routes/middleware.yaml) and request
-fixtures in the cookbook tests. The same modules ship as the `middleware`
-[local recipe](RECIPES.md):
-
-```sh
-urlcode recipes add middleware --out ./my-middleware
-urlcode test --project ./my-middleware
-```
-
-They cover what Express, Koa, Fastify, Hono, Next.js and edge runtimes usually
-ship as middleware, rewritten for URLCode's [guest API](MIDDLEWARE.md): text/JSON
-`Request`/`Response`, `Headers`, `context.inputs/args/env/secrets/state`, timers
-and nothing else. There is no `crypto`, `URL`, `fetch`, storage or console, and
-`context.state` dies with the request. Patterns that need any of those are listed
-at the end so nobody wastes time porting them.
-
-| Pattern | Module | Framework equivalent | Demonstrates |
-| --- | --- | --- | --- |
-| Bearer token gate | `auth.mjs` `bearer` | Hono `bearerAuth`, `express-bearer-token` | Early 401, `www-authenticate`, constant-time compare against an `env` binding |
-| Basic authentication | `auth.mjs` `basic` | Hono `basicAuth`, `express-basic-auth` | Hand-written base64 (no `atob`), both checks always evaluated, `state.user` |
-| CORS | `cors.mjs` | Express `cors`, Hono `cors` | `OPTIONS` answered before the handler, origin allowlist, `vary: origin` |
-| Correlation id and timing | `request-id.mjs` | Hono `requestId`/`timing`, Express `response-time` | Validating a caller header, `server-timing`, coexisting with the runtime's own `x-request-id` |
-| Maintenance switch | `maintenance.mjs` | Next.js and Netlify Edge maintenance examples | 503 with `retry-after`, bypass header, flipping behavior from a binding |
-| Error boundary | `errors.mjs` | Koa `onerror`, Express error handlers | Catching a downstream throw, JSON 500 instead of a bare 502 |
-| JSON envelope | `envelope.mjs` | Response transformers | Reading a function body once, passing native bodies through untouched |
-| Content negotiation | `negotiate.mjs` | Express `res.format` | Parsing `accept` with q-values, 406, `vary: accept` |
-| Method override | `methods.mjs` `override` | Express `method-override` | Bounded tunneling through POST, 405 with `allow` |
-| ETag and 304 | `etag.mjs` | Express `etag`, Fastify `@fastify/etag` | FNV-1a weak tag, `if-none-match`, null-body 304 |
-| A/B bucket | `bucket.mjs` | Vercel and Cloudflare A/B examples | Cookie parsing, `set-cookie`, replacing a native redirect |
-| Locale redirect | `locale.mjs` | Next.js i18n middleware | `accept-language` ranking, allowlisted languages, `vary` |
-| Referer allowlist | `referer.mjs` | Hotlink protection rules | Gating a native download without reading it |
-| Body validation | `body.mjs` | `express-validator`, Fastify schemas | Single-use body, 422 error list, handoff through `state` |
-| Debug echo | `debug.mjs` | Request loggers | Inspecting inputs, args and redacted headers when the console is silent |
-
-## Reading the modules
-
-Every module follows the shape in [middleware](MIDDLEWARE.md): read the request,
-optionally return early, otherwise `await next()` once and return a `Response`.
-Three habits recur and are worth copying:
-
-- **Configuration lives in bindings.** Tokens, allowlists and switches are read
-  from `context.env`. The cookbook binds literal values so it runs without grants;
-  a deployed project uses `{secret: name}` for credentials and an operator grant.
-- **Native bodies stay opaque.** `envelope`, `negotiate` and `etag` only rewrite a
-  body when the downstream response is a function response with a readable
-  content type. `bucket`, `locale` and `referer` wrap native redirects and
-  downloads without touching their bytes; to change the destination they return
-  a new `Response` instead.
-- **Chains compose through `state`.** `/fragile` runs `request-id` before
-  `errors`, so the fallback JSON carries the correlation id. `/profile` parses
-  the body once in middleware and the function reads `context.state.body`.
-
-## Limits these examples respect
-
-- **No `crypto`.** The auth modules compare a shared token; they cannot verify
-  HMAC signatures, JWTs or password hashes. Signed URLs would be a runtime
-  feature, not a middleware example.
-- **No cross-request state.** Rate limiting, caching, sessions and CSRF tokens
-  need storage the guest does not have. Throttling and cache headers exist as
-  native [policies](POLICIES.md) instead.
-- **No logging target.** The guest console is a no-op; `debug.mjs` returns the
-  information to the caller instead, and only when both a binding and a header
-  ask for it. Remove that route before publishing a project.
-- **Runtime headers win.** The runtime stamps `x-request-id` on every response,
-  which is why the tracing example uses `x-correlation-id`. YAML
-  `response.headers` also override middleware headers.
-
-Each cookbook route has fixtures for its success path, its early responses, its
-validation failures and every declared method, which is what `urlcode audit`
-expects before it reports a middleware-wrapped route as covered.

package/docs/MIDDLEWARE.md

@@ -1,102 +0,0 @@
-# Middleware
-
-Middleware is reusable JavaScript around any route handler. It is optional and
-route-local; plain redirects and assets retain their native fast path when no
-middleware is attached. Middleware runs trusted and unsandboxed by default,
-in-process with full Node access, the same as a `function` route; add
-`sandbox: true` on the route to run the whole chain isolated instead (see
-[trust model and sandbox opt-in](FUNCTION-SECURITY.md)).
-
-```yaml
-version: "1"
-routes:
-  /go:
-    middleware:
-      - source: middleware/headers.mjs
-        export: default
-    redirect:
-      url: https://example.com
-```
-
-```js
-export default async function headers(request, context, next) {
-  context.state.startedAt = Date.now();
-  const response = await next();
-  response.headers.set('x-example-middleware', 'active');
-  return response;
-}
-```
-
-Paths resolve from the project root. Up to 16 entries are allowed; each accepts
-`source` and optional `export` (default `default`). Reuse a module across routes.
-There are no global middleware settings or middleware-specific argument fields.
-This is URLCode's small portable API, not Express/Node middleware compatibility.
-Fourteen ready-to-copy patterns (auth, CORS, tracing, error boundary, ETag and
-more) are in [middleware examples](MIDDLEWARE-EXAMPLES.md).
-
-## Order and responses
-
-For `[first, second]`, execution is first-before, second-before, handler,
-second-after, first-after. Call `await next()` to obtain the downstream response.
-Call it at most once, during the middleware invocation, with no arguments.
-Always return a `Response`. Return early to skip downstream middleware and the
-handler, for example `return new Response('Denied', {status: 403})`.
-Middleware may catch downstream JavaScript exceptions and return a fallback.
-
-Every middleware and the function share the same request and context. Validated
-`inputs`, function `args`, and route-scoped `env`/`secrets` are available along
-with a fresh `context.state` object for this chain. State never survives the
-request. Header edits are visible downstream; editing the request does not
-reroute it or change already validated inputs. Request bodies are single-use:
-reading one consumes it for downstream code. On a `sandbox: true` route there is
-no `clone()` or streaming API at all, so pass parsed data through
-`context.state`; a trusted route receives Node's own `Request`/`Response` and so
-does have `clone()`, but passing parsed data through `context.state` keeps the
-chain portable between the two modes.
-
-Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. On a `sandbox: true` route, native
-redirect/respond/page/static/download bodies are opaque and cannot be read
-through `text()` or `json()`; a trusted chain receives them as an ordinary
-`Response` and can read them, so wrapping `respond: {text: hello}` and returning
-`HELLO` works there and fails in the guest.
-Returning the same native response preserves original bytes, including binary
-files, ranges and HEAD lengths. You may add headers, but cannot change its
-original status or existing native headers while preserving that body. To replace
-status, destination or content, return a new `Response` instead. Replacement
-responses follow the normal response size limits, and (on a `sandbox: true`
-route) the guest's text/JSON constraints. To wrap a shared
-template around file content, render it through a function at build time and
-publish the result: see [prerendering](PRERENDER.md).
-
-Route selection, enabled/expiry checks, methods and input/body validation run
-before middleware. Their errors do not pass through the chain. A missing file
-inside a selected static mount is a downstream 404 response. YAML
-`response.headers` apply last and override matching middleware headers. Runtime
-framing and asset metadata protections still apply.
-
-## Trust, isolation and testing
-
-The whole chain and handler run as one unit, in one execution mode, chosen by
-the route's `sandbox` field — not a per-middleware-entry choice. By default
-(`sandbox` false/absent) that means trusted, in-process execution with full
-Node access and no fixed worker-pool ceiling. With `sandbox: true` it means
-one fresh QuickJS/WASM guest with one memory budget and one deadline: no
-Node, filesystem, shell, fetch or ambient environment, and modules limited to
-this route's declared dependency graph. Either way, all middleware on a route
-receive that route's approved bindings, so review the whole chain; source
-changes invalidate grants. See [trust model and sandbox opt-in](FUNCTION-SECURITY.md).
-
-Invalid responses and repeated `next()` calls fail with 502, and the deadline
-returns 504 either way. A `sandbox: true` chain also sheds load with 503 when
-the shared worker pool is exhausted, and cannot extend the deadline or catch
-the outer worker termination; forgotten downstream work is still drained
-within it. A trusted chain has no worker pool to exhaust (see
-[capacity](CAPACITY.md)), but its deadline is a race against the call's own
-promise rather than a forced kill — it cannot preempt code that blocks the
-event loop synchronously.
-
-Include explicit request fixtures for middleware-wrapped routes: test success,
-early responses, validation failures and every configured method. Audit will
-report missing coverage instead of assuming native handler behavior. Benchmark
-with middleware enabled to measure its actual overhead, sandboxed or trusted.

package/docs/MONITORING.md

@@ -1,115 +0,0 @@
-# Monitoring a URLCode deployment
-
-URLCode emits one JSON object per line on stdout, answers two unauthenticated
-probes and, when an operator opts in, serves in-process counters in Prometheus
-format. Everything below is built from those sources, and the example
-configuration in [`examples/monitoring/`](../examples/monitoring/) is the
-runnable form of it. The contract behind all of it (the event catalogue, the
-observer interface for in-process sinks, the metrics snapshot and the
-exposition endpoint) is in [observability](OBSERVABILITY.md).
-
-What you can measure is shaped by a deliberate logging decision: records carry
-**no URL, query string, header, body, binding or user exception text**. You can
-alert on error rates and latency per configured route; you cannot get per-URL
-analytics from these logs, and adding it would mean logging user data. See
-[operations](OPERATIONS.md).
-
-## Probes
-
-| Endpoint | Meaning | Alert when |
-|---|---|---|
-| `GET /_urlcode/health` | The process is alive and not shutting down. | It fails at all (`UrlcodeDown`). |
-| `GET /_urlcode/ready` | The active snapshot and every function worker are available. | It fails for longer than replacement takes (`UrlcodeNotReady`). |
-
-Both return `{status, version, routes}`. A third endpoint,
-`GET /_urlcode/metrics`, exists only with `startServer({ metrics: true })` and
-answers 404 otherwise; see [metrics](#metrics) below. Keep both: alerting only on health hides
-a process that is up and serving nothing, while alerting only on readiness pages
-for a brief, self-healing worker replacement. Probes have their own bounded
-admission budget (`--max-in-flight-health`), so they keep answering while the
-application sheds load — but they are unauthenticated and disclose the
-configuration digest and route count, so keep them internal.
-
-## Log records
-
-| Event | Fields | Why it matters |
-|---|---|---|
-| `request` | `requestId`, `status`, `durationMs`; plus `method` and `route` with `--request-log detailed` | Error rate and latency per route. `route` is the configured pattern such as `/u/{id}`, never the requested path. |
-| `reload` | `status` (`ok`/`rejected`); `version` and `routes` on `ok` | A `rejected` reload means the last-good snapshot is still serving and a deploy did not take effect. |
-| `watch` | `status` | Development watcher failure; not used by `serve`. |
-| `function_worker` | `status` (`started`/`restarting`), `slot`; `attempt` and `delayMs` on `restarting` | Sustained `restarting` means a function is failing on real traffic. |
-| `logs_dropped` | `count` | The logger shed records because the collector fell behind. Every other signal is unreliable while this fires. |
-| `observer` | `status` (`failed`), `name` | An in-process observer threw; the request was unaffected. Written to the log only, never to observers. Sustained failures mean the observer's own sink is broken. |
-| `throttle`, `agents`, `cache` | `route`, `outcome`; `remaining` or `list` | Policy decisions; see [policies](POLICIES.md). `throttle` logs `allowed` only in report mode. |
-| `site` | `key`, `path`, `status` (`generated`/`shadowed`); or `severity` (`info`/`warning`) and `message` | Activation records for [site conventions](SITE.md). `shadowed` means a declared route took the path; an `info`/`warning` line reports an omitted `Sitemap:` line (no `--origin`), skipped list names or a far-future `security.txt` expiry. |
-
-Startup prints `listening` with the effective `origin`, which is what functions
-and absolute URLs see. Behind a proxy or tunnel this must be your public origin;
-forwarded headers are deliberately not trusted. See [tunnels](TUNNELS.md).
-
-## Metrics
-
-`startServer({ metrics: true })` serves `GET /_urlcode/metrics` in Prometheus
-text format: requests by status class and by configured route, in-flight
-gauges, shed 503s, reloads, worker restarts and healthy slots, policy
-outcomes, dropped logs and observer errors, all prefixed
-`urlcode_`. The same numbers are available in process as `app.metrics()`. The
-endpoint shares the probes' admission budget and bind host and is off by
-default; it discloses route patterns and traffic shape, so keep it internal
-like the probes. [`examples/monitoring/prometheus-scrape.yaml`](../examples/monitoring/prometheus-scrape.yaml)
-scrapes it directly, without a log pipeline. Field names and label sets are
-fixed in [observability](OBSERVABILITY.md).
-
-If you would rather keep everything in one process, an observer passed as
-`startServer({ observers })` receives every log record and a periodic metrics
-snapshot; the same page shows an OpenTelemetry sketch.
-
-## What to alert on
-
-The example rules in
-[`examples/monitoring/prometheus-rules.yaml`](../examples/monitoring/prometheus-rules.yaml)
-cover:
-
-- **`UrlcodeDown`** — liveness probe failing. Process-level; check the supervisor.
-- **`UrlcodeNotReady`** — readiness failing for more than a few minutes.
-- **`UrlcodeServerErrors`** — over 5% 5xx on a route. 502 is a function error,
-  503 is capacity, 504 is a deadline.
-- **`UrlcodeCapacityShedding`** — sustained 503. Raise `--max-in-flight` or
-  `--workers`, or find what is occupying the pool.
-- **`UrlcodeWorkerRestartLoop`** — replacement backs off but never stops, so a
-  persistent cause appears as a steady restart rate rather than a stopped pool.
-  This is the signal that a function is exceeding its deadline on real traffic.
-- **`UrlcodeLogsDropped`** — the collector is behind, so the other rules are
-  blind until it recovers.
-
-Pick service objectives for your own application; these thresholds are a
-starting point, not a recommendation for your workload.
-
-## Wiring it up
-
-1. Send the process's stdout to a collector. The runtime never writes log files
-   and owns no rotation or retention; that belongs to the collector.
-2. Get counters either by scraping `/_urlcode/metrics` (enable `metrics`
-   and load [`examples/monitoring/prometheus-scrape.yaml`](../examples/monitoring/prometheus-scrape.yaml))
-   or by deriving them from the JSON records — see
-   [`examples/monitoring/vector.toml`](../examples/monitoring/vector.toml), which
-   produces `urlcode_requests_total`, `urlcode_worker_restarts_total` and
-   `urlcode_logs_dropped_total`. Fluent Bit, Promtail and Alloy work equally
-   well; the field names are what matter. The endpoint labels requests by
-   `status_class` where the log pipeline keeps the exact `status`; the example
-   rules carry both forms.
-3. Probe both endpoints with blackbox_exporter — see
-   [`examples/monitoring/blackbox-jobs.yaml`](../examples/monitoring/blackbox-jobs.yaml).
-4. Load the alert rules and set the thresholds to your objectives.
-
-Latency percentiles need a histogram; `durationMs` is per record, so have the
-log pipeline bucket it rather than averaging in the alert.
-
-## What this does not give you
-
-Dashboards here describe one process. There is no built-in tracing, no
-per-URL analytics, no distributed aggregation, no metrics persistence across
-restarts and no automatic capacity management. The example configuration is a starting point that has not been
-run against a production workload; validate it in your own environment before
-relying on it, and run the drills in
-[release readiness](RELEASE-READINESS.md) before treating any of it as proof.