@lakutata/entrypoint 3.0.0-beta.0

package/dist/cjs/adapter/fastify/FastifyHTTPEntrypoint.d.ts

@@ -0,0 +1,156 @@
+import { type FastifyInstance, type FastifyReply, type FastifyRequest, type FastifyServerOptions } from 'fastify';
+import type { Server } from 'node:http';
+import type { Module } from '@lakutata/core';
+import type { EntrypointAdapter } from '../../channel/EntrypointAdapter.js';
+import type { MiddlewareDefinition } from '../../lib/Middleware.js';
+import { HTTPContext } from '../../context/HTTPContext.js';
+import { type FastifyResponder } from './Responders.js';
+/**
+ * What the `before` hook of {@link fastifyHTTPEntrypoint} receives besides the fastify instance: the entrypoint's
+ * module, the HTTP server (not listening yet) and the routes the actions will occupy.
+ */
+export type FastifyHookContext = {
+    /**
+     * The module owning the entrypoint, to get the application's objects from (`await module.getObject('db')`).
+     */
+    readonly module: Module;
+    /**
+     * The HTTP server of the fastify instance. It does not listen yet when the hook runs; attach other servers to it
+     * there (such as a socket.io server, see the `server` option of `socketIOServiceEntrypoint`).
+     */
+    readonly server: Server;
+    /**
+     * Each action route mapped to its HTTP methods, in upper case (`'/users/:id'` → `{'GET', 'DELETE'}`).
+     */
+    readonly routes: Map<string, Set<string>>;
+    /**
+     * The first segment of each action route (`'/device'`, `'/user'`…). A route starting with a parameter (`/:id`)
+     * adds none.
+     */
+    readonly actionPrefixes: string[];
+    /**
+     * Tell whether a request path belongs to the actions: it equals one of the action prefixes or starts with one
+     * followed by `/`.
+     */
+    readonly isActionPath: (requestPath: string) => boolean;
+};
+/**
+ * The options of {@link fastifyHTTPEntrypoint}.
+ */
+export type FastifyHTTPEntrypointOptions = {
+    /**
+     * The adapter name, to tell apart several HTTP adapters of one entrypoint.
+     */
+    name?: string;
+    /**
+     * The port the server listens on; 0 picks a random free port. The entrypoint fails to start when the port is in use.
+     * @default 80
+     */
+    port?: number;
+    /**
+     * The host or address the server listens on.
+     * @default every interface, as the other HTTP adapters (`::`, or `0.0.0.0` without IPv6)
+     */
+    host?: string;
+    /**
+     * An existing fastify instance to add the action routes to, or the options of the instance to create (`bodyLimit`,
+     * `trustProxy`, `logger`…). The adapter closes the instance when it stops, a given one included.
+     * @default a new fastify instance with its default options (a body limit of 1 MiB)
+     */
+    fastify?: FastifyInstance | FastifyServerOptions;
+    /**
+     * Build an action's input from a request. The route parameters are always merged over its result.
+     * @default the query parameters, then the properties of an object body over them (an array body is ignored)
+     */
+    input?: (request: FastifyRequest) => Record<string, unknown>;
+    /**
+     * How the results and the errors of the actions are written.
+     * @default FastifyJSONResponder
+     */
+    respond?: FastifyResponder;
+    /**
+     * The middlewares of this adapter's actions, run after the entrypoint's global middlewares.
+     */
+    middlewares?: MiddlewareDefinition[];
+    /**
+     * Run before the action routes are added, to register the application's own plugins, hooks and routes. A failure
+     * fails the entrypoint start.
+     */
+    before?: (app: FastifyInstance, context: FastifyHookContext) => void | Promise<void>;
+    /**
+     * The handler of the requests that match no route and whose path is outside the action prefixes, such as the pages
+     * of a web application. The unmatched requests inside the action prefixes, and all of them without a fallback, are
+     * answered with a `RouteNotFoundException` (404).
+     */
+    fallback?: (request: FastifyRequest, reply: FastifyReply) => unknown;
+    /**
+     * Run when the adapter stops, after the server is closed.
+     */
+    stop?: () => void | Promise<void>;
+    /**
+     * The interval between the comments keeping the event streams (`EventsResult`) alive through the proxies, in
+     * milliseconds.
+     * @default 15000
+     */
+    heartbeat?: number;
+};
+/**
+ * Create the HTTP adapter of an entrypoint served by a fastify instance: each HTTP action (`@GET`, `@POST`,
+ * `@HTTPAction`…) becomes a fastify route. It needs the optional peer dependency `fastify`.
+ *
+ * An action's input is the request's query and body (see the `input` option) with the route parameters merged over
+ * them. Its result is written by the responder (JSON by default, 204 for no result); a `StatusResult` sets the status
+ * and the headers, a `FileResult` sends a file, a buffer or a stream (its content type guessed from the extension of
+ * its file name, 304 when its ETag matches `If-None-Match`), and an `EventsResult` streams Server-Sent Events. An action
+ * that writes the response itself (through `HTTPContext.response`) is left alone. The errors, those of fastify included
+ * (a body too large: 413, a malformed JSON body: 400), are written by the responder with their status (500 by default).
+ * A GET action also answers HEAD, unless a HEAD action is declared for its route.
+ *
+ * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
+ * entrypoint stops, fastify stops accepting connections and answers the new requests with 503, the event streams end,
+ * and the requests in progress are given up to one second after they settle to send their responses before the
+ * remaining connections are closed.
+ * @param options The adapter options; by default it listens on port 80 with a new fastify instance.
+ * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET, POST} from 'lakutata/decorator/ctrl'
+ * import {fastifyHTTPEntrypoint} from 'lakutata/adapter/fastify'
+ *
+ * class UserController extends Controller {
+ *     //GET /users/1?verbose=true: the route parameter id merged over the query
+ *     @GET('/users/:id')
+ *     public async get(input: {id: string, verbose?: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ *
+ *     //POST /users with the JSON body {"name": "Ada"}
+ *     @POST('/users')
+ *     public async create(input: {name: string}): Promise<{name: string}> {
+ *         return {name: input.name}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 host: '0.0.0.0',
+ *                 fastify: {bodyLimit: 5 * 1024 * 1024, trustProxy: true},
+ *                 //The application's own routes
+ *                 before: (app): void => {
+ *                     app.get('/health', async (): Promise<string> => 'ok')
+ *                 }
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function fastifyHTTPEntrypoint(options?: FastifyHTTPEntrypointOptions): EntrypointAdapter<HTTPContext>;

package/dist/cjs/adapter/fastify/FastifyHTTPEntrypoint.js

@@ -0,0 +1,339 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastifyHTTPEntrypoint = fastifyHTTPEntrypoint;
+const fastify_1 = __importDefault(require("fastify"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const HTTPContext_js_1 = require("../../context/HTTPContext.js");
+const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
+const Result_js_1 = require("../../lib/Result.js");
+const RouteNotFoundException_js_1 = require("../../exceptions/RouteNotFoundException.js");
+const Responders_js_1 = require("./Responders.js");
+/**
+ * The content types of the common file extensions
+ */
+const CONTENT_TYPES = {
+    '.txt': 'text/plain; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8',
+    '.xml': 'application/xml; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip'
+};
+/**
+ * The first segments of the routes
+ * @param routes
+ */
+function actionPrefixesOf(routes) {
+    const prefixes = new Set();
+    for (const route of routes) {
+        const segment = route.split('/').find((part) => !!part);
+        //A route starting with a parameter matches every path
+        if (segment && !/^[:*]/.test(segment))
+            prefixes.add(`/${segment}`);
+    }
+    return [...prefixes];
+}
+/**
+ * The data of an event of a stream
+ * @param data
+ * @param event
+ * @param id
+ */
+function eventFrame(data, event, id) {
+    let frame = '';
+    if (id !== undefined)
+        frame += `id: ${id}\n`;
+    if (event !== undefined)
+        frame += `event: ${event}\n`;
+    const text = typeof data === 'string' ? data : JSON.stringify(data);
+    for (const line of text.split(/\r?\n/))
+        frame += `data: ${line}\n`;
+    return `${frame}\n`;
+}
+/**
+ * Whether a value is a fastify instance
+ * @param value
+ */
+function isFastifyInstance(value) {
+    return !!value && typeof value.route === 'function' && typeof value.listen === 'function';
+}
+/**
+ * Create the HTTP adapter of an entrypoint served by a fastify instance: each HTTP action (`@GET`, `@POST`,
+ * `@HTTPAction`…) becomes a fastify route. It needs the optional peer dependency `fastify`.
+ *
+ * An action's input is the request's query and body (see the `input` option) with the route parameters merged over
+ * them. Its result is written by the responder (JSON by default, 204 for no result); a `StatusResult` sets the status
+ * and the headers, a `FileResult` sends a file, a buffer or a stream (its content type guessed from the extension of
+ * its file name, 304 when its ETag matches `If-None-Match`), and an `EventsResult` streams Server-Sent Events. An action
+ * that writes the response itself (through `HTTPContext.response`) is left alone. The errors, those of fastify included
+ * (a body too large: 413, a malformed JSON body: 400), are written by the responder with their status (500 by default).
+ * A GET action also answers HEAD, unless a HEAD action is declared for its route.
+ *
+ * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
+ * entrypoint stops, fastify stops accepting connections and answers the new requests with 503, the event streams end,
+ * and the requests in progress are given up to one second after they settle to send their responses before the
+ * remaining connections are closed.
+ * @param options The adapter options; by default it listens on port 80 with a new fastify instance.
+ * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET, POST} from 'lakutata/decorator/ctrl'
+ * import {fastifyHTTPEntrypoint} from 'lakutata/adapter/fastify'
+ *
+ * class UserController extends Controller {
+ *     //GET /users/1?verbose=true: the route parameter id merged over the query
+ *     @GET('/users/:id')
+ *     public async get(input: {id: string, verbose?: string}): Promise<{id: string}> {
+ *         return {id: input.id}
+ *     }
+ *
+ *     //POST /users with the JSON body {"name": "Ada"}
+ *     @POST('/users')
+ *     public async create(input: {name: string}): Promise<{name: string}> {
+ *         return {name: input.name}
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [UserController],
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 host: '0.0.0.0',
+ *                 fastify: {bodyLimit: 5 * 1024 * 1024, trustProxy: true},
+ *                 //The application's own routes
+ *                 before: (app): void => {
+ *                     app.get('/health', async (): Promise<string> => 'ok')
+ *                 }
+ *             })
+ *         })
+ *     }
+ * })
+ * ```
+ */
+function fastifyHTTPEntrypoint(options = {}) {
+    const respond = options.respond ?? Responders_js_1.FastifyJSONResponder;
+    const input = options.input ?? ((request) => ({
+        ...(request.query && typeof request.query === 'object' ? request.query : {}),
+        ...(request.body && typeof request.body === 'object' && !Array.isArray(request.body) ? request.body : {})
+    }));
+    const streams = new Set();
+    let app;
+    let closed;
+    let stopping = false;
+    //The responses not sent yet
+    const responding = new Set();
+    /**
+     * Stream the events of a result
+     * @param result
+     * @param reply
+     */
+    const streamEvents = async (result, reply) => {
+        const abortController = new AbortController();
+        streams.add(abortController);
+        reply.hijack();
+        const response = reply.raw;
+        response.writeHead(200, {
+            ...reply.getHeaders(),
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache, no-transform',
+            'Connection': 'keep-alive',
+            'X-Accel-Buffering': 'no'
+        });
+        response.flushHeaders();
+        const heartbeat = setInterval(() => response.write(': ping\n\n'), options.heartbeat ?? 15000);
+        const close = () => abortController.abort();
+        response.on('close', close);
+        try {
+            await result.producer((data, event, id) => {
+                if (!abortController.signal.aborted)
+                    response.write(eventFrame(data, event, id));
+            }, abortController.signal);
+        }
+        catch {
+            //The stream is already started, its error ends it
+        }
+        finally {
+            clearInterval(heartbeat);
+            response.off('close', close);
+            streams.delete(abortController);
+            if (!response.writableEnded)
+                response.end();
+        }
+    };
+    /**
+     * Send a file
+     * @param result
+     * @param request
+     * @param reply
+     */
+    const sendFile = async (result, request, reply) => {
+        const { contentType, filename, etag, headers } = result.options;
+        if (headers)
+            reply.headers(headers);
+        if (etag) {
+            reply.header('ETag', `"${etag}"`);
+            if (request.headers['if-none-match'] === `"${etag}"`) {
+                await reply.code(304).send();
+                return;
+            }
+        }
+        const source = result.source;
+        const name = filename ?? (typeof source === 'string' ? node_path_1.default.basename(source) : undefined);
+        if (filename)
+            reply.header('Content-Disposition', `attachment; filename="${encodeURIComponent(filename)}"`);
+        reply.type(contentType ?? (name && CONTENT_TYPES[node_path_1.default.extname(name).toLowerCase()]) ?? 'application/octet-stream');
+        await reply.send(typeof source === 'string' ? (0, node_fs_1.createReadStream)(node_path_1.default.resolve(source)) : source);
+    };
+    /**
+     * Write the result of an action
+     * @param result
+     * @param request
+     * @param reply
+     */
+    const output = async (result, request, reply) => {
+        //The action wrote the response itself
+        if (reply.sent || reply.raw.headersSent)
+            return;
+        if (result instanceof Result_js_1.EventsResult)
+            return await streamEvents(result, reply);
+        if (result instanceof Result_js_1.FileResult)
+            return await sendFile(result, request, reply);
+        if (result instanceof Result_js_1.StatusResult) {
+            reply.code(result.status).headers(result.headers);
+            return respond.success(reply, result.data, request);
+        }
+        respond.success(reply, result, request);
+    };
+    /**
+     * The handler of the requests of an action
+     * @param runtime
+     * @param action
+     */
+    const actionHandler = (runtime, action) => async (request, reply) => {
+        const abortController = new AbortController();
+        //The client left before the response was sent
+        reply.raw.once('close', () => {
+            if (!reply.raw.writableFinished)
+                abortController.abort();
+        });
+        const context = new HTTPContext_js_1.HTTPContext({
+            route: action.address.route,
+            method: action.address.method,
+            request: request.raw,
+            response: reply.raw,
+            data: input(request)
+        });
+        try {
+            const result = await runtime.dispatchTo(action, context, { signal: abortController.signal, params: { ...request.params } });
+            if (!abortController.signal.aborted)
+                await output(result, request, reply);
+        }
+        catch (error) {
+            if (!reply.sent && !reply.raw.headersSent && !abortController.signal.aborted)
+                respond.error(reply, error, request, 'action');
+        }
+        //The client left: nothing is sent, the request is done for fastify (it is not waited for when fastify closes)
+        if (abortController.signal.aborted && !reply.sent) {
+            reply.hijack();
+            reply.raw.destroy();
+        }
+        return reply;
+    };
+    return {
+        channel: 'http',
+        definition: BuiltinChannels_js_1.HTTPChannel,
+        name: options.name,
+        middlewares: options.middlewares,
+        start: async (runtime) => {
+            const fastify = isFastifyInstance(options.fastify) ? options.fastify : (0, fastify_1.default)(options.fastify ?? {});
+            app = fastify;
+            const routes = new Map();
+            for (const action of runtime.actions)
+                routes.set(action.address.route, (routes.get(action.address.route) ?? new Set()).add(String(action.address.method).toUpperCase()));
+            const actionPrefixes = actionPrefixesOf(routes.keys());
+            const isActionPath = (requestPath) => actionPrefixes.some((prefix) => requestPath === prefix || requestPath.startsWith(`${prefix}/`));
+            await options.before?.(fastify, { module: runtime.module, server: fastify.server, routes: routes, actionPrefixes: actionPrefixes, isActionPath: isActionPath });
+            for (const action of runtime.actions) {
+                const method = String(action.address.method).toUpperCase();
+                fastify.route({
+                    method: method,
+                    url: action.address.route,
+                    //A HEAD action of the route replaces the HEAD route fastify adds to a GET route
+                    exposeHeadRoute: method === 'GET' && !routes.get(action.address.route).has('HEAD'),
+                    handler: actionHandler(runtime, action)
+                });
+            }
+            fastify.setNotFoundHandler((request, reply) => {
+                const requestPath = request.url.split('?')[0];
+                if (options.fallback && !isActionPath(requestPath))
+                    return options.fallback(request, reply);
+                return respond.error(reply, new RouteNotFoundException_js_1.RouteNotFoundException('Route {route} not found', { route: requestPath }), request, 'request');
+            });
+            //The responses in progress are waited for when the adapter closes
+            fastify.addHook('onRequest', async (request, reply) => {
+                const responded = new Promise((resolve) => void reply.raw.once('close', resolve));
+                responding.add(responded);
+                //Only resolved
+                void responded.then(() => responding.delete(responded));
+            });
+            //While the adapter stops, the connections are closed once their response is sent
+            fastify.addHook('onResponse', async () => {
+                if (stopping)
+                    setImmediate(() => fastify.server.closeIdleConnections());
+            });
+            fastify.setErrorHandler((error, request, reply) => respond.error(reply, error, request, 'request'));
+            //The adapter starts once the server listens (an occupied port fails the start)
+            //Every interface by default, as the other adapters (fastify listens on localhost only)
+            if (options.host !== undefined) {
+                await fastify.listen({ port: options.port ?? 80, host: options.host });
+            }
+            else {
+                try {
+                    await fastify.listen({ port: options.port ?? 80, host: '::' });
+                }
+                catch (error) {
+                    if (!['EAFNOSUPPORT', 'EADDRNOTAVAIL'].includes(error.code ?? ''))
+                        throw error;
+                    await fastify.listen({ port: options.port ?? 80, host: '0.0.0.0' });
+                }
+            }
+        },
+        stop: () => {
+            //The event streams end; fastify stops accepting connections, closes the idle ones and answers 503 to the new requests
+            stopping = true;
+            streams.forEach((stream) => stream.abort());
+            closed = app?.close();
+        },
+        close: async () => {
+            //The requests in progress ended or were aborted: their responses are given a second to be sent, then the remaining connections are closed
+            //(a connection opened without a request would hold the close of the server)
+            let timer;
+            await Promise.race([Promise.all(responding), new Promise((resolve) => {
+                    timer = setTimeout(resolve, 1000);
+                })]);
+            clearTimeout(timer);
+            app?.server.closeAllConnections();
+            await closed;
+            await options.stop?.();
+        }
+    };
+}

package/dist/cjs/adapter/fastify/Responders.d.ts

@@ -0,0 +1,88 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type HTTPErrorOrigin } from '../../lib/HTTPErrors.js';
+/**
+ * How {@link fastifyHTTPEntrypoint} writes the results and the errors of the actions (its `respond` option). Implement
+ * it to give the responses another shape; {@link FastifyJSONResponder} is the default, {@link fastifyJSONEnvelope}
+ * wraps them in an envelope. The file results and the event streams are not written by the responder.
+ */
+export interface FastifyResponder {
+    /**
+     * Write the result of an action. For a `StatusResult`, its status and headers are already set on the reply and
+     * `data` is its payload.
+     * @param reply The fastify reply to send.
+     * @param data The action's result, `undefined` when it returned nothing.
+     * @param request The fastify request being answered.
+     */
+    success(reply: FastifyReply, data: unknown, request: FastifyRequest): void;
+    /**
+     * Write an error: a failed action (validation, access control, its own exception), an error of fastify (a hook such
+     * as an authenticator, a body too large), or a request matching no route (`RouteNotFoundException`). Not called for
+     * an action once the reply is sent, nor after the client left.
+     * @param reply The fastify reply to send.
+     * @param error The thrown error.
+     * @param request The fastify request being answered.
+     * @param origin Where the error comes from: `'action'` (the dispatch of an action failed) or `'request'` (a hook,
+     * an error of fastify, a route not found); see `HTTPErrorOrigin`.
+     */
+    error(reply: FastifyReply, error: unknown, request: FastifyRequest, origin?: HTTPErrorOrigin): void;
+}
+/**
+ * The default responder of {@link fastifyHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
+ * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
+ * (see `statusOfError`: the first 4xx status in its cause chain, its own status, or 500).
+ */
+export declare const FastifyJSONResponder: FastifyResponder;
+/**
+ * The options of {@link fastifyJSONEnvelope}.
+ */
+export type FastifyJSONEnvelopeOptions = {
+    /**
+     * The HTTP status of every error response, such as 200 for the clients that read the errors from the envelope.
+     * @default the error's own status (see `statusOfError`)
+     */
+    errorStatus?: number;
+    /**
+     * The HTTP status of the errors of the actions only (their dispatch failed: validation, access control, their own
+     * exceptions), over `errorStatus`; the errors of the hooks (an authenticator's 401), of fastify and the routes not
+     * found keep theirs. 200 answers as the applications of lakutata 2.x usually did.
+     * @default `errorStatus`
+     */
+    actionErrorStatus?: number;
+};
+/**
+ * Create a responder for {@link fastifyHTTPEntrypoint} that wraps every response in the envelope
+ * `{errno, errMsg, data}`: a result as `{errno: null, errMsg: null, data}` (`data` is `null` when the action returned
+ * nothing, and its status is not turned into 204), an error as `{errno, errMsg, data: null}` with the error's status,
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option.
+ * @param options The envelope options.
+ * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {fastifyHTTPEntrypoint, fastifyJSONEnvelope} from 'lakutata/adapter/fastify'
+ *
+ * class PingController extends Controller {
+ *     //GET /ping answers {"errno": null, "errMsg": null, "data": "pong"}
+ *     @GET('/ping')
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [PingController],
+ *             //The errors of the actions answered with 200 too (as the applications of lakutata 2.x), the routes not
+ *             //found and the errors of the hooks with their status (404, 401…)
+ *             http: fastifyHTTPEntrypoint({port: 8080, respond: fastifyJSONEnvelope({actionErrorStatus: 200})})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+export declare function fastifyJSONEnvelope(options?: FastifyJSONEnvelopeOptions): FastifyResponder;

package/dist/cjs/adapter/fastify/Responders.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FastifyJSONResponder = void 0;
+exports.fastifyJSONEnvelope = fastifyJSONEnvelope;
+const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
+/**
+ * Send JSON
+ * @param reply
+ * @param data
+ */
+function sendJSON(reply, data) {
+    reply.type('application/json; charset=utf-8').send(JSON.stringify(data));
+}
+/**
+ * The default responder of {@link fastifyHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
+ * status set by a `StatusResult`); an error is sent as `{errno, errMsg}` (see `describeError`) with its HTTP status
+ * (see `statusOfError`: the first 4xx status in its cause chain, its own status, or 500).
+ */
+exports.FastifyJSONResponder = {
+    success: (reply, data) => {
+        if (data === undefined) {
+            reply.code(reply.statusCode === 200 ? 204 : reply.statusCode).send();
+            return;
+        }
+        sendJSON(reply, data);
+    },
+    error: (reply, error) => {
+        reply.code((0, HTTPErrors_js_1.statusOfError)(error));
+        sendJSON(reply, (0, HTTPErrors_js_1.describeError)(error));
+    }
+};
+/**
+ * Create a responder for {@link fastifyHTTPEntrypoint} that wraps every response in the envelope
+ * `{errno, errMsg, data}`: a result as `{errno: null, errMsg: null, data}` (`data` is `null` when the action returned
+ * nothing, and its status is not turned into 204), an error as `{errno, errMsg, data: null}` with the error's status,
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option.
+ * @param options The envelope options.
+ * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+ * import {GET} from 'lakutata/decorator/ctrl'
+ * import {fastifyHTTPEntrypoint, fastifyJSONEnvelope} from 'lakutata/adapter/fastify'
+ *
+ * class PingController extends Controller {
+ *     //GET /ping answers {"errno": null, "errMsg": null, "data": "pong"}
+ *     @GET('/ping')
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ * }
+ *
+ * Application.run({
+ *     id: 'web.app',
+ *     name: 'Web',
+ *     components: {
+ *         entrypoint: buildEntrypoints({
+ *             controllers: [PingController],
+ *             //The errors of the actions answered with 200 too (as the applications of lakutata 2.x), the routes not
+ *             //found and the errors of the hooks with their status (404, 401…)
+ *             http: fastifyHTTPEntrypoint({port: 8080, respond: fastifyJSONEnvelope({actionErrorStatus: 200})})
+ *         })
+ *     }
+ * })
+ * ```
+ */
+function fastifyJSONEnvelope(options = {}) {
+    return {
+        success: (reply, data) => sendJSON(reply, { errno: null, errMsg: null, data: data === undefined ? null : data }),
+        error: (reply, error, _request, origin) => {
+            const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
+            reply.code(status ?? (0, HTTPErrors_js_1.statusOfError)(error));
+            sendJSON(reply, { ...(0, HTTPErrors_js_1.describeError)(error), data: null });
+        }
+    };
+}