expediate 1.0.4 → 1.0.6

package/README.md

@@ -1,11 +1,21 @@
-# expediate
+<p align="center">
+  <img src="docs/expediate.png" alt="expediate" width="260" />
+</p>
 
-A lightweight, zero-dependency TypeScript HTTP routing framework for Node.js.
+<p align="center">
+  A lightweight, zero-dependency TypeScript HTTP routing framework for Node.js.
+</p>
 
-**expediate** provides an Express-compatible API surface with full TypeScript types, built-in body parsing, static file serving, JWT authentication, multipart form handling, and a Git Smart HTTP gateway — all in a single package with no runtime dependencies beyond Node.js itself.
+<p align="center">
+  <a href="https://www.npmjs.com/package/expediate"><img src="https://img.shields.io/npm/v/expediate.svg" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node ≥ 18" />
+  <a href="https://npmcharts.com/compare/expediate?minimal=true"><img src="https://img.shields.io/npm/dm/expediate.svg" alt="npm downloads" /></a>
+</p>
 
-  [![NPM Version][npm-image]][npm-url]
-  [![NPM Downloads][downloads-image]][downloads-url]
+---
+
+**Expediate** provides an Express-compatible API surface with full TypeScript types, built-in body parsing, static file serving, JWT authentication, multipart form handling, a Git Smart HTTP gateway, and a suite of production-ready middleware — all with **zero runtime dependencies** beyond Node.js itself.
 
 ---
 
@@ -13,31 +23,14 @@ A lightweight, zero-dependency TypeScript HTTP routing framework for Node.js.
 
 - [Installation](#installation)
 - [Quick start](#quick-start)
+- [Why Expediate?](#why-expediate)
 - [Router](#router)
-  - [Creating a router](#creating-a-router)
-  - [Route registration](#route-registration)
-  - [Path patterns](#path-patterns)
-  - [Response helpers](#response-helpers)
-  - [Sub-routers](#sub-routers)
-  - [Starting the server](#starting-the-server)
 - [Body parsing](#body-parsing)
-  - [`json()`](#json)
-  - [`formData()`](#formdata)
-  - [`parseBody()`](#parsebody)
 - [Static files](#static-files)
-  - [`serveStatic()`](#servestatic)
-  - [`serveFile()`](#servefile)
-  - [`sendFile()`](#sendfile)
-- [Request logging](#request-logging)
-- [JWT Authentication](#jwt-authentication)
-  - [Setup](#setup)
-  - [Protecting routes](#protecting-routes)
-  - [Role and permission guards](#role-and-permission-guards)
-  - [Configuration reference](#configuration-reference)
+- [Middleware suite](#middleware-suite)
+- [JWT authentication](#jwt-authentication)
 - [API service builder](#api-service-builder)
-  - [Defining a service](#defining-a-service)
-  - [Scoping](#scoping)
-  - [Error handling](#error-handling)
+- [OpenAPI spec generation](#openapi-spec-generation)
 - [Git Smart HTTP gateway](#git-smart-http-gateway)
 - [TypeScript types](#typescript-types)
 
@@ -49,7 +42,9 @@ A lightweight, zero-dependency TypeScript HTTP routing framework for Node.js.
 npm install expediate
 ```
 
-Node.js ≥ 18 is required. The package ships as native ESM with full TypeScript declarations.
+Node.js ≥ 18.20.0 is required — the floor where `with { type: 'json' }` JSON import attributes exist (the ESM build uses one for `mimetypes.json`); on 18.20.0–18.20.4, 20.10.0–20.18.2, and all of 21.x, Node logs an `ExperimentalWarning` for that syntax but runs fine. For a warning-free run, use Node ≥ 18.20.5, ≥ 20.18.3, or ≥ 22.12.0. The package ships as native ESM with full TypeScript declarations and a CommonJS compatibility bundle (the CJS build is bundled with esbuild specifically so this JSON import works under `require()` too).
+
+**Bun / Deno:** not officially tested, but likely to work with caveats. Both runtimes support `with { type: 'json' }` and the package's `exports` map resolves cleanly under either. The main risk area is `src/router.ts`'s use of `node:http2.createSecureServer` and raw socket fields (`req.socket.setTimeout`, `req.socket.remoteAddress`, `req.socket.encrypted`) for HTTP/2 + TLS: Bun's `node:http2` server support has known gaps (no `allowHTTP1`, no `enableConnectProtocol`, no ALPN-based push), and Deno's `node:http2` compatibility, while improving, is newer and less battle-tested than its `node:http`. Plain HTTP/HTTPS routes are the safer bet on either runtime.
 
 ---
 
@@ -60,16 +55,15 @@ import { createRouter, json, logger } from 'expediate';
 
 const app = createRouter();
 
-app.use('/', logger());
-app.use('/', json());
+app.use(logger());
+app.use(json());
 
 app.get('/hello/:name', (req, res) => {
   res.send(`Hello, ${req.params.name}!`);
 });
 
 app.post('/echo', (req, res) => {
-  res.setHeader('Content-Type', 'application/json');
-  res.send(JSON.stringify((req as any).body));
+  res.json((req as any).body);
 });
 
 app.listen(3000, () => console.log('Listening on :3000'));
@@ -77,552 +71,443 @@ app.listen(3000, () => console.log('Listening on :3000'));
 
 ---
 
+## Why Expediate?
+
+- **Zero runtime dependencies.** The entire framework — router, body parsers, static files, compression, JWT, Git gateway, OpenAPI — uses only Node.js built-ins.
+- **TypeScript-first.** Strict compiler settings, full type declarations for every public API.
+- **Express-compatible API.** Familiar route registration, `req`/`res` helpers, middleware signature, signed cookies, and error handling — easy migration path.
+- **Real HTTP testing.** The test suite spins up live servers on ephemeral ports rather than mocking. Behaviour you see in tests is behaviour you get in production.
+- **ESM + CJS dual output.** Works with both `import` and `require`.
+
+---
+
 ## Router
 
-### Creating a router
+→ Full reference: [docs/router.md](docs/router.md)
 
 ```ts
 import { createRouter } from 'expediate';
 
-const app = createRouter();
+const app = createRouter({
+  secret:     process.env.COOKIE_SECRET,
+  timeout:    30_000,    // 408 if no response starts within 30 s
+  trustProxy: true,      // trust X-Forwarded-* headers
+});
 ```
 
-`createRouter()` returns a `Router` object that also acts as a middleware function itself, making it nestable.
-
 ### Route registration
 
-All registration methods share the same signature:
-
 ```ts
-router.METHOD(path, ...middleware)
+app.get('/users',        listUsers);         // endpoint match (GET only)
+app.post('/users',       createUser);
+app.put('/users/:id',    updateUser);
+app.delete('/users/:id', deleteUser);
+app.all('/health',       handler);           // any method, endpoint match
+app.use('/api',          apiRouter);         // prefix mount — strips /api from req.path
 ```
 
-| Method | HTTP verb | Notes |
-|---|---|---|
-| `router.get(path, ...mw)` | `GET` | Path is not stripped from `req.path` — chained middlewares see the full path |
-| `router.post(path, ...mw)` | `POST` | |
-| `router.put(path, ...mw)` | `PUT` | |
-| `router.delete(path, ...mw)` | `DELETE` | |
-| `router.patch(path, ...mw)` | `PATCH` | |
-| `router.use(path, ...mw)` | any | **Strips the matched prefix** from `req.path` before calling middleware; used for mounting sub-routers |
-| `router.all(path, ...mw)` | any | Matches any method but don't strips the prefix |
+`use()` strips the matched prefix from `req.path` and sets `req.baseUrl` for nested routers. Method routes (`get`, `post`, etc.) use **endpoint matching** — `get('/users')` matches `/users` but not `/users/42`.
 
-Each middleware slot accepts a `Middleware` function, a `Router` instance, or an array of either:
+To register several methods against one path without repeating it, use the chainable `route()` builder:
 
 ```ts
-const guard: Middleware = (req, res, next) => {
-  if (!req.headers.authorization) return res.status(401).end();
-  next();
-};
-
-app.get('/secret', guard, (req, res) => res.send('classified'));
-app.get('/multi',  [guard, anotherMiddleware], handler);
+app.route('/users/:id')
+  .get(getUser)
+  .put(replaceUser)
+  .delete(removeUser);
 ```
 
-### Path patterns
+Each call forwards to the matching method (`get`, `post`, …) with the cached path and returns the builder, so behaviour is identical to calling those methods directly.
 
-Three pattern types are supported:
+**Method handling.** `HEAD` requests are served by the matching `GET` handler (Node strips the response body). An unhandled `OPTIONS` request on a registered path automatically returns `204 No Content` with an `Allow` header, and a method mismatch on a registered path returns `405 Method Not Allowed` with `Allow` (both list `HEAD` when a `GET` exists, plus `OPTIONS`). Register `app.head(path, …)` or `app.options(path, …)` (also on the `route()` builder) for method-specific handlers; explicit handlers and `cors()` run first, so they override these defaults.
 
-**Plain strings with `:param` segments**
-```ts
-app.get('/users/:id',              handler);  // req.params.id
-app.get('/orgs/:org/repos/:repo',  handler);  // req.params.org, req.params.repo
-```
+### Path patterns
 
-**Glob patterns** (`.gitignore` wildcard rules)
 ```ts
-app.get('/api/*',       handler);  // one path segment
-app.get('/api/**',      handler);  // any depth
-app.get('/**/*.php',    handler);  // PHP files in any subdirectory
-app.get('/v?/status',   handler);  // one character wildcard
+app.get('/users/:id',           handler);   // named param
+app.get('/items/:id(\\d+)',     handler);   // inline regex constraint (digits only)
+app.get('/api/**',              handler);   // glob — any depth
+app.get(/^\/v\d+\/status/,      handler);   // RegExp (no /g or /y flags)
 ```
 
-**Regular expressions** — named capture groups become `req.params` entries
+### Request fields
+
+Every request is augmented before middleware runs:
+
+| Field | Description |
+|---|---|
+| `req.params` | Named route params + flat URL query params |
+| `req.query` | URL query params (repeated keys → arrays) |
+| `req.path` | Current path (stripped by `use()` layers) |
+| `req.baseUrl` | Accumulated prefix from parent `use()` mounts |
+| `req.hostname` | `Host` header with port stripped |
+| `req.protocol` | `'http'` or `'https'` |
+| `req.secure` | `true` when protocol is `https` |
+| `req.ip` | Remote IP (respects `X-Forwarded-For` when `trustProxy: true`) |
+| `req.ips` | Full XFF chain as an array |
+| `req.cookies` | Parsed cookies; `s:` values are HMAC-verified |
+| `req.json()` | Parse body as JSON (Promise) |
+| `req.text()` | Read body as text (Promise) |
+| `req.formData()` | Parse body as multipart (Promise) |
+| `req.header(name)` | Read a request header by name (case-insensitive) |
+
+The `req.json()`, `req.text()`, and `req.formData()` helpers accept the same `BodyOptions` as the parser middleware, including `limit`, `inflate`, and the `verify` hook (a throw rejects the returned promise with the error's `status`, default `403`).
+
+### Response helpers
+
 ```ts
-app.get(/^\/users\/(?<id>\d+)/, handler);  // req.params.id
+res.send('Hello');                   // write and end
+res.json({ ok: true });              // JSON body + Content-Type
+res.status(201).send('Created');     // set status code (integer 100–999)
+res.redirect('/new-url');            // 302 Found
+res.type('text/csv').send(data);     // set Content-Type
+res.etag('v1').json(payload);        // weak ETag W/"v1"
+res.cookie('session', 'abc', { ... }); // Set-Cookie (value percent-encoded)
+res.clearCookie('session');          // Max-Age=0 + Expires=epoch
+res.download('/path/file.pdf');      // Content-Disposition: attachment
+res.attachment('report.pdf').send(buf); // set disposition + Content-Type
+res.sendStatus(200);                 // status + standard text body
+res.header('Cache-Control', 'no-store'); // set a header (replaces)
+res.append('X-Custom', 'v1');        // append to header
+res.vary('Accept');                  // add to Vary header
+res.location('/new-path');           // set Location
+res.locals['user'] = currentUser;    // request-scoped storage
 ```
 
-> **Route specificity:** when using `apiBuilder`, routes are automatically sorted by specificity (more segments / fewer parameters first) to prevent shorter paths from shadowing longer ones.
+### Error handling
 
-### Response helpers
+→ Full reference: [docs/errors.md](docs/errors.md)
+
+Any error thrown by a middleware — synchronous throw, rejected `async` middleware, or an explicit `next(err)` — enters the router's **error channel**.
 
-Every response object is augmented with convenience methods:
+Register ordered error middleware with `app.error()`. The error value is the **first** argument (to distinguish it from a normal middleware). Each handler either ends the response or calls `next` to pass control along — `next()` forwards the same error, `next(err)` replaces it:
 
 ```ts
-res.send('Hello');                   // write body and end
-res.send();                          // end with no body
-res.status(404).send('Not found');   // set status + body (chainable)
-res.status(201).end();               // set status and end
-res.redirect('/new-url');            // 302 redirect
-res.cookie('session', 'abc', {
-  maxAge:   3_600_000,               // milliseconds
-  path:     '/api',
-  signed:   false,
+app.error((err, _req, res, next) => {
+  if ((err as any)?.status === 404) return res.status(404).json({ error: 'Not Found' });
+  next(err); // not ours — let the next handler (or the parent router) deal with it
 });
-```
-
-<!-- Every response also carries `X-Powered-By: Expediate`. -->
 
-### Sub-routers
+app.error((err, _req, res, _next) => {
+  res.status((err as any)?.status ?? 500).json({ error: String(err) });
+});
+```
 
-Routers are fully nestable. Use `router.use()` to mount a child router under a prefix — the prefix is stripped from `req.path` before child middleware runs:
+**Bubbling.** When a router's `error()` chain is exhausted without ending the response, the error falls back to that router's `onError()` handler (if any), and otherwise **bubbles up to the parent router** that mounted it via `use()`. This means a single handler on the root router can catch failures raised deep inside nested sub-routers. A top-level router with no handler sends a plain `500`.
 
 ```ts
 const api = createRouter();
-api.get('/users',     listUsers);
-api.get('/users/:id', getUser);
-api.post('/users',    createUser);
+api.get('/items/:id', () => { throw new Error('boom'); });
 
 const app = createRouter();
-app.use('/api/v1', api);  // /api/v1/users → api sees /users
+app.use('/api', api);                       // api has no error handler…
+app.error((err, _req, res) =>               // …so the failure bubbles up to here
+  res.status(500).json({ error: String(err) }));
 ```
 
-Pass a `Router` instance directly (no need to unwrap `.listener`):
+`onError()` remains available as a simple, single terminal fallback `(err, req, res)` with no `next` — handy when you only want one catch-all and no bubbling.
+
+> Caveat: only the returned promise is tracked. A middleware that calls `next()` and *then* throws later from a detached callback (`setTimeout`, an event emitter) is outside the framework's reach.
+
+For a custom 404, register a catch-all as the **last** layer. Layers match in registration order, so it only runs when no earlier route claimed the request (`/**` matches any path, and `all()` matches any method):
 
 ```ts
-app.use('/auth', authRouter);   // Router instance
-app.use('/auth', authRouter.listener);  // equivalent
+app.all('/**', (_req, res) => res.status(404).json({ error: 'Not Found' }));
 ```
 
-### Starting the server
+Without one, unmatched requests fall back to the built-in `Cannot METHOD /path` 404.
+
+### Server
 
 ```ts
-// HTTP
-app.listen(3000, () => console.log('Ready'));
+const server = app.listen(3000, () => console.log('Ready'));
 
 // HTTPS
-import { readFileSync } from 'fs';
-app.listen(443, {
-  key:  readFileSync('server.key'),
-  cert: readFileSync('server.crt'),
-});
+app.listen(443, { key: readFileSync('key.pem'), cert: readFileSync('cert.pem') });
+
+// HTTP/2
+app.listen(443, { key, cert, http2: true });
+
+// Graceful shutdown
+process.on('SIGTERM', () => app.shutdown(10_000));
 ```
 
 ---
 
 ## Body parsing
 
-All body-parsing middleware must be registered **before** route handlers that need `req.body`.
+→ Full reference: [docs/body-parsing.md](docs/body-parsing.md)
 
-### `json()`
-
-Parses `application/json` request bodies and populates `req.body`. Also attaches `res.json(data)` for sending JSON responses.
+Typed parsers call `next()` when the request content-type does not match, so it is safe to stack them globally:
 
 ```ts
-import { json } from 'expediate';
+import { json, formData, formEncoded, raw, text, parseBody } from 'expediate';
 
-app.use('/', json());
+app.use(json());        // application/json → req.body
+app.use(formEncoded()); // application/x-www-form-urlencoded → req.body
+app.use(formData());    // multipart/form-data → req.body as FormPart[]
+app.use(text());        // text/plain → req.body as string
+app.use(raw());         // application/octet-stream → req.body as Buffer
 
-app.post('/data', (req, res) => {
-  const body = (req as any).body;
-  res.json({ received: body });
-});
+// Or catch everything at once (415 for unsupported types)
+app.use(parseBody());
 ```
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `limit` | `string \| number` | `'100kb'` | Maximum body size. Accepts `'10kb'`, `'2mb'`, `'1gb'`, or a number of bytes |
-| `inflate` | `boolean` | `true` | Decompress gzip/deflate bodies automatically |
-| `reviver` | `Reviver \| null` | `null` | Passed as the second argument to `JSON.parse` |
-| `strict` | `boolean` | `true` | Reserved for top-level primitive rejection |
-
-**Status codes returned on error:**
-- `413 Content Too Large` — body exceeds `limit`
-- `415 Unsupported Media Type` — wrong `Content-Type` or unsupported encoding
-- `500 Internal Server Error` — malformed JSON or unsupported charset
-
-### `formData()`
+Request bodies encoded with `gzip`, `deflate`, or `br` (Brotli) are decompressed automatically (disable with `inflate: false`).
 
-Parses `multipart/form-data` bodies. Populates `req.body` with an array of `FormPart` objects, each exposing:
-- `headers` — part headers (lowercased, e.g. `content-disposition`)
-- `content` — raw `Buffer` of the part body
+Override which requests a parser handles with `type`, and inspect the raw bytes before parsing with `verify` (throw to reject — handy for webhook signature checks):
 
 ```ts
-import { formData } from 'expediate';
-
-app.post('/upload', formData(), (req, res) => {
-  const parts = (req as any).body as FormPart[];
-  for (const part of parts) {
-    const disp = part.headers['content-disposition'];
-    console.log(disp, '-', part.content.length, 'bytes');
-  }
-  res.status(201).end();
-});
+app.post('/webhook',
+  json({
+    type:   'application/*',                // string, string[], or (req) => boolean
+    verify: (req, res, buf) => verifySignature(req, buf), // throw → 403 (or err.status)
+  }),
+  handler,
+);
 ```
 
-Accepts the same `limit` and `inflate` options as `json()`.
-
-### `parseBody()`
-
-Auto-detects the `Content-Type` and dispatches to the appropriate parser. Supports:
-
-| Content-Type | Result in `req.body` |
-|---|---|
-| `application/json` | Parsed JS value |
-| `multipart/form-data` | `FormPart[]` |
-| `text/plain` | Decoded string |
+Streaming multipart:
 
 ```ts
-import { parseBody } from 'expediate';
+import { streamFormData } from 'expediate';
 
-app.use('/', parseBody());
+app.post('/upload', async (req, res) => {
+  for await (const part of streamFormData(req)) {
+    for await (const chunk of part.stream) { /* consume */ }
+  }
+  res.send('ok');
+});
 ```
 
-Unsupported MIME types receive `415 Unsupported Media Type`.
+| Option | Default | Description |
+|---|---|---|
+| `limit` | `'100kb'` | Maximum body size |
+| `inflate` | `true` | Accept gzip/deflate/br encoded bodies |
+| `reviver` | `null` | JSON.parse reviver |
+| `strict` | `true` | `json()` only — reject a bare top-level JSON primitive (string, number, boolean, `null`) with `400 Bad Request` |
+| `type` | per parser | Content-type matcher: string, string[], or `(req) => boolean` (supports `*` wildcards) |
+| `verify` | `null` | Hook `(req, res, buf, encoding)` run on the raw body before parsing; throw to reject |
 
 ---
 
 ## Static files
 
-### `serveStatic()`
-
-Serve an entire directory of static assets:
+→ Full reference: [docs/static.md](docs/static.md)
 
 ```ts
-import { serveStatic } from 'expediate';
-
-app.use('/public', serveStatic('./dist'));
-```
-
-Features: ETag, Last-Modified, conditional GET (304), Cache-Control, MIME-type detection, dot-file handling, directory index redirect, gzip/deflate decompression.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `maxage` / `maxAge` | `number` | `0` | Cache lifetime in **milliseconds** → `Cache-Control: public, max-age=<s>` |
-| `immutable` | `boolean` | `false` | Appends `, immutable` to `Cache-Control` |
-| `etag` | `boolean` | `true` | Send weak `ETag` header |
-| `lastModified` | `boolean` | `true` | Send `Last-Modified` header |
-| `dotfiles` | `'allow' \| 'deny' \| 'hide'` | `'hide'` | Dot-file access policy |
-| `redirect` | `boolean` | `true` | Redirect directory requests to `index.html` |
-| `fallthrough` | `boolean` | `true` | Call `next()` instead of sending 404 for missing files |
-| `contentType` | `string \| null` | `null` | Override auto-detected `Content-Type` |
-| `headers` | `Record<string, string>` | security defaults | Extra response headers merged with built-in CSP / XCTO headers |
-
-### `serveFile()`
+import { serveStatic, serveFile, sendFile } from 'expediate';
 
-Serve a single fixed file for every request — ideal for SPA catch-all routes:
+// Serve a directory
+app.use('/public', serveStatic('./dist', { maxAge: 86_400_000 }));
 
-```ts
-import { serveFile } from 'expediate';
-
-// Serve dist/index.html for every unmatched route
+// SPA catch-all
 app.get('/**', serveFile('./dist/index.html'));
-```
-
-Supports the same caching and method-filtering options as `serveStatic()`. Returns `500 EISDIR` if the path points to a directory.
-
-### `sendFile()`
 
-Low-level utility for sending an arbitrary file path dynamically:
-
-```ts
-import { sendFile } from 'expediate';
-import type { StaticOptions } from 'expediate';
-
-const opts: StaticOptions = { etag: true, lastModified: true };
-
-app.get('/downloads/:file', (req, res) => {
-  const filePath = path.join('./downloads', req.params.file);
-  sendFile(req as any, res as any, filePath, opts as any);
+// Dynamic path
+app.get('/files/:name', (req, res) => {
+  sendFile(req as any, res as any, path.join('./files', req.params.name));
 });
 ```
 
+Features: weak ETags, `Last-Modified`, `304 Not Modified`, `Cache-Control`, dot-file policies, path traversal protection, HTML-escaped directory listings, `400` for malformed percent-encoded paths.
+
 ---
 
-## Request logging
+## Middleware suite
 
-```ts
-import { logger } from 'expediate';
-
-app.use('/', logger({
-  track:        true,            // warn on requests that never finish (dev only)
-  trackTimeout: 30_000,          // ms before emitting a LOST warning
-  user:         (req) => (req as any).user?.username ?? '-',
-  locale:       'en-US',
-  logger:       (msg) => process.stderr.write(msg + '\n'),
-}));
-```
+→ Full reference: [docs/middleware.md](docs/middleware.md)
 
-Output format (one line per completed request, ANSI-coloured by status class):
+| Middleware | Purpose |
+|---|---|
+| `compress()` | Brotli / gzip / deflate response compression |
+| `conditionalGet()` | `If-None-Match` / `If-Modified-Since` → 304 |
+| `cacheControl()` | `Cache-Control`, `Expires`, `Vary` headers |
+| `requestId()` | Unique `req.id` + response header |
+| `rateLimit()` | Sliding-window in-memory rate limiting |
+| `csrf()` | Double-submit cookie CSRF protection |
+| `securityHeaders()` | HSTS, X-Frame-Options, CSP baseline, etc. |
+| `cors()` | Cross-Origin Resource Sharing headers |
+| `logger()` | One-line request log with timing |
 
-```
-21 Mar, 14:32  200  GET  /api/users  127.0.0.1  <alice>  4 ms  (1234)
-```
+```ts
+import {
+  compress, conditionalGet, cacheControl, requestId,
+  rateLimit, csrf, securityHeaders, cors, logger,
+} from 'expediate';
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `track` | `boolean` | `false` | Enable lost-request detection |
-| `trackTimeout` | `number` | `30000` | Timeout in ms before a LOST line is emitted |
-| `user` | `(req) => string` | `() => '-'` | Extract a user identity from the request |
-| `locale` | `string` | `'en-GB'` | BCP 47 locale for the timestamp |
-| `dateFormat` | `Intl.DateTimeFormatOptions` | short date+time | Timestamp format |
-| `logger` | `(msg: string) => void` | `console.log` | Custom logging sink |
+app.use(compress());
+app.use(securityHeaders());
+app.use(cors({ origin: 'https://example.com' }));
+app.use(requestId());
+app.use(logger());
+app.use(rateLimit({ windowMs: 60_000, max: 100 }));
+```
 
 ---
 
-## JWT Authentication
+## JWT authentication
 
-### Setup
+→ Full reference: [docs/jwt-auth.md](docs/jwt-auth.md)
 
 ```ts
 import { createRouter, json, createJwtPlugin } from 'expediate';
 
 const app  = createRouter();
 const auth = createJwtPlugin({
-  accessTokenSecret:  process.env.JWT_SECRET!,
-  refreshTokenSecret: process.env.JWT_REFRESH_SECRET!,
+  accessTokenSecret: process.env.JWT_SECRET!,
+  fetchUser:         (username) => db.users.findOne({ username }),
+  isPasswordValid:   (user, pw) => bcrypt.compare(pw, user.passwordHash),
 });
 
-// Mount auth endpoints (require json() body parser first)
 app.post('/auth/login',   json(), auth.login);
 app.post('/auth/refresh', json(), auth.refresh);
 app.post('/auth/logout',  json(), auth.logout);
-```
-
-#### `POST /auth/login`
 
-```json
-// Request body
-{ "username": "alice", "password": "password123" }
-
-// Response 200
-{
-  "accessToken":  "eyJ...",
-  "refreshToken": "a3f8...",
-  "expiresIn":    900,
-  "tokenType":    "Bearer"
-}
+// Protect routes
+app.get('/me',           auth.authenticate, auth.authorize, meHandler);
+app.delete('/admin/:id', ...auth.requireRole('admin'),      deleteUser);
+app.put('/posts/:id',    ...auth.requirePermission('write'), updatePost);
 ```
 
-#### `POST /auth/refresh`
-
-```json
-// Request body
-{ "username": "alice", "refreshToken": "a3f8..." }
+Supported algorithms: `HS256/384/512`, `RS256/384/512`, `ES256/384/512`. Refresh tokens rotate on every use. Fully implemented with Node.js `crypto` — no third-party JWT library.
 
-// Response 200 — new token pair (old refresh token is invalidated)
-{ "accessToken": "eyJ...", "refreshToken": "b9c2...", ... }
-```
+> **Security note:** always supply `fetchUser` and `isPasswordValid`. The defaults use demo credentials and SHA-256 password hashing, which are unsuitable for production.
 
-Refresh tokens are **rotated** on every use — the presented token is always invalidated and a fresh pair is issued.
+---
 
-#### `POST /auth/logout`
+## API service builder
 
-```json
-{ "refreshToken": "b9c2..." }
-// Response 200 — refresh token revoked
-```
+→ Full reference: [docs/api-builder.md](docs/api-builder.md)
 
-### Protecting routes
+Define REST endpoints as a controller-style service object with automatic scoping, lifecycle management, and error translation:
 
 ```ts
-// authenticate — silently populates req.user; calls next() even on failure
-// authorize   — rejects with 401 if req.user is not set
-app.get('/me', auth.authenticate, auth.authorize, (req, res) => {
-  res.send(`Hello, ${(req as any).user.username}`);
-});
-```
-
-`req.user` is populated with the decoded `TokenPayload`:
+import { createRouter, json, apiBuilder } from 'expediate';
+import type { ServiceDefinition, ApiContext } from 'expediate';
 
-```ts
-interface TokenPayload {
-  sub:          string;   // user ID
-  username:     string;
-  iss:          string;   // issuer
-  iat:          number;   // issued at (Unix s)
-  exp:          number;   // expires at (Unix s)
-  roles?:       string[];
-  permissions?: string[];
-}
-```
+interface State { items: string[]; }
 
-### Role and permission guards
+const service: ServiceDefinition<State> = {
+  data: () => ({ items: [] }),
 
-```ts
-// Require at least one of the listed roles
-app.delete('/admin/users/:id', ...auth.requireRole('admin'), deleteUser);
+  GET: {
+    '/items':     function (this: State) { return this.items; },
+    '/items/:id': function (this: State, ctx: ApiContext) { return this.items[+ctx.params.id]; },
+  },
+  POST: {
+    '/items': function (this: State, _ctx: ApiContext, body: any) {
+      this.items.push(body.name);
+      return this.items;
+    },
+  },
+};
 
-// Require ALL listed permissions
-app.put('/posts/:id', ...auth.requirePermission('write', 'publish'), updatePost);
+const app = createRouter();
+app.use('/', json());
+app.use('/api', apiBuilder(service));
+app.listen(3000);
 ```
 
-Both factories return `[authenticate, guard]` — spread them into the route registration:
-
-```ts
-app.get('/report', ...auth.requireRole('admin', 'editor'), getReport);
-```
+Three scoping modes: **singleton** (one global instance), **keyed** (one instance per key), **ephemeral** (new instance per request). Routes are automatically sorted by specificity so declaration order does not matter.
 
-### Configuration reference
+Errors thrown by a handler, guard, auth check, or validation are translated to HTTP automatically (`{ status, message | data }`, else `500`). Add a `service.onError` hook to log or reshape them before that translation — return nothing to keep the default, return an `ApiError` to override the response, or throw to escalate the error to the surrounding app's error channel (`app.error()`):
 
 ```ts
-const auth = createJwtPlugin({
-  // Secrets — always override in production
-  accessTokenSecret:  'change-me',
-  refreshTokenSecret: 'change-me',
-
-  // Expiry
-  accessTokenExpiry:  15 * 60,         // 15 minutes (seconds)
-  refreshTokenExpiry: 7 * 24 * 3600,   // 7 days (seconds)
-
-  // Token claims
-  issuer:      'my-app',
-  checkIssuer: true,                   // reject tokens with wrong iss claim
-  alg:         'HS256',                // 'HS256' | 'HS384' | 'HS512'
-
-  // User lookup (replace with a database query) — must override
-  // Returned object must have a username field
-  fetchUser: async (username) => {
-    return await db.users.findOne({ username });
-  },
-
-  // Password validation — default look for SHA256(user.passwordHash), replace with bcrypt/argon2
-  isPasswordValid: async (user, password) => {
-    return await bcrypt.compare(password, user.passwordHash);
+const service: ServiceDefinition<State> = {
+  onError(err, ctx, _req) {
+    metrics.increment('api.error', { path: ctx.path });
+    if (err instanceof DbTimeout) return { status: 503, message: 'Try again shortly' };
+    // return nothing → default translation; throw → bubble up to app.error()
   },
-
-  // Custom JWT payload
-  payload: (user) => ({
-    sub:   user.id,
-    email: user.email,
-    roles: user.roles,
-  }),
-
-  // Custom token store (replace with Redis for multi-instance deployments)
-  refreshTokenStore: redisAdapter,
-});
+  // …routes…
+};
 ```
 
-> **Security note:** the default password hashing uses SHA-256, which is fast and unsuitable for production. Replace `isPasswordValid` with a bcrypt or argon2 implementation.
-
----
+Large APIs split into per-domain **controllers** that merge into one router and one OpenAPI document — with **guards**, a declarative **auth binding** bridged to the JWT plugin, and **runtime request validation** from declared JSON Schemas:
 
-## API service builder
+```ts
+import { apiBuilder, defineController, describe, createJwtPlugin } from 'expediate';
 
-`apiBuilder` lets you define REST endpoints as a controller-style service object, handling scoping, lifecycle, method binding, and error translation automatically.
+const jwt = createJwtPlugin({ accessTokenSecret: SECRET });
 
-### Defining a service
-
-```ts
-import { createRouter, json, apiBuilder } from 'expediate';
-import type { ServiceDefinition } from 'expediate';
-
-interface TodoState {
-  items: Record<string, { title: string; done: boolean }>;
-  nextId: number;
-}
-
-const todoService: ServiceDefinition<TodoState> = {
-  // Initial state
-  data: () => ({ items: {}, nextId: 1 }),
-
-  // Shared helper methods (bound to `this`)
-  methods: {
-    findOrThrow(this: TodoState, id: string) {
-      const item = this.items[id];
-      if (!item) throw { httpStatus: 404, message: 'Todo not found' };
-      return item;
-    },
-  },
+const wikiController = defineController({
+  prefix: '/p/:proj/wiki',
+  tags:   ['Wiki'],
+  permission: 'wiki.read',                   // auth.check() runs for every route
+  guards: [loadProject],                     // pre-handler hooks; results land in ctx.state
 
   GET: {
-    '/todos':     function (this: TodoState) { return Object.entries(this.items).map(([id, v]) => ({ id, ...v })); },
-    '/todos/:id': function (this: TodoState, params) { return this.findOrThrow(params.id); },
-  },
-
-  POST: {
-    '/todos': function (this: TodoState, _params, body: any) {
-      const id = String(this.nextId++);
-      this.items[id] = { title: body.title, done: false };
-      return { id, ...this.items[id] };
-    },
+    '/pages/:slug': describe(
+      (ctx) => wiki.readPage(ctx.params.proj, ctx.params.slug),
+      { summary: 'Read a wiki page' }),
   },
-
-  DELETE: {
-    '/todos/:id': function (this: TodoState, params) {
-      this.findOrThrow(params.id);
-      delete this.items[params.id];
-      return undefined;  // → 201 No Content
-    },
+  PUT: {
+    '/pages/:slug': describe(
+      (ctx, body) => wiki.writePage(ctx.params.proj, ctx.params.slug, body),
+      { summary: 'Create or update a page', permission: 'wiki.write' }),
   },
-};
-
-const app = createRouter();
-app.use('/', json());
-app.use('/api', apiBuilder(todoService));
+});
 
-app.listen(3000);
+const api = apiBuilder({
+  auth:     { authenticate: jwt.authenticate },  // default check reads ctx.user.permissions
+  validate: true,                                // enforce declared requestBody schemas (400 + fieldErrors)
+  controllers: [wikiController /* , issuesController, … */],
+});
 ```
 
-**Handler conventions:**
+Duplicate `(verb, path)` pairs across controllers **throw at build time** instead of silently shadowing.
 
-| Return value | HTTP response |
-|---|---|
-| Truthy value or `Promise` resolving to one | `200 OK` with JSON body |
-| `undefined`, `null`, `false`, `0`, `''` | `201 No Content` |
-| Throw `{ httpStatus, message }` | `<httpStatus>` with plain-text body |
-| Throw `{ httpStatus, data }` | `<httpStatus>` with JSON body |
-| Throw anything else | `500 Internal Server Error` |
-
-### Scoping
-
-Control how many instances of the service state are created:
+`apiBuilder(service, options?)` takes an optional second argument (`ApiBuilderOptions`) to control validation. When provided it overrides `service.validate`: `validateRequests` defaults **on** (cancel with `{ validateRequests: false }`) and `validateResponses` opts in to checking each handler's return against its declared `200` schema — `true` returns `500` on a mismatch (the server's fault), `'warn'` only logs it:
 
 ```ts
-const service: ServiceDefinition = {
-  // Singleton (default — omit `scope`): one global instance
-  // scope: undefined
-
-  // Per-session: same instance reused for all requests sharing the key
-  scope: (req) => (req as any).session?.ssid ?? null,
-
-  // Per-request: fresh instance for every request (null key)
-  scope: () => null,
-
-  data: () => ({ /* initial state */ }),
-};
+apiBuilder(service, { validateResponses: true }); // validate both incoming bodies and outgoing responses
 ```
 
-> The key returned by the `scope()` method is store at `this.$key`.
+---
 
-### Error handling
+## OpenAPI spec generation
 
-Throw structured errors from any handler or method to send precise HTTP responses:
+→ Full reference: [docs/openapi.md](docs/openapi.md)
 
 ```ts
-// Plain message
-throw { httpStatus: 404, message: 'Resource not found' };
-
-// JSON body
-throw { httpStatus: 422, data: { field: 'email', error: 'invalid format' } };
+import { apiBuilder, describe } from 'expediate';
 
-// Guard pattern for async setup
-methods: {
-  throwIfNotReady(this: any) {
-    if (!this.ready)
-      throw { httpStatus: 503, message: 'Service initialising — try again shortly' };
+const service: ServiceDefinition<State> = {
+  GET: {
+    '/items': describe(
+      function (this: State) { return this.items; },
+      { summary: 'List items', responses: { '200': { description: 'Item array' } } },
+    ),
   },
-},
-setup: function (this: any) {
-  this.loadData().then(() => { this.ready = true; });
-},
+};
+
+const api = apiBuilder(service);
+app.use('/api', api);
+app.get('/openapi.json', api.specHandler({ title: 'Items API', version: '1.0.0' }));
+app.get('/openapi.yaml', api.specHandler({ title: 'Items API', version: '1.0.0' }, 'yaml'));
 ```
 
+Controllers merge into a single document. Routes carrying a `permission` automatically emit `security: [{ bearerAuth: [] }]`, an `x-required-permissions` vendor extension, and the matching `components.securitySchemes` entry.
+
+`openApiSpec()` also accepts an **array of sources** — useful for documenting routes that have no `ServiceDefinition` at all (e.g. JWT auth endpoints mounted directly with `app.post(...)`) alongside a real API in one merged document. See [docs/openapi.md](docs/openapi.md#multiple-sources).
+
 ---
 
 ## Git Smart HTTP gateway
 
-Serve a Git repository over HTTP (fetch / clone only — push is not supported):
+→ Full reference: [docs/git.md](docs/git.md)
+
+Serve Git repositories over HTTP — supports clone, fetch, and push:
 
 ```ts
-import { createRouter, gitHandler } from 'expediate';
+import { createRouter, gitHandler, gitCreate } from 'expediate';
 import path from 'path';
 
 const app = createRouter();
 
 app.use('/repos/:repo', gitHandler({
   repository: (req) => {
-    // Resolve the repo path from the request; return falsy to 404
     const name = req.params.repo;
     if (!/^[\w.-]+$/.test(name)) return null;
     return path.join('/srv/git', name + '.git');
@@ -632,52 +517,58 @@ app.use('/repos/:repo', gitHandler({
 app.listen(3000);
 ```
 
-Clients can now clone with:
-
 ```bash
 git clone http://localhost:3000/repos/myproject
+git push  http://localhost:3000/repos/myproject HEAD:main
 ```
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `repository` | `(req) => string \| null` | **required** | Resolve the absolute path to the bare repository. Return falsy to send 404 |
-| `gitPath` | `string` | `''` | Directory prefix for the `git-upload-pack` binary (include trailing `/`) |
-| `strict` | `boolean` | `false` | When `true`, omits `--no-strict` — git will reject non-bare repositories |
-| `timeout` | `number \| string` | none | Kill `git-upload-pack` after this many **seconds** |
-
-**Supported endpoints:**
-
-| Method | Path | Description |
-|---|---|---|
-| `GET` | `/info/refs?service=git-upload-pack` | Capability advertisement |
-| `POST` | `/git-upload-pack` | Pack negotiation and transfer |
+Create new repositories programmatically:
 
-Gzip-compressed `POST` bodies are decompressed transparently. Spawn errors (e.g. `git` not installed) return `500` with a descriptive message.
+```ts
+await gitCreate('/srv/git/newrepo.git', { description: 'New repository' });
+```
 
 ---
 
 ## TypeScript types
 
-Full type declarations are included. Key types exported from the package:
+Full declarations are included. Key exports:
 
 ```ts
 // Router
-import type { Router, RouterRequest, RouterResponse, Middleware, MiddlewareArg } from 'expediate';
+import type {
+  Router, RouterOptions, RouterRequest, RouterResponse,
+  Middleware, MiddlewareArg, NextFunction, ErrorHandler, ErrorMiddleware,
+  Layer, RouteInfo, RouteBuilder, CookieOptions, TlsOptions, StringMap,
+} from 'expediate';
 
 // Body parsing
-import type { BodyOptions, FormPart } from 'expediate';
+import type {
+  BodyOptions, BodyTypeMatcher, VerifyFn, FormPart, FormPartStream,
+  LoggerOptions, CorsOptions,
+} from 'expediate';
 
 // Static files
-import type { StaticOptions } from 'expediate';
+import type { StaticOptions, Mime } from 'expediate';
 
-// Logging
-import type { LoggerOptions } from 'expediate';
+// Middleware
+import type {
+  CompressOptions, RequestIdOptions, RateLimitOptions,
+  CacheControlOptions, CsrfOptions, SecurityHeadersOptions,
+} from 'expediate';
 
 // JWT
-import type { JwtConfig, JwtPlugin, TokenPayload, UserRecord, TokenStore } from 'expediate';
-
-// API builder
-import type { ServiceDefinition, ServiceMethod, ApiError } from 'expediate';
+import type {
+  JwtConfig, JwtPlugin, TokenPayload, TokenStore,
+  UserRecord, RefreshTokenRecord,
+} from 'expediate';
+
+// API builder + OpenAPI
+import type {
+  ServiceDefinition, ServiceMethod, ServiceMethods, RouteMap, ApiError,
+  ApiContext, ControllerDefinition, Guard, AuthBinding, ApiBuilderOptions,
+  OperationMeta, OpenApiServiceMeta, SpecOptions, OpenApiDocument,
+} from 'expediate';
 
 // Git
 import type { GitHandlerOptions } from 'expediate';
@@ -688,8 +579,3 @@ import type { GitHandlerOptions } from 'expediate';
 ## License
 
 MIT © 2021 Fabien Bavent
-
-[npm-image]: https://img.shields.io/npm/v/expediate.svg
-[npm-url]: https://npmjs.org/package/expediate
-[downloads-image]: https://img.shields.io/npm/dm/expediate.svg
-[downloads-url]: https://npmcharts.com/compare/expediate?minimal=true