actor-ts 0.9.1 → 0.11.0

package/dist/http/HttpExtension.js

@@ -1,7 +1,9 @@
+import { CoordinatedShutdownId, Phases } from '../CoordinatedShutdown.js';
 import { extensionId } from '../Extension.js';
 import { FastifyBackend } from './backend/FastifyBackend.js';
 import { HttpClient } from './HttpClient.js';
-import { compile } from './Route.js';
+import { compile, defaultErrorResponse } from './Route.js';
+import { ConnectionTracker, trackSocket } from './websocket/ConnectionWiring.js';
 /**
  * System-wide HTTP extension — entry point for the routing DSL and the
  * shared HttpClient.  Every ActorSystem gets one HttpClient and a factory
@@ -18,27 +20,54 @@ export class HttpExtension {
     /** Start building a new server scope.  Call `bind(routes)` to start it. */
     newServerAt(host, port) {
         let backend = null;
+        let errorHandler = null;
         const system = this.system;
         return {
             useBackend(b) {
                 backend = b;
                 return this;
             },
+            withErrorHandler(handler) {
+                errorHandler = handler;
+                return this;
+            },
             async bind(routes) {
                 const active = backend ?? new FastifyBackend();
                 const compiled = compile(routes);
-                // Wrap each route's handler with a request log + timing.
+                const httpRoutes = compiled.filter((r) => r.kind === 'http');
+                const wsRoutes = compiled.filter((r) => r.kind === 'websocket');
+                const fallbacks = compiled.filter((r) => r.kind === 'fallback');
+                if (wsRoutes.length > 0 && typeof active.registerWebSocket !== 'function') {
+                    throw new Error(`HTTP backend "${active.name}" does not support websocket() routes.`);
+                }
+                // Reject duplicate / conflicting patterns up front — clearer than
+                // the backend's own boot-time error, and it catches the WS-vs-GET
+                // collision (a WS route occupies the GET verb at its pattern).
+                const wsPatterns = new Set();
+                for (const route of wsRoutes) {
+                    if (wsPatterns.has(route.pattern)) {
+                        throw new Error(`Duplicate websocket() route for pattern "${route.pattern}".`);
+                    }
+                    wsPatterns.add(route.pattern);
+                }
+                for (const route of httpRoutes) {
+                    if (route.method === 'GET' && wsPatterns.has(route.pattern)) {
+                        throw new Error(`Route conflict: GET ${route.pattern} collides with a websocket() route on the same path.`);
+                    }
+                }
+                // Wrap each HTTP route's handler with a request log + timing.
                 // Done at the DSL level so backends don't need a Logger
                 // reference — every backend gets the same per-request debug
                 // line uniformly.
-                for (const r of compiled) {
-                    const wrapped = {
-                        ...r,
+                for (const route of httpRoutes) {
+                    active.registerRoute({
+                        method: route.method,
+                        pattern: route.pattern,
                         handler: async (req) => {
                             const start = Date.now();
                             system.log.debug(`[http] ${req.method} ${req.path}`);
                             try {
-                                const out = await r.handler(req);
+                                const out = await route.handler(req);
                                 system.log.debug(`[http] ${req.method} ${req.path} → ${out.status} (${Date.now() - start} ms)`);
                                 return out;
                             }
@@ -47,12 +76,79 @@ export class HttpExtension {
                                 throw err;
                             }
                         },
-                    };
-                    active.registerRoute(wrapped);
+                    });
+                }
+                // WebSocket routes: every accepted socket flows through the
+                // shared ConnectionTracker so unbind() can close it — otherwise
+                // a long-lived socket keeps the server's close() pending forever.
+                const tracker = new ConnectionTracker();
+                for (const route of wsRoutes) {
+                    active.registerWebSocket({
+                        pattern: route.pattern,
+                        authorize: route.authorize,
+                        onConnection: (req, socket) => {
+                            system.log.debug(`[ws] upgrade ${req.path}`);
+                            route.connect(system, req, trackSocket(tracker, socket));
+                        },
+                    });
+                }
+                // Fallback (not-found) route — at most one, wired to the backend's
+                // method-agnostic not-found hook.  Wrap it like the per-route
+                // handlers (debug log + default error mapping on throw).
+                if (fallbacks.length > 1) {
+                    throw new Error('Multiple fallback() routes registered — a server has exactly one not-found handler.');
+                }
+                if (fallbacks.length === 1) {
+                    if (typeof active.setNotFound !== 'function') {
+                        throw new Error(`HTTP backend "${active.name}" does not support fallback() routes (no setNotFound hook).`);
+                    }
+                    const fb = fallbacks[0];
+                    active.setNotFound(async (req) => {
+                        system.log.debug(`[http] (fallback) ${req.method} ${req.path}`);
+                        try {
+                            return await fb.handler(req);
+                        }
+                        catch (err) {
+                            return defaultErrorResponse(err);
+                        }
+                    });
+                }
+                // Server-wide error handler.  Backends consult it before their
+                // default mapping and fall back to that mapping if it throws.
+                if (errorHandler) {
+                    if (typeof active.setErrorHandler !== 'function') {
+                        throw new Error(`HTTP backend "${active.name}" does not support withErrorHandler (no setErrorHandler hook).`);
+                    }
+                    active.setErrorHandler(errorHandler);
                 }
-                const binding = await active.listen(host, port);
+                const raw = await active.listen(host, port);
+                // Wrap `unbind` so it's idempotent — both the auto-registered
+                // CoordinatedShutdown task and any manual caller can invoke it
+                // safely; subsequent calls return the in-flight/resolved promise
+                // from the first.  On unbind we also close then hard-terminate
+                // live WebSocket sockets so the backend's close() can complete.
+                let unbindOnce = null;
+                const binding = {
+                    host: raw.host,
+                    port: raw.port,
+                    unbind(gracePeriodMs) {
+                        if (!unbindOnce) {
+                            unbindOnce = (async () => {
+                                const backendUnbind = raw.unbind(gracePeriodMs);
+                                tracker.closeAll(1001, 'server shutting down');
+                                tracker.terminateAll();
+                                await backendUnbind;
+                            })();
+                        }
+                        return unbindOnce;
+                    },
+                };
+                // Auto-register with CoordinatedShutdown's ServiceUnbind phase so
+                // operator-triggered shutdown (SIGTERM, cluster-leave, etc.) closes
+                // the server before the rest of the pipeline tears down the system.
+                system.extension(CoordinatedShutdownId).addTask(Phases.ServiceUnbind, `http-unbind-${binding.host}:${binding.port}`, () => binding.unbind());
                 system.log.info(`HTTP server bound on ${binding.host}:${binding.port} (${active.name})`);
-                system.log.debug(`[http] ${compiled.length} route(s) registered`);
+                system.log.debug(`[http] ${httpRoutes.length} route(s) + ${wsRoutes.length} websocket route(s) registered`);
                 return binding;
             },
         };

package/dist/http/HttpExtension.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpExtension.js","sourceRoot":"","sources":["../../src/http/HttpExtension.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"HttpExtension.js","sourceRoot":"","sources":["../../src/http/HttpExtension.ts"],"names":[],"mappings":"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"}

package/dist/http/Marshalling.js

@@ -20,11 +20,11 @@ export function pickRequestSerializer(req) {
 export function pickResponseSerializer(req) {
     const accept = req.headers['accept'] ?? 'application/json';
     for (const tok of accept.split(',')) {
-        const t = tok.trim().split(';')[0].toLowerCase();
-        if (t === 'application/cbor' || t === 'application/x-cbor') {
+        const mediaType = tok.trim().split(';')[0].toLowerCase();
+        if (mediaType === 'application/cbor' || mediaType === 'application/x-cbor') {
             return { serializer: new CborSerializer(), contentType: 'application/cbor' };
         }
-        if (t === 'application/json' || t === '*/*') {
+        if (mediaType === 'application/json' || mediaType === '*/*') {
             return { serializer: new JsonSerializer(), contentType: 'application/json; charset=utf-8' };
         }
     }

package/dist/http/Marshalling.js.map

@@ -1 +1 @@
-{"version":3,"file":"Marshalling.js","sourceRoot":"","sources":["../../src/http/Marshalling.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Marshalling.js","sourceRoot":"","sources":["../../src/http/Marshalling.ts"],"names":[],"mappings":"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"}

package/dist/http/MimeTypes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A small, dependency-free MIME-type registry — the response-side sibling
+ * of request marshalling.  Maps a file extension to a content-type for the
+ * static-file directives (and anyone building file responses by hand).
+ */
+/** Extension (lowercase, no dot) → content-type (no charset). */
+export declare const DEFAULT_MIME_TYPES: Readonly<Record<string, string>>;
+/**
+ * Resolve a content-type from a path or bare extension.  Text-ish types
+ * get `; charset=utf-8`; unknown extensions fall back to
+ * `application/octet-stream`.  `overrides` (ext → full content-type, taken
+ * verbatim) win over the defaults.
+ */
+export declare function contentTypeFor(pathOrExt: string, overrides?: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=MimeTypes.d.ts.map

package/dist/http/MimeTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MimeTypes.d.ts","sourceRoot":"","sources":["../../src/http/MimeTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA6C9D,CAAC;AAuBH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAOtG"}

package/dist/http/MimeTypes.js

@@ -0,0 +1,87 @@
+/**
+ * A small, dependency-free MIME-type registry — the response-side sibling
+ * of request marshalling.  Maps a file extension to a content-type for the
+ * static-file directives (and anyone building file responses by hand).
+ */
+/** Extension (lowercase, no dot) → content-type (no charset). */
+export const DEFAULT_MIME_TYPES = Object.freeze({
+    html: 'text/html',
+    htm: 'text/html',
+    xhtml: 'application/xhtml+xml',
+    css: 'text/css',
+    js: 'text/javascript',
+    mjs: 'text/javascript',
+    cjs: 'text/javascript',
+    json: 'application/json',
+    map: 'application/json',
+    webmanifest: 'application/manifest+json',
+    xml: 'application/xml',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    csv: 'text/csv',
+    yaml: 'application/yaml',
+    yml: 'application/yaml',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    apng: 'image/apng',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+    pdf: 'application/pdf',
+    wasm: 'application/wasm',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    wav: 'audio/wav',
+    flac: 'audio/flac',
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    zip: 'application/zip',
+    gz: 'application/gzip',
+    tar: 'application/x-tar',
+    '7z': 'application/x-7z-compressed',
+});
+/** Non-`text/*` types that are still text and should carry a UTF-8 charset. */
+const CHARSET_TYPES = new Set([
+    'application/json',
+    'application/manifest+json',
+    'application/xml',
+    'application/xhtml+xml',
+    'application/yaml',
+    'image/svg+xml',
+]);
+/** Last-segment, last-dot extension, lowercased.  Accepts a path or a bare ext. */
+function extensionOf(pathOrExt) {
+    const segment = pathOrExt.split(/[\\/]/).pop() ?? '';
+    const dot = segment.lastIndexOf('.');
+    return (dot < 0 ? segment : segment.slice(dot + 1)).toLowerCase();
+}
+function needsCharset(type) {
+    return type.startsWith('text/') || CHARSET_TYPES.has(type);
+}
+/**
+ * Resolve a content-type from a path or bare extension.  Text-ish types
+ * get `; charset=utf-8`; unknown extensions fall back to
+ * `application/octet-stream`.  `overrides` (ext → full content-type, taken
+ * verbatim) win over the defaults.
+ */
+export function contentTypeFor(pathOrExt, overrides) {
+    const ext = extensionOf(pathOrExt);
+    const override = overrides?.[ext];
+    if (override)
+        return override;
+    const base = DEFAULT_MIME_TYPES[ext];
+    if (!base)
+        return 'application/octet-stream';
+    return needsCharset(base) ? `${base}; charset=utf-8` : base;
+}
+//# sourceMappingURL=MimeTypes.js.map

package/dist/http/MimeTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MimeTypes.js","sourceRoot":"","sources":["../../src/http/MimeTypes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAqC,MAAM,CAAC,MAAM,CAAC;IAChF,IAAI,EAAE,WAAW;IACjB,GAAG,EAAE,WAAW;IAChB,KAAK,EAAE,uBAAuB;IAC9B,GAAG,EAAE,UAAU;IACf,EAAE,EAAE,iBAAiB;IACrB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;IACtB,IAAI,EAAE,kBAAkB;IACxB,GAAG,EAAE,kBAAkB;IACvB,WAAW,EAAE,2BAA2B;IACxC,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,YAAY;IACjB,EAAE,EAAE,eAAe;IACnB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,kBAAkB;IACxB,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,eAAe;IACpB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,YAAY;IACjB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,cAAc;IACnB,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,iBAAiB;IACtB,IAAI,EAAE,kBAAkB;IACxB,GAAG,EAAE,YAAY;IACjB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,YAAY;IAClB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,iBAAiB;IACtB,EAAE,EAAE,kBAAkB;IACtB,GAAG,EAAE,mBAAmB;IACxB,IAAI,EAAE,6BAA6B;CACpC,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IAC5B,kBAAkB;IAClB,2BAA2B;IAC3B,iBAAiB;IACjB,uBAAuB;IACvB,kBAAkB;IAClB,eAAe;CAChB,CAAC,CAAC;AAEH,mFAAmF;AACnF,SAAS,WAAW,CAAC,SAAiB;IACpC,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,SAA4C;IAC5F,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,0BAA0B,CAAC;IAC7C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC"}

package/dist/http/Route.d.ts

@@ -1,13 +1,73 @@
+import type { ActorSystem } from '../ActorSystem.js';
 import { type HttpMethod, type HttpRequest, type HttpResponse } from './types.js';
+import type { WebsocketSocketAdapter } from './websocket/SocketAdapter.js';
+import { type CorsRouteOptions } from './middleware/Cors.js';
 /**
- * A compiled route — the Route-DSL reduces to a list of these, which the
- * HTTP backend registers in its native routing table.
+ * A compiled HTTP route — the Route-DSL reduces to a list of these
+ * (plus {@link CompiledWebsocketRoute}s), which the HTTP backend
+ * registers in its native routing table.
  */
 export interface CompiledRoute {
+    readonly kind: 'http';
     readonly method: HttpMethod;
     readonly pattern: string;
     readonly handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse;
 }
+/**
+ * Framework-owned entry point for one accepted WebSocket connection.
+ * The backend never sees actors — it only hands us the upgrade request
+ * and a normalised socket; the closure (built by the `websocket()`
+ * directive) owns the codec, target ref and per-route policy.
+ */
+export type WebsocketConnectHandler = (system: ActorSystem, req: HttpRequest, socket: WebsocketSocketAdapter) => void;
+/**
+ * A compiled WebSocket route.  Occupies the `GET` verb at its pattern
+ * (that's how the HTTP upgrade arrives).  `authorize` folds any
+ * enclosing `withMiddleware(...)` — it runs once, against the upgrade
+ * request, and returns `null` to accept or an {@link HttpResponse} to
+ * reject the upgrade with a plain HTTP response.
+ */
+export interface CompiledWebsocketRoute {
+    readonly kind: 'websocket';
+    readonly method: 'GET';
+    readonly pattern: string;
+    readonly connect: WebsocketConnectHandler;
+    readonly authorize: (req: HttpRequest) => Promise<HttpResponse | null>;
+}
+/**
+ * A compiled fallback — answers any request that matched no other route.
+ * Wired to the backend's not-found hook at bind time (exactly one per
+ * server), so unlike {@link CompiledRoute} it carries no method or pattern.
+ */
+export interface CompiledFallback {
+    readonly kind: 'fallback';
+    readonly handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse;
+}
+/** A compiled endpoint: a plain HTTP route, a WebSocket route, or the fallback. */
+export type CompiledEndpoint = CompiledRoute | CompiledWebsocketRoute | CompiledFallback;
+/**
+ * Per-request hook that runs around a handler.  Receives the request
+ * and a `next()` thunk; either short-circuit by returning your own
+ * response, or call `next()` and pass its result through (optionally
+ * wrapped, decorated, or re-thrown).
+ *
+ * `next()` optionally takes a **replacement request** — pass one to
+ * enrich what the handler (and any inner middleware) sees, e.g. to inject
+ * a generated request id or a verified CSRF token as a header.  Omit the
+ * argument to forward the request unchanged; the two forms are otherwise
+ * identical, so existing `next()` call sites keep working.
+ *
+ * Examples (all shipped in `src/http/middleware/`):
+ *   - `BearerTokenAuth({ tokens })` — checks `Authorization: Bearer`,
+ *     short-circuits with 401 on mismatch.
+ *   - `IpAllowlist({ allow })` — checks `remoteAddress` (or a
+ *     configured extractor) against a CIDR list, short-circuits
+ *     with 403 if not allowed.
+ *
+ * Throwing `HttpError(status, msg)` is the idiomatic short-circuit:
+ * the global error handler catches it and emits the right response.
+ */
+export type Middleware = (req: HttpRequest, next: (req?: HttpRequest) => Promise<HttpResponse>) => Promise<HttpResponse> | HttpResponse;
 /**
  * Node type emitted by DSL builders like `path(...)`, `get(...)`.  Internal
  * representation is a tree that knows how to flatten into CompiledRoutes.
@@ -23,6 +83,21 @@ export type Route = {
 } | {
     readonly kind: 'concat';
     readonly routes: ReadonlyArray<Route>;
+} | {
+    readonly kind: 'middleware';
+    readonly middleware: Middleware;
+    readonly child: Route;
+} | {
+    readonly kind: 'websocket';
+    readonly connect: WebsocketConnectHandler;
+    readonly authorize?: (req: HttpRequest) => HttpResponse | null;
+} | {
+    readonly kind: 'fallback';
+    readonly handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse;
+} | {
+    readonly kind: 'cors';
+    readonly settings: CorsRouteOptions;
+    readonly child: Route;
 };
 /** Compose several sibling routes (OR semantics — first matching wins). */
 export declare function concat(...routes: Route[]): Route;
@@ -30,6 +105,72 @@ export declare function concat(...routes: Route[]): Route;
 export declare function path(segment: string, child: Route): Route;
 /** Scope under a path prefix that may capture dynamic segments. */
 export declare function pathPrefix(segment: string, child: Route): Route;
+/**
+ * Wrap every handler in `child`'s subtree with the given `Middleware`.
+ * The middleware runs **before** the handler; it can short-circuit
+ * (return without calling `next()`) or transform the response.
+ *
+ * Nesting composes outside-in: `withMiddleware(a, withMiddleware(b,
+ * get(h)))` runs `a` first, then if it calls `next()`, `b` runs, and
+ * if `b` calls `next()`, the handler `h` runs.
+ *
+ *     const protectedRoutes = withMiddleware(
+ *       BearerTokenAuth({ tokens: [process.env.MGMT_TOKEN!] }),
+ *       withMiddleware(
+ *         IpAllowlist({ allow: ['10.0.0.0/8'] }),
+ *         path('cluster', concat(
+ *           path('down', post(handleDown)),
+ *           path('leave', post(handleLeave)),
+ *         )),
+ *       ),
+ *     );
+ */
+export declare function withMiddleware(middleware: Middleware, child: Route): Route;
+/**
+ * Handler for {@link handleErrors}.  Receives the thrown value (an
+ * {@link HttpError} or anything else) plus the request; return an
+ * {@link HttpResponse} to handle it, or `null`/`undefined` to decline —
+ * declining re-throws so an outer `handleErrors` (or, failing that, the
+ * backend's default mapping) takes over.
+ */
+export type ExceptionHandler = (err: unknown, req: HttpRequest) => Promise<HttpResponse | null | undefined> | HttpResponse | null | undefined;
+/**
+ * Scope an exception handler over `child`'s subtree — the akka-http
+ * `ExceptionHandler` analogue, implemented as sugar over a `middleware`
+ * node so it inherits handler-wrapping (and the WebSocket authorize fold)
+ * for free.
+ *
+ * The handler sees the ORIGINAL thrown value — e.g. the `HttpError`
+ * instance with its `status` / `extra` / `headers` — because DSL-level
+ * wrappers run strictly before any backend's default error mapping.
+ * Handlers nest outside-in like {@link withMiddleware}: the innermost
+ * `handleErrors` gets first refusal, and returning `null` delegates
+ * outward.  Placed around a `withMiddleware(...)` node it also catches
+ * that middleware's throws (e.g. an auth 401).
+ *
+ *     handleErrors(
+ *       (err) => err instanceof NotFoundError ? complete(Status.NotFound, ...) : null,
+ *       path('users', concat(...)),
+ *     )
+ */
+export declare function handleErrors(handler: ExceptionHandler, child: Route): Route;
+/**
+ * Answer any request that matched no other route — the server-global
+ * not-found handler expressed in the DSL.  Wired to the backend's
+ * not-found hook at bind time, so it is method-agnostic (it also answers
+ * unmatched OPTIONS/HEAD) and MUST sit at the root of the tree: a fallback
+ * scoped under `path()` / `pathPrefix()` is rejected at compile time,
+ * because a server has exactly one not-found handler.  At most one
+ * `fallback()` per server.  It still composes with
+ * `withMiddleware()` / `handleErrors()`, which wrap its handler like any
+ * other, so a fallback can carry security headers or its own recovery.
+ *
+ *     concat(
+ *       path('api', apiRoutes),
+ *       fallback((req) => completeJson(Status.NotFound, { error: 'no route', path: req.path })),
+ *     )
+ */
+export declare function fallback(handler: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse): Route;
 export declare const get: (h: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => Route;
 export declare const post: (h: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => Route;
 export declare const put: (h: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse) => Route;
@@ -47,8 +188,16 @@ export declare function completeText(status: number, body: string, headers?: Rec
 export declare function redirect(url: string, status?: number): HttpResponse;
 /** Rejection — throw to short-circuit to a 4xx/5xx. */
 export declare function reject(status: number, message: string, extra?: Record<string, unknown>): never;
-/** Flatten a Route tree into the list of concrete route registrations. */
-export declare function compile(route: Route, prefix?: string[]): CompiledRoute[];
+/**
+ * The framework's default error→response mapping: an {@link HttpError}
+ * becomes its status + `{ error, ...extra }` JSON (carrying any custom
+ * `headers`); anything else becomes a generic 500 that deliberately does
+ * NOT echo the thrown message.  Kept in one place so the WebSocket
+ * upgrade-reject path and the `fallback()` wrapper map errors identically.
+ */
+export declare function defaultErrorResponse(err: unknown): HttpResponse;
+/** Flatten a Route tree into the list of concrete endpoint registrations. */
+export declare function compile(route: Route, prefix?: string[]): CompiledEndpoint[];
 /**
  * Extract a query parameter as a trimmed string, or undefined.  Array-valued
  * params (e.g. `?x=1&x=2`) return the first value.

package/dist/http/Route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Route.d.ts","sourceRoot":"","sources":["../../src/http/Route.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Route.d.ts","sourceRoot":"","sources":["../../src/http/Route.ts"],"names":[],"mappings":"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"}