@databehave/server 0.1.1 → 0.1.3

package/docs/config/mock-mode.md

@@ -1,84 +0,0 @@
-# `mockMode`
-
-```jsonc
-"mockMode": {
-  "enabled":             true,
-  "header":              "x-mock-status",
-  "healthPaths":         ["/health", "/healthz", "/api/v1/health"],
-  "defaultStatus":       200,
-  "allowHeaderOverride": false,
-  "pathOverrides": {
-    "GET /api/v1/products/list": 500,
-    "/api/v1/admin/users-delete": 401
-  }
-}
-```
-
-| Field | Default | Meaning |
-| --- | --- | --- |
-| `enabled` | `false` | Master switch. `false` / absent = feature off. |
-| `header` | `'x-mock-status'` | Response header tagged with the resolved status. Also the request header consulted when `allowHeaderOverride: true`. |
-| `healthPaths` | `[]` | Paths exempt from injection (typically health probes). |
-| `defaultStatus` | undefined | Status applied when no override matches. Omit for passthrough. |
-| `allowHeaderOverride` | `false` | When `true`, an incoming request may flip the mocked status by sending the same `header` (default `x-mock-status: 500`). Disabled by default so production-style mock servers don't expose status injection to arbitrary clients. |
-| `pathOverrides` | `{}` | Per-route status overrides. Keys are `"METHOD /path"` or `"/path"` (path must start with `/`). Values are HTTP status codes. |
-| `logger` | `console` | Programmatic-only sink for non-fatal mock-mode diagnostics (e.g. out-of-range header overrides). Pass the host application's logger to keep mock-server output in one place. Not settable from JSONC. |
-
-## Resolution priority (canonical)
-
-For each request, mock-mode picks a status in this order — first hit
-wins. When `admin.enabled` is also set, the admin inject hook
-runs **before** mock-mode and can short-circuit any of the steps
-below; see [../admin/overrides.md#sticky-override-resolution](../admin/overrides.md#sticky-override-resolution)
-for the unified pipeline.
-
-1. Request `header` value (only when `allowHeaderOverride: true`).
-2. `pathOverrides["<METHOD> <path>"]` (method-scoped exact match).
-3. `pathOverrides["<path>"]` (any-method exact match).
-4. `defaultStatus`.
-5. Passthrough — the real handler runs.
-
-`healthPaths` short-circuits the entire chain: matching paths are
-served by their handler regardless of any override.
-
-## `pathOverrides` key validation
-
-Keys are validated at config load. Malformed keys raise at boot
-(via `AggregateError` so every gap surfaces at once) — there is no
-silent "this key never matches" failure mode.
-
-- Keys must match `(?:METHOD\s+)?/path`. The optional method prefix
-  is one of `GET POST PUT DELETE PATCH HEAD OPTIONS`. The path must
-  start with `/` and contain no whitespace.
-- Method names are normalised to upper-case: `"get /api/x"`,
-  `"GET /api/x"`, and `"Get /api/x"` all canonicalise to
-  `"GET /api/x"` so a lower-case key still matches.
-- Values must be finite numbers (HTTP status codes).
-
-## Body resolution
-
-When a non-passthrough status `N` fires:
-
-1. `status === 204` → empty body.
-2. The body resolver returns the OAS `responses[N]` schema mock when
-   the route is OAS-walker-backed and a response schema exists for
-   that status (see [../openapi/fallback.md#per-status-body-generators](../openapi/fallback.md#per-status-body-generators)).
-3. Fallback envelope `{ error: true, status: N }`.
-
-The configured `header` (default `x-mock-status`) is always tagged on
-the response with the resolved status code so a client can confirm
-which override fired.
-
-## `allowHeaderOverride` validation
-
-When the request header is set but the value is not a finite integer
-in `[200, 600)`, the value is **ignored** and a single `warn` line
-is emitted via `logger` (default `console`) so the typo is visible
-without breaking legitimate clients that ship the header for other
-reasons:
-
-```text
-@databehave/server/mock-mode: ignored x-mock-status="abc" (must be an integer in [200, 600))
-```
-
-A per-endpoint shortcut also exists — see [endpoints.md](./endpoints.md).

package/docs/config/openapi.md

@@ -1,8 +0,0 @@
-# `openapi`
-
-Path (relative to the config file) to an OpenAPI 3.x document.
-**JSON only** — convert YAML first via `yq -o=json openapi.yaml > openapi.json`.
-When set, the walker registers fallback handlers for every
-`paths.*.<method>` not declared in `endpoints`.
-
-See [../openapi/fallback.md](../openapi/fallback.md) for walker behaviour.

package/docs/config/schema.md

@@ -1,34 +0,0 @@
-# `schema`
-
-Top-level field that opts the server into **auto-schema mode** — every
-endpoint absent from `endpoints` is served from data generated by
-`@databehave/schema`'s `mock()` engine, derived directly from your
-OpenAPI document.
-
-**Minimal:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": { "enabled": true }, // "enabled" gates auto-mode; defaults equivalent to { "seed": "stable" }
-  "endpoints": {}
-}
-```
-
-**With knobs:**
-
-```jsonc
-{
-  "openapi": "./openapi.json",
-  "schema": {
-    "enabled": true,
-    "seed": 42, // number = fixed; "stable" = derive from endpoint|query|params; "random" = fresh per request; default "stable"
-    "locale": "ja",
-    "arrayCount": 20 // default array length when the OAS lacks minItems
-  }
-}
-```
-
-For the architecture, install path, missing-install error, precedence,
-and default-behaviour rules, see
-[../openapi/auto-schema.md](../openapi/auto-schema.md).

package/docs/config/server.md

@@ -1,32 +0,0 @@
-# `server` and `basePath`
-
-## `server`
-
-```jsonc
-"server": {
-  "host": "${MOCK_SERVER_HOST:127.0.0.1}",
-  "port": "${MOCK_SERVER_PORT:8000}"
-}
-```
-
-`host` defaults to `127.0.0.1`, `port` to `3000`. The CLI reads this
-section; the programmatic API ignores it (you pass `listen({ host,
-port })` directly).
-
-## `basePath`
-
-```jsonc
-"basePath": "/api/v1"
-```
-
-Automatically prepended to every `endpoints` key that does NOT start
-with `/` after the method. Must start with `/` and must not end with
-`/`. OpenAPI paths are left untouched — they already carry their full
-path in the OAS document.
-
-```jsonc
-"endpoints": {
-  "GET products/list": "./src/list.js",  // → /api/v1/products/list
-  "GET /health":              "./src/health.js" // → /health (absolute)
-}
-```

package/docs/config/validation.md

@@ -1,161 +0,0 @@
-# `validation`
-
-Opt-in inbound request validation against the OpenAPI document.
-Disabled by default — when `validation` is omitted or
-`validation.request !== true`, `server.fetch(Request)` is
-byte-identical to the no-validation behaviour.
-
-```jsonc
-"validation": {
-  "request": true,        // master switch; default false
-  "maxBodyBytes": 102400  // default 100 KB (matches express body-parser)
-}
-```
-
-Source: `src/types.ts:Config.validation`,
-`src/middleware/request-validation.ts`,
-`src/validation/validate.ts`.
-
-## Field reference
-
-### `validation.request` (boolean)
-
-Master switch. Default `false`. When `true`, every inbound request
-is matched against the OAS document and runs through the
-build-time-compiled validators below before reaching the
-dispatcher. Routes outside the OAS (hand-written `endpoints` keys
-that have no matching OAS path) are passed through unchanged — the
-validator has no contract to enforce.
-
-### `validation.maxBodyBytes` (number)
-
-Hard cap on the JSON request body size, measured in **UTF-8 bytes**
-(not JS string length). Default `102400` (100 KB) — matches
-express's body-parser default. Bodies above the cap are rejected
-with `413 Payload Too Large` before `JSON.parse` runs. Raise only
-if the OpenAPI document genuinely declares large request bodies.
-
-Source: `src/middleware/request-validation.ts:42-46`,
-`:300-380`.
-
-## Validation pipeline
-
-For every matching route (built once at server-creation,
-re-used per request) the validator runs four steps in order:
-
-1. **Security gate** — if the OAS declares a `security` block on
-   the operation (or globally), at least one requirement must be
-   satisfied. Failure → `401` with a `WWW-Authenticate` challenge.
-   Schemes recognised: `http` (presence-only `Authorization: <scheme> …`
-   match), `apiKey` (`in: header | query`; cookie schemes are
-   ignored), `oauth2`, `openIdConnect` (presence-only
-   `Authorization` check; full token introspection is out of scope
-   for a zero-dep mock — layer it via `hooks.onRequest` if needed).
-2. **Content-Type guard** — for routes whose `requestBody.content`
-   declares only `application/json`, requests with a non-JSON
-   `Content-Type` are rejected with `415`.
-3. **Body parse + validate** — the body is read once, capped at
-   `maxBodyBytes`, then `JSON.parse`-d. Parse failure → `400`. Any
-   schema violations are collected as `Violation[]` and emitted in
-   the `422` response. **Body validation is strict** — no type
-   coercion. A JSON `"42"` will not satisfy a schema with
-   `type: integer`.
-4. **Param validation (with coercion)** — query, path, and header
-   parameters arrive as strings on the wire and are coerced
-   (`integer`, `number`, `boolean`) before validation. Required
-   params missing from the request emit a `required`-keyword
-   violation. Cookie parameters are ignored.
-
-Source: `src/middleware/request-validation.ts:300-460`.
-
-## RFC 7807 problem-detail response
-
-All rejections use `Content-Type: application/problem+json` and the
-shape:
-
-```json
-{
-  "type": "https://github.com/ochairo/databehave/blob/main/docs/errors/<slug>.md",
-  "title": "Request validation failed",
-  "status": 422,
-  "detail": "request validation failed (3 violations)",
-  "violations": [
-    { "path": "/body/items/0/sku", "keyword": "minLength", "message": "..." },
-    { "path": "/query/page",       "keyword": "minimum",   "message": "..." },
-    { "path": "/header/x-id",      "keyword": "required",  "message": "..." }
-  ]
-}
-```
-
-Source: `src/middleware/request-validation.ts:24-50` (slug map +
-title map), `:240-280` (envelope builder).
-
-| Status | `title` | `type` slug |
-| --- | --- | --- |
-| `400` | `Malformed request` | `malformed-body` |
-| `401` | `Unauthorized` | `unauthorized` |
-| `413` | `Payload too large` | `payload-too-large` |
-| `415` | `Unsupported media type` | `unsupported-media-type` |
-| `422` | `Request validation failed` | `request-validation` |
-
-`violations` is omitted when empty (e.g. on `400` / `415` / `413`).
-The `Violation` shape (`{ path, keyword, message }`) is documented
-in `src/validation/validate.ts:Violation`. Each `path` is a
-JSON-Pointer rooted at one of `/body`, `/query/<name>`, `/path/<name>`,
-or `/header/<name>`.
-
-## Validator scope
-
-The hand-rolled validator is intentionally a JSON-Schema **subset**
-(audit-it-yourself: ~600 LoC, zero dependencies). Supported
-keywords: `type`, `enum`, `required`, `properties`,
-`additionalProperties`, `items`, `pattern`, `minLength`,
-`maxLength`, `minimum`, `maximum`, `exclusiveMinimum`,
-`exclusiveMaximum`, `minItems`, `maxItems`, `$ref`
-(intra-document only — `#/components/schemas/...`), `oneOf`,
-`anyOf`, `allOf`, `discriminator`, `format` (`date`, `date-time`,
-`email`, `uuid`, `uri`), and `nullable` (OAS 3.0) /
-`["X","null"]` (OAS 3.1).
-
-Unsupported keywords are **rejected at server-start, not runtime**:
-`if`, `then`, `else`, `dependentSchemas`, `dependentRequired`,
-`unevaluatedProperties`, `unevaluatedItems`, `contentEncoding`,
-`contentMediaType`, `propertyNames`, `patternProperties`, and
-remote (`http://…` / `https://…`) `$ref`. The same set is rejected
-by the auto-schema translator (single source of truth on JSON
-Schema parity).
-
-Source: `src/validation/validate.ts:51-58` (unsupported set),
-`:21-44` (supported set; mirrored in
-`src/openapi/translate.ts`).
-
-## Security guarantees
-
-The validator is built to be hostile-input safe:
-
-- **No `eval`, no `new Function`, no dynamic `require`** — pure
-  recursion (`src/validation/validate.ts:18-23`).
-- **Prototype-pollution guard** — input objects whose own keys
-  include `__proto__` / `constructor` / `prototype` are rejected as
-  per-property violations (`:50-56`).
-- **ReDoS mitigation** — `pattern` length capped at 1024 chars;
-  invalid regexes rejected at build time, never request time
-  (`:42`).
-- **Recursion depth cap 64** — both schema build (`$ref` cycles)
-  and `deepEqual` (used to compare against `enum` choices)
-  (`:38-41`).
-
-## Cross-references
-
-- Symptoms and diagnosis: [../troubleshooting.md](../troubleshooting.md).
-- Verbatim error catalogue (status mapping, `WWW-Authenticate`,
-  parser errors): [../errors.md](../errors.md).
-- Which OAS keywords each pipeline accepts:
-  [../openapi/keywords.md](../openapi/keywords.md).
-- Trust model for OAS-author input (the validator's caps are part
-  of it): [../openapi/fallback.md#trust-model](../openapi/fallback.md#trust-model).
-- Bypass via custom handlers: a hand-written `endpoints` route
-  receives the raw `Request` (post-security, post-content-type,
-  post-body checks unless you opt out at the route level — but the
-  route is still part of the validation universe). To skip
-  validation entirely for a route, omit it from the OAS document.