@xfcfam/xf-server-http 0.1.0

package/dist/src/business/general/HttpServerBusiness.js

@@ -0,0 +1,364 @@
+import { NotInitializedException } from '@xfcfam/xf';
+import { ServerBusiness } from '@xfcfam/xf-server';
+import fastify from 'fastify';
+import { HttpException } from '../transfers/HttpException.js';
+/**
+ * Business-Layer Generalization for the artefact-level HTTP server
+ * orchestrator — the Fastify implementation of the transport-agnostic
+ * {@link ServerBusiness} contract from `@xfcfam/xf-server`.
+ *
+ * It is **technology-aware** (Fastify, HTTP) by design: the Business
+ * Layer in XF is the correct home for infrastructure concerns that are
+ * not domain rules — the HTTP server is infrastructure, not domain
+ * logic. The route registry and the request pipeline come from the
+ * core; this class supplies the HTTP address scheme (`{ method, path }`),
+ * the Fastify lifecycle (`listen` / `close`), body collection
+ * (including multipart) and the error → HTTP-status mapping.
+ *
+ * **Registration model — push, not pull.** Interaction Services register
+ * their routes by calling `B.server.get(path, handler)` (or `post`,
+ * `put`, `patch`, `del`, `call`) from within their own `init()`. The
+ * server MUST be created and available on `B` before `A.init()` runs;
+ * `listen()` is called by the start-point AFTER all services have
+ * registered.
+ *
+ * **Handler contract.** Handlers are `HttpHandler` functions
+ * (`(req: HttpRequest) => Promise<HttpResponse> | HttpResponse`). The
+ * server calls them with an `HttpRequest` whose `body` is the raw
+ * bytes/stream (or a `MultipartPart[]` for multipart requests).
+ * Serialisation (object → bytes) and parsing (bytes → object) are the
+ * Interaction Layer's responsibility — see `ObjectRestService.object()`.
+ *
+ * @example
+ * ```ts
+ * // business/logic/AppServerBusiness.ts
+ * import { HttpServerBusiness, type HttpRequest } from '@xfcfam/xf-server-http'
+ *
+ * export class AppServerBusiness extends HttpServerBusiness {
+ *   constructor() {
+ *     super({ port: Number.parseInt(process.env['PORT'] ?? '3000', 10) })
+ *   }
+ *
+ *   override async onRequest(req: HttpRequest): Promise<HttpRequest> {
+ *     console.log(`[server] → ${req.method} ${req.path}`)
+ *     return req
+ *   }
+ * }
+ *
+ * // business/B.ts
+ * export class B {
+ *   private constructor() {}
+ *   static readonly server = new AppServerBusiness()
+ *   static async init()      { await B.server.init() }
+ *   static async terminate() { await B.server.terminate() }
+ * }
+ *
+ * // main.ts (start-point): once the XF element has bootstrapped the
+ * // layers R → B → A and the services have pushed their routes, start
+ * // the transport explicitly:
+ * await B.server.listen()    // start Fastify after all routes are in
+ * // ...and on shutdown, before the XF element tears the layers down:
+ * await B.server.close()
+ * ```
+ */
+export class HttpServerBusiness extends ServerBusiness {
+    constructor(options) {
+        super({ options, fastify: undefined, routes: [], wsRoutes: [], graphql: undefined });
+    }
+    // ─── Route registration (push) ────────────────────────────
+    /** Register a GET endpoint. */
+    get(path, handler) {
+        this.call('GET', path, handler);
+    }
+    /** Register a POST endpoint. */
+    post(path, handler) {
+        this.call('POST', path, handler);
+    }
+    /** Register a PUT endpoint. */
+    put(path, handler) {
+        this.call('PUT', path, handler);
+    }
+    /** Register a PATCH endpoint. */
+    patch(path, handler) {
+        this.call('PATCH', path, handler);
+    }
+    /** Register a DELETE endpoint. */
+    del(path, handler) {
+        this.call('DELETE', path, handler);
+    }
+    /**
+     * Register an endpoint for an arbitrary HTTP method. Used for
+     * `HEAD`, `OPTIONS`, or any verb not covered by the convenience
+     * helpers.
+     */
+    call(method, path, handler) {
+        this.register({ method, path }, handler);
+    }
+    /**
+     * Register a WebSocket endpoint. The handler receives a
+     * {@link WebSocketConnection} once the client upgrade completes. The
+     * WebSocket plugin runs on the same Fastify instance and port as the
+     * REST routes; like every registration, call this before `listen()`.
+     */
+    ws(path, handler) {
+        this.state.wsRoutes.push({ path, handler });
+    }
+    /**
+     * Register a GraphQL endpoint (schema + resolvers). The GraphQL
+     * engine (Mercurius) is mounted on the shared Fastify instance at
+     * `config.path` (default `/graphql`). At most one GraphQL endpoint per
+     * server; a later call replaces the earlier config.
+     */
+    graphql(config) {
+        this.state.graphql = config;
+    }
+    // ─── Lifecycle ────────────────────────────────────────────
+    /**
+     * Start accepting requests. Creates the Fastify instance, registers
+     * multipart support if configured, mounts every route that has been
+     * pushed so far, and begins listening.
+     *
+     * Call this from the start-point AFTER the Interaction layer has
+     * registered all routes — no new routes should be pushed after this
+     * point.
+     */
+    async listen() {
+        const instance = fastify({ logger: false });
+        this.state.fastify = instance;
+        if (this.state.options.multipart !== undefined && this.state.options.multipart !== false) {
+            await HttpServerBusiness.registerMultipart(instance, this.state.options.multipart);
+        }
+        // WebSocket plugin must be registered before its routes are defined.
+        if (this.state.wsRoutes.length > 0) {
+            await HttpServerBusiness.registerWebSocket(instance, this.state.wsRoutes);
+        }
+        for (const route of this.routes) {
+            instance.route({
+                method: route.address.method,
+                url: route.address.path,
+                handler: this.adapter(route.address.method, route.address.path, route.handler),
+            });
+        }
+        if (this.state.graphql !== undefined) {
+            await HttpServerBusiness.registerGraphQL(instance, this.state.graphql);
+        }
+        await instance.listen({
+            port: this.state.options.port,
+            host: this.state.options.host ?? '0.0.0.0',
+        });
+        await this.onStarted();
+    }
+    /**
+     * Stop accepting requests and release the Fastify instance. Waits
+     * for in-flight requests to complete before resolving.
+     */
+    async close() {
+        if (this.state.fastify !== undefined) {
+            await this.state.fastify.close();
+            this.state.fastify = undefined;
+        }
+        await this.onStopped();
+    }
+    // ─── Protected accessor ───────────────────────────────────
+    /**
+     * Get the underlying Fastify instance. Throws if `listen()` hasn't
+     * run. Exposed so protocol extensions (WebSocket, GraphQL) can
+     * register their plugins on the same instance.
+     */
+    fastifyInstance() {
+        if (this.state.fastify === undefined) {
+            throw new NotInitializedException('HttpServerBusiness: listen() has not been called.');
+        }
+        return this.state.fastify;
+    }
+    // ─── Internals ─────────────────────────────────────────────
+    adapter(method, path, handler) {
+        return async (fastifyReq, fastifyReply) => {
+            const req = await HttpServerBusiness.request(fastifyReq, method, path);
+            const res = await this.dispatch(req, handler, HttpServerBusiness.errorToResponse);
+            await HttpServerBusiness.sendResponse(fastifyReply, res);
+        };
+    }
+    static async request(fr, method, path) {
+        let body = fr.body;
+        // If @fastify/multipart is active and this is a multipart request,
+        // collect the parts into our MultipartPart[] shape so handlers
+        // see a uniform body regardless of the underlying engine.
+        const contentType = String(fr.headers['content-type'] ?? '').toLowerCase();
+        if (contentType.startsWith('multipart/') && typeof fr.parts === 'function') {
+            body = await HttpServerBusiness.collectMultipart(fr);
+        }
+        return {
+            method,
+            path,
+            params: fr.params,
+            query: fr.query,
+            headers: fr.headers,
+            body,
+        };
+    }
+    static async collectMultipart(fr) {
+        const out = [];
+        for await (const raw of fr.parts()) {
+            const p = raw;
+            if (p.type === 'file') {
+                const bytes = await HttpServerBusiness.collectNodeStream(p.file);
+                const part = {
+                    field: p.fieldname,
+                    mimeType: p.mimetype ?? 'application/octet-stream',
+                    body: bytes,
+                    ...(p.filename !== undefined ? { filename: p.filename } : {}),
+                    size: bytes.byteLength,
+                };
+                out.push(part);
+            }
+            else {
+                const value = String(p.value ?? '');
+                out.push({
+                    field: p.fieldname,
+                    mimeType: 'text/plain',
+                    body: new TextEncoder().encode(value),
+                    size: value.length,
+                });
+            }
+        }
+        return out;
+    }
+    static async collectNodeStream(stream) {
+        const chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        }
+        const total = chunks.reduce((acc, c) => acc + c.byteLength, 0);
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+            out.set(c, offset);
+            offset += c.byteLength;
+        }
+        return out;
+    }
+    static async registerMultipart(instance, config) {
+        // `@fastify/multipart` is a direct dependency of xf-server-http (the
+        // package is encapsulated end-to-end). We load it lazily — only
+        // when the user opts in via `multipart: true | {...}` — to keep
+        // the cold-start of multipart-free services minimal.
+        const mod = await import('@fastify/multipart');
+        const plugin = mod.default ?? mod;
+        const opts = config === true ? {} : {
+            limits: {
+                ...(config.maxFileSize !== undefined ? { fileSize: config.maxFileSize } : {}),
+                ...(config.maxFiles !== undefined ? { files: config.maxFiles } : {}),
+                ...(config.maxFields !== undefined ? { fields: config.maxFields } : {}),
+                ...(config.maxFieldsSize !== undefined ? { fieldSize: config.maxFieldsSize } : {}),
+            },
+        };
+        await instance.register(plugin, opts);
+    }
+    static async registerWebSocket(instance, routes) {
+        // `@fastify/websocket` is a direct dependency of xf-server-http,
+        // lazy-loaded only when WebSocket endpoints are declared. The
+        // dynamic specifier is resolved at runtime; the plugin's Fastify
+        // type augmentation is applied through a loose local shape.
+        const spec = '@fastify/websocket';
+        const mod = await import(spec);
+        const plugin = mod.default ?? mod;
+        const app = instance;
+        await app.register(plugin);
+        for (const route of routes) {
+            app.get(route.path, { websocket: true }, (socket, req) => {
+                void route.handler(HttpServerBusiness.adaptSocket(socket, req, route.path));
+            });
+        }
+    }
+    static adaptSocket(socket, req, path) {
+        const s = socket;
+        const r = req;
+        return {
+            path,
+            params: (r.params ?? {}),
+            query: (r.query ?? {}),
+            headers: (r.headers ?? {}),
+            send: (data) => s.send(data),
+            close: (code, reason) => s.close(code, reason),
+            onMessage: (listener) => s.on('message', (data) => listener(HttpServerBusiness.toFrame(data))),
+            onClose: (listener) => s.on('close', (code, reason) => listener(Number(code ?? 0), String(reason ?? ''))),
+            onError: (listener) => s.on('error', (err) => listener(err instanceof Error ? err : new Error(String(err)))),
+        };
+    }
+    static toFrame(data) {
+        if (typeof data === 'string')
+            return data;
+        if (data instanceof Uint8Array)
+            return data;
+        if (data instanceof ArrayBuffer)
+            return new Uint8Array(data);
+        if (Array.isArray(data)) {
+            const parts = data;
+            const total = parts.reduce((n, c) => n + c.byteLength, 0);
+            const out = new Uint8Array(total);
+            let offset = 0;
+            for (const c of parts) {
+                out.set(c, offset);
+                offset += c.byteLength;
+            }
+            return out;
+        }
+        return String(data);
+    }
+    static async registerGraphQL(instance, config) {
+        // `mercurius` is a direct dependency of xf-server-http, lazy-loaded
+        // only when a GraphQL endpoint is declared.
+        const spec = 'mercurius';
+        const mod = await import(spec);
+        const plugin = mod.default ?? mod;
+        const app = instance;
+        await app.register(plugin, {
+            schema: config.schema,
+            resolvers: config.resolvers,
+            graphiql: config.graphiql ?? false,
+            path: config.path ?? '/graphql',
+        });
+    }
+    static async sendResponse(reply, res) {
+        reply.status(res.status);
+        if (res.headers !== undefined) {
+            for (const [k, v] of Object.entries(res.headers))
+                reply.header(k, v);
+        }
+        const body = res.body;
+        if (body === null || body === undefined) {
+            await reply.send();
+            return;
+        }
+        if (HttpServerBusiness.isReadableStream(body)) {
+            // Web ReadableStream → Node Readable for Fastify.
+            const { Readable } = await import('node:stream');
+            await reply.send(Readable.fromWeb(body));
+            return;
+        }
+        if (body instanceof Uint8Array) {
+            await reply.send(Buffer.from(body.buffer, body.byteOffset, body.byteLength));
+            return;
+        }
+        if (typeof body === 'string') {
+            await reply.send(body);
+            return;
+        }
+        // Anything else: pass through (Fastify will JSON-encode objects).
+        await reply.send(body);
+    }
+    static errorToResponse(err) {
+        if (err instanceof HttpException) {
+            return { status: err.status, body: err.body };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { status: 500, body: { message: 'Internal server error', detail: message } };
+    }
+    static isReadableStream(value) {
+        return typeof value === 'object'
+            && value !== null
+            && typeof value.getReader === 'function';
+    }
+}
+//# sourceMappingURL=HttpServerBusiness.js.map

package/dist/src/business/general/HttpServerBusiness.js.map

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

package/dist/src/business/transfers/BadRequestException.d.ts

@@ -0,0 +1,13 @@
+import { HttpException } from './HttpException.js';
+/**
+ * Interaction-layer Exception — HTTP 400.
+ *
+ * Client error — the request is malformed (missing fields, invalid types, validation failure).
+ *
+ * Use `throw new BadRequestException('message')` inside a handler; the
+ * server pipeline translates it into a 400 response automatically.
+ */
+export declare class BadRequestException extends HttpException {
+    constructor(message: string, body?: unknown);
+}
+//# sourceMappingURL=BadRequestException.d.ts.map

package/dist/src/business/transfers/BadRequestException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BadRequestException.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/BadRequestException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;;;;;GAOG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAI5C"}

package/dist/src/business/transfers/BadRequestException.js

@@ -0,0 +1,16 @@
+import { HttpException } from './HttpException.js';
+/**
+ * Interaction-layer Exception — HTTP 400.
+ *
+ * Client error — the request is malformed (missing fields, invalid types, validation failure).
+ *
+ * Use `throw new BadRequestException('message')` inside a handler; the
+ * server pipeline translates it into a 400 response automatically.
+ */
+export class BadRequestException extends HttpException {
+    constructor(message, body) {
+        super(400, message, body);
+        this.name = 'BadRequestException';
+    }
+}
+//# sourceMappingURL=BadRequestException.js.map

package/dist/src/business/transfers/BadRequestException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BadRequestException.js","sourceRoot":"","sources":["../../../../src/business/transfers/BadRequestException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD,YAAY,OAAe,EAAE,IAAc;QACzC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/src/business/transfers/ForbiddenException.d.ts

@@ -0,0 +1,13 @@
+import { HttpException } from './HttpException.js';
+/**
+ * Interaction-layer Exception — HTTP 403.
+ *
+ * Authentication succeeded but the principal is not allowed to perform the action.
+ *
+ * Use `throw new ForbiddenException('message')` inside a handler; the
+ * server pipeline translates it into a 403 response automatically.
+ */
+export declare class ForbiddenException extends HttpException {
+    constructor(message: string, body?: unknown);
+}
+//# sourceMappingURL=ForbiddenException.d.ts.map

package/dist/src/business/transfers/ForbiddenException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForbiddenException.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/ForbiddenException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAI5C"}

package/dist/src/business/transfers/ForbiddenException.js

@@ -0,0 +1,16 @@
+import { HttpException } from './HttpException.js';
+/**
+ * Interaction-layer Exception — HTTP 403.
+ *
+ * Authentication succeeded but the principal is not allowed to perform the action.
+ *
+ * Use `throw new ForbiddenException('message')` inside a handler; the
+ * server pipeline translates it into a 403 response automatically.
+ */
+export class ForbiddenException extends HttpException {
+    constructor(message, body) {
+        super(403, message, body);
+        this.name = 'ForbiddenException';
+    }
+}
+//# sourceMappingURL=ForbiddenException.js.map

package/dist/src/business/transfers/ForbiddenException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForbiddenException.js","sourceRoot":"","sources":["../../../../src/business/transfers/ForbiddenException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD,YAAY,OAAe,EAAE,IAAc;QACzC,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF"}

package/dist/src/business/transfers/GraphQLConfig.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Business-layer Transfer — a GraphQL endpoint registration.
+ *
+ * Carries everything the server needs to mount a GraphQL API on the
+ * shared Fastify instance (via Mercurius): the SDL schema, the resolver
+ * map, the mount path, and whether to serve the GraphiQL IDE.
+ *
+ * `GraphQLService` builds this and pushes it with
+ * `B.server.graphql(config)` from its `init()`.
+ */
+export interface GraphQLConfig {
+    /** GraphQL schema in SDL (Schema Definition Language) form. */
+    readonly schema: string;
+    /**
+     * Resolver map: `{ Query: {...}, Mutation: {...}, <Type>: {...} }`.
+     * Shape is engine-defined; kept opaque here to avoid a hard
+     * dependency on the GraphQL types at the contract level.
+     */
+    readonly resolvers: Readonly<Record<string, unknown>>;
+    /** Mount path for the endpoint. Default `'/graphql'`. */
+    readonly path?: string;
+    /** Serve the GraphiQL IDE at the mount path. Default `false`. */
+    readonly graphiql?: boolean;
+}
+//# sourceMappingURL=GraphQLConfig.d.ts.map

package/dist/src/business/transfers/GraphQLConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphQLConfig.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/GraphQLConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACrD,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B"}

package/dist/src/business/transfers/GraphQLConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=GraphQLConfig.js.map

package/dist/src/business/transfers/GraphQLConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphQLConfig.js","sourceRoot":"","sources":["../../../../src/business/transfers/GraphQLConfig.ts"],"names":[],"mappings":""}

package/dist/src/business/transfers/HttpException.d.ts

@@ -0,0 +1,23 @@
+import { ServerException } from '@xfcfam/xf-server';
+/**
+ * Business-layer Exception — base class for typed HTTP errors raised
+ * inside a handler. The HTTP specialisation of the transport-agnostic
+ * {@link ServerException}: it adds the numeric HTTP `status` that the
+ * server maps onto the wire.
+ *
+ * The server pipeline catches every `HttpException`, reads its
+ * `status` and `body`, and writes the corresponding HTTP response.
+ * Subclasses for common cases (`BadRequestException`,
+ * `NotFoundException`, …) preset the status; custom domain errors can
+ * extend this class with any status and shape.
+ *
+ * Non-`HttpException` errors raised by a handler are routed to the
+ * `onError` hooks; if no hook produces a response, the server emits a
+ * generic `500 Internal Server Error`.
+ */
+export declare class HttpException extends ServerException {
+    /** HTTP status code to send to the client. */
+    readonly status: number;
+    constructor(status: number, message: string, body?: unknown);
+}
+//# sourceMappingURL=HttpException.d.ts.map

package/dist/src/business/transfers/HttpException.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpException.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/HttpException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,aAAc,SAAQ,eAAe;IAChD,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;gBAEX,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAK5D"}

package/dist/src/business/transfers/HttpException.js

@@ -0,0 +1,27 @@
+import { ServerException } from '@xfcfam/xf-server';
+/**
+ * Business-layer Exception — base class for typed HTTP errors raised
+ * inside a handler. The HTTP specialisation of the transport-agnostic
+ * {@link ServerException}: it adds the numeric HTTP `status` that the
+ * server maps onto the wire.
+ *
+ * The server pipeline catches every `HttpException`, reads its
+ * `status` and `body`, and writes the corresponding HTTP response.
+ * Subclasses for common cases (`BadRequestException`,
+ * `NotFoundException`, …) preset the status; custom domain errors can
+ * extend this class with any status and shape.
+ *
+ * Non-`HttpException` errors raised by a handler are routed to the
+ * `onError` hooks; if no hook produces a response, the server emits a
+ * generic `500 Internal Server Error`.
+ */
+export class HttpException extends ServerException {
+    /** HTTP status code to send to the client. */
+    status;
+    constructor(status, message, body) {
+        super(message, body);
+        this.name = 'HttpException';
+        this.status = status;
+    }
+}
+//# sourceMappingURL=HttpException.js.map

package/dist/src/business/transfers/HttpException.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpException.js","sourceRoot":"","sources":["../../../../src/business/transfers/HttpException.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,aAAc,SAAQ,eAAe;IAChD,8CAA8C;IACrC,MAAM,CAAQ;IAEvB,YAAY,MAAc,EAAE,OAAe,EAAE,IAAc;QACzD,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/dist/src/business/transfers/HttpMethod.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Canonical HTTP methods supported by the server. The union is closed:
+ * exotic verbs (`CONNECT`, `TRACE`, `PROPFIND`, …) are intentionally
+ * out of scope for v0 and can be added in extension packages.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+//# sourceMappingURL=HttpMethod.d.ts.map

package/dist/src/business/transfers/HttpMethod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpMethod.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/HttpMethod.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,MAAM,GACN,KAAK,GACL,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,CAAA"}

package/dist/src/business/transfers/HttpMethod.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=HttpMethod.js.map

package/dist/src/business/transfers/HttpMethod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpMethod.js","sourceRoot":"","sources":["../../../../src/business/transfers/HttpMethod.ts"],"names":[],"mappings":""}

package/dist/src/business/transfers/HttpRequest.d.ts

@@ -0,0 +1,35 @@
+import type { HttpMethod } from './HttpMethod.js';
+/**
+ * Interaction-layer Transfer — a single incoming HTTP request as seen
+ * by a `RestService` handler.
+ *
+ * `body` is parameterised so each handler can declare its expected
+ * shape. By default it is `unknown` — at the `RestService` level the
+ * body arrives as a raw stream or `Uint8Array`; the
+ * `ObjectRestService` subclass parses it according to the
+ * `Content-Type` and surfaces it as a typed object.
+ *
+ * Streaming uploads are first-class: when the underlying transport
+ * supplies the body as a `ReadableStream<Uint8Array>`, it is carried
+ * through here without buffering. The handler decides whether to
+ * consume it incrementally or to read it into memory.
+ */
+export interface HttpRequest<TBody = unknown> {
+    /** HTTP method. */
+    readonly method: HttpMethod;
+    /** Resolved path (after route matching). */
+    readonly path: string;
+    /** Route parameters extracted from the path (`/users/:id` → `{ id: '42' }`). */
+    readonly params: Readonly<Record<string, string>>;
+    /** Query-string parameters. */
+    readonly query: Readonly<Record<string, string | readonly string[]>>;
+    /** Lowercased header name → value (or array for repeated headers). */
+    readonly headers: Readonly<Record<string, string | readonly string[]>>;
+    /**
+     * Request body. May be `null`, a `Uint8Array`, a
+     * `ReadableStream<Uint8Array>` for incremental consumption, or any
+     * parsed value when an `ObjectRestService` has run its parsers.
+     */
+    readonly body: TBody;
+}
+//# sourceMappingURL=HttpRequest.d.ts.map

package/dist/src/business/transfers/HttpRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpRequest.d.ts","sourceRoot":"","sources":["../../../../src/business/transfers/HttpRequest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,OAAO;IAC1C,mBAAmB;IACnB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IACpE,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IACtE;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CACrB"}

package/dist/src/business/transfers/HttpRequest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=HttpRequest.js.map

package/dist/src/business/transfers/HttpRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpRequest.js","sourceRoot":"","sources":["../../../../src/business/transfers/HttpRequest.ts"],"names":[],"mappings":""}