@lakutata/entrypoint 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -111,7 +111,7 @@ import {buildEntrypoints, Controller, type ActionInvocation, type Next} from 'la
 import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
 
 //Runs around the action: before its input validation and its access control
-async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
     const started: number = Date.now()
     try {
         return await next()
@@ -120,7 +120,7 @@ async function Timing(invocation: ActionInvocation, next: Next): Promise<unknown
     }
 }
 
-@UseMiddlewares(Timing)
+@UseMiddlewares(timing)
 class HealthController extends Controller {
     @GET('/health')
     public async health(): Promise<string> {
@@ -132,7 +132,7 @@ Application.run(() => ({
     id: 'health.app',
     name: 'Health',
     components: {
-        entrypoint: buildEntrypoints({controllers: [HealthController], middlewares: [Timing]})
+        entrypoint: buildEntrypoints({controllers: [HealthController], middlewares: [timing]})
     }
 }))
 ```

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.d.ts

@@ -123,7 +123,8 @@ export type ExpressHTTPEntrypointOptions = {
  *
  * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
  * entrypoint stops, the server stops accepting connections, 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.
+ * given up to one second after they settle to send their responses before the remaining connections are closed — the
+ * connections taken over by an upgrade (the WebSockets of the application) too, which would hold the stop forever.
  * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
  * application.
  * @returns The adapter, to give to the `http` option of `buildEntrypoints`.

package/dist/cjs/adapter/express/ExpressHTTPEntrypoint.js

@@ -11,6 +11,7 @@ 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 Connections_js_1 = require("../../lib/Connections.js");
 const Responders_js_1 = require("./Responders.js");
 /**
  * The first segments of the routes
@@ -56,7 +57,8 @@ function eventFrame(data, event, id) {
  *
  * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
  * entrypoint stops, the server stops accepting connections, 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.
+ * given up to one second after they settle to send their responses before the remaining connections are closed — the
+ * connections taken over by an upgrade (the WebSockets of the application) too, which would hold the stop forever.
  * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
  * application.
  * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
@@ -107,6 +109,7 @@ function expressHTTPEntrypoint(options = {}) {
     const input = options.input ?? ((request) => ({ ...request.query, ...(request.body && typeof request.body === 'object' ? request.body : {}) }));
     const streams = new Set();
     let server;
+    let destroyConnections;
     let closed;
     let stopping = false;
     //The responses of the actions not sent yet
@@ -245,6 +248,7 @@ function expressHTTPEntrypoint(options = {}) {
         start: async (runtime) => {
             const app = options.app ?? (0, express_1.default)();
             server = (0, node_http_1.createServer)(options.server ?? {}, app);
+            destroyConnections = (0, Connections_js_1.trackConnections)(server);
             const routes = new Map();
             for (const action of runtime.actions)
                 routes.set(action.address.route, (routes.get(action.address.route) ?? new Set()).add(action.address.method));
@@ -294,6 +298,8 @@ function expressHTTPEntrypoint(options = {}) {
                 })]);
             clearTimeout(timer);
             server?.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closed;
             await options.stop?.();
         }

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

@@ -49,12 +49,23 @@ export type JSONEnvelopeOptions = {
      * @default `errorStatus`
      */
     actionErrorStatus?: number;
+    /**
+     * The extra fields of the envelope, such as the `timestamp`, `nonce` or `requestId` of the envelopes of the
+     * applications of lakutata 2.x: called for each response (a result or an error), its fields added after `errno`,
+     * `errMsg` and `data`, which they never replace. When it throws, a result is answered as an error, and an error
+     * without the extra fields.
+     * @param request The express request being answered.
+     * @returns The fields to add to the envelope.
+     * @default no extra field
+     */
+    extra?: (request: Request) => Record<string, unknown>;
 };
 /**
  * Create a responder for {@link expressHTTPEntrypoint} 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
  * @example
@@ -79,8 +90,15 @@ export type JSONEnvelopeOptions = {
  *         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 express middlewares with their status (404, 401…)
- *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *             //found and the errors of the express middlewares with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: jsonEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })

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

@@ -5,6 +5,7 @@ exports.jsonEnvelope = jsonEnvelope;
 const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
 Object.defineProperty(exports, "describeError", { enumerable: true, get: function () { return HTTPErrors_js_1.describeError; } });
 Object.defineProperty(exports, "statusOfError", { enumerable: true, get: function () { return HTTPErrors_js_1.statusOfError; } });
+const Envelope_js_1 = require("../../lib/Envelope.js");
 /**
  * The default responder of {@link expressHTTPEntrypoint}: 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
@@ -26,7 +27,8 @@ exports.JSONResponder = {
  * Create a responder for {@link expressHTTPEntrypoint} 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
  * @example
@@ -51,8 +53,15 @@ exports.JSONResponder = {
  *         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 express middlewares with their status (404, 401…)
- *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *             //found and the errors of the express middlewares with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: jsonEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })
@@ -60,12 +69,12 @@ exports.JSONResponder = {
  */
 function jsonEnvelope(options = {}) {
     return {
-        success: (response, data) => {
-            response.json({ errno: null, errMsg: null, data: data === undefined ? null : data });
+        success: (response, data, request) => {
+            response.json((0, Envelope_js_1.envelopeOf)({ errno: null, errMsg: null, data: data === undefined ? null : data }, options.extra?.(request)));
         },
-        error: (response, error, _request, origin) => {
+        error: (response, error, request, origin) => {
             const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
-            response.status(status ?? (0, HTTPErrors_js_1.statusOfError)(error)).json({ ...(0, HTTPErrors_js_1.describeError)(error), data: null });
+            response.status(status ?? (0, HTTPErrors_js_1.statusOfError)(error)).json((0, Envelope_js_1.envelopeOf)({ ...(0, HTTPErrors_js_1.describeError)(error), data: null }, (0, Envelope_js_1.errorExtraOf)(options.extra, request)));
         }
     };
 }

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

@@ -109,7 +109,8 @@ export type FastifyHTTPEntrypointOptions = {
  * 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.
+ * remaining connections are closed — the connections taken over by an upgrade (the WebSockets of the application) too,
+ * which would hold the stop forever.
  * @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

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

@@ -11,6 +11,7 @@ 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 Connections_js_1 = require("../../lib/Connections.js");
 const Responders_js_1 = require("./Responders.js");
 /**
  * The content types of the common file extensions
@@ -85,7 +86,8 @@ function isFastifyInstance(value) {
  * 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.
+ * remaining connections are closed — the connections taken over by an upgrade (the WebSockets of the application) too,
+ * which would hold the stop forever.
  * @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
@@ -137,6 +139,7 @@ function fastifyHTTPEntrypoint(options = {}) {
     }));
     const streams = new Set();
     let app;
+    let destroyConnections;
     let closed;
     let stopping = false;
     //The responses not sent yet
@@ -266,6 +269,7 @@ function fastifyHTTPEntrypoint(options = {}) {
         start: async (runtime) => {
             const fastify = isFastifyInstance(options.fastify) ? options.fastify : (0, fastify_1.default)(options.fastify ?? {});
             app = fastify;
+            destroyConnections = (0, Connections_js_1.trackConnections)(fastify.server);
             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()));
@@ -332,6 +336,8 @@ function fastifyHTTPEntrypoint(options = {}) {
                 })]);
             clearTimeout(timer);
             app?.server.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closed;
             await options.stop?.();
         }

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

@@ -48,12 +48,23 @@ export type FastifyJSONEnvelopeOptions = {
      * @default `errorStatus`
      */
     actionErrorStatus?: number;
+    /**
+     * The extra fields of the envelope, such as the `timestamp`, `nonce` or `requestId` of the envelopes of the
+     * applications of lakutata 2.x: called for each response (a result or an error), its fields added after `errno`,
+     * `errMsg` and `data`, which they never replace. When it throws, a result is answered as an error, and an error
+     * without the extra fields.
+     * @param request The fastify request being answered.
+     * @returns The fields to add to the envelope.
+     * @default no extra field
+     */
+    extra?: (request: FastifyRequest) => Record<string, unknown>;
 };
 /**
  * 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
  * @example
@@ -78,8 +89,15 @@ export type FastifyJSONEnvelopeOptions = {
  *         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})})
+ *             //found and the errors of the hooks with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: fastifyJSONEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })

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

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FastifyJSONResponder = void 0;
 exports.fastifyJSONEnvelope = fastifyJSONEnvelope;
 const HTTPErrors_js_1 = require("../../lib/HTTPErrors.js");
+const Envelope_js_1 = require("../../lib/Envelope.js");
 /**
  * Send JSON
  * @param reply
@@ -33,7 +34,8 @@ exports.FastifyJSONResponder = {
  * 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
  * @example
@@ -58,8 +60,15 @@ exports.FastifyJSONResponder = {
  *         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})})
+ *             //found and the errors of the hooks with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: fastifyJSONEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })
@@ -67,11 +76,11 @@ exports.FastifyJSONResponder = {
  */
 function fastifyJSONEnvelope(options = {}) {
     return {
-        success: (reply, data) => sendJSON(reply, { errno: null, errMsg: null, data: data === undefined ? null : data }),
-        error: (reply, error, _request, origin) => {
+        success: (reply, data, request) => sendJSON(reply, (0, Envelope_js_1.envelopeOf)({ errno: null, errMsg: null, data: data === undefined ? null : data }, options.extra?.(request))),
+        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 });
+            sendJSON(reply, (0, Envelope_js_1.envelopeOf)({ ...(0, HTTPErrors_js_1.describeError)(error), data: null }, (0, Envelope_js_1.errorExtraOf)(options.extra, request)));
         }
     };
 }

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.d.ts

@@ -77,7 +77,8 @@ export declare function httpRequestOfContext(context: ServiceContext): IncomingM
  *
  * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
  * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
- * streams are closed and the server shuts down.
+ * streams are closed and the server shuts down, closing its remaining connections (the ones taken over by an upgrade of
+ * the application too).
  * @param options The adapter options; by default it listens on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example

package/dist/cjs/adapter/http/HTTPServiceEntrypoint.js

@@ -8,6 +8,7 @@ const ServiceContext_js_1 = require("../../context/ServiceContext.js");
 const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
 const ServiceResponseCodec_js_1 = require("../../lib/ServiceResponseCodec.js");
 const EntrypointStoppedException_js_1 = require("../../exceptions/EntrypointStoppedException.js");
+const Connections_js_1 = require("../../lib/Connections.js");
 /**
  * Get the HTTP request carrying a service action's request, when {@link httpServiceEntrypoint} serves it (to read its
  * headers, its remote address…).
@@ -92,7 +93,8 @@ async function readBody(request, limit) {
  *
  * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
  * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
- * streams are closed and the server shuts down.
+ * streams are closed and the server shuts down, closing its remaining connections (the ones taken over by an upgrade of
+ * the application too).
  * @param options The adapter options; by default it listens on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example
@@ -135,6 +137,7 @@ function httpServiceEntrypoint(options = {}) {
     const eventsPath = `${base}/events`;
     const limit = options.limit ?? 10 * 1024 * 1024;
     let server;
+    let destroyConnections;
     let stopping = false;
     let keepAlive;
     //The event streams of each client (a client may listen several times)
@@ -222,6 +225,7 @@ function httpServiceEntrypoint(options = {}) {
             //The event streams kept open by the proxies
             keepAlive = setInterval(() => clients.forEach((streams) => streams.forEach((stream) => stream.write(': keep-alive\n\n'))), 15000);
             keepAlive.unref();
+            destroyConnections = (0, Connections_js_1.trackConnections)(server);
             await new Promise((resolve, reject) => {
                 server.once('error', reject).listen(options.port ?? 3000, options.host, () => {
                     server.off('error', reject);
@@ -242,6 +246,8 @@ function httpServiceEntrypoint(options = {}) {
                 return;
             const closing = new Promise((resolve) => void server.close(() => resolve()));
             server.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closing;
         },
         notify: (clientId, event, args) => {

package/dist/cjs/adapter/jsonrpc/JSONRPCServiceEntrypoint.d.ts

@@ -103,7 +103,8 @@ export type JSONRPCServiceEntrypointOptions = JSONRPCMappingOptions & {
  *
  * When an HTTP client disconnects before its response, the action's abort signal fires. When the entrypoint stops,
  * stdio stops reading, the new requests are answered with `STOPPING`, and once the requests in progress are answered
- * the WebSocket connections are closed (code 1001) and the server shuts down.
+ * the WebSocket connections are closed (code 1001; the ones not answering within a second are terminated) and the
+ * server shuts down, closing its remaining connections (the ones taken over by an upgrade of the application too).
  * @param options The adapter options; by default it serves HTTP on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example

package/dist/cjs/adapter/jsonrpc/JSONRPCServiceEntrypoint.js

@@ -39,6 +39,7 @@ const node_http_1 = require("node:http");
 const BuiltinChannels_js_1 = require("../../channel/BuiltinChannels.js");
 const JSONRPCProtocol_js_1 = require("./JSONRPCProtocol.js");
 const ApplicationOf_js_1 = require("../../lib/ApplicationOf.js");
+const Connections_js_1 = require("../../lib/Connections.js");
 /**
  * The headers of the responses of HTTP: the tools of the browsers may call the adapter
  */
@@ -173,7 +174,8 @@ function readMessages(input, framing, limit, receive, ended, oversized) {
  *
  * When an HTTP client disconnects before its response, the action's abort signal fires. When the entrypoint stops,
  * stdio stops reading, the new requests are answered with `STOPPING`, and once the requests in progress are answered
- * the WebSocket connections are closed (code 1001) and the server shuts down.
+ * the WebSocket connections are closed (code 1001; the ones not answering within a second are terminated) and the
+ * server shuts down, closing its remaining connections (the ones taken over by an upgrade of the application too).
  * @param options The adapter options; by default it serves HTTP on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example
@@ -228,6 +230,7 @@ function jsonRPCServiceEntrypoint(options = {}) {
     const path = (options.path ?? '/').replace(/(.)\/+$/, '$1');
     let stopping = false;
     let server;
+    let destroyConnections;
     let webSocketServer;
     let stopReading;
     let heartbeat;
@@ -263,6 +266,7 @@ function jsonRPCServiceEntrypoint(options = {}) {
         return handled;
     };
     const listen = async (target) => {
+        destroyConnections = (0, Connections_js_1.trackConnections)(target);
         await new Promise((resolve, reject) => {
             target.once('error', reject).listen(options.port ?? 3000, options.host, () => {
                 target.off('error', reject);
@@ -375,13 +379,25 @@ function jsonRPCServiceEntrypoint(options = {}) {
             await Promise.allSettled([...inProgress]);
             clients.clear();
             if (webSocketServer) {
-                webSocketServer.clients.forEach((socket) => socket.close(1001, 'The service stops'));
-                await new Promise((resolve) => webSocketServer.close(() => resolve()));
+                //The WebSockets are given a second to answer their close, then the ones not answering are terminated (the
+                //close of the server waits for them all)
+                const sockets = webSocketServer.clients;
+                const closedSockets = new Promise((resolve) => webSocketServer.close(() => resolve()));
+                sockets.forEach((socket) => socket.close(1001, 'The service stops'));
+                let timer;
+                await Promise.race([closedSockets, new Promise((resolve) => {
+                        timer = setTimeout(resolve, 1000);
+                    })]);
+                clearTimeout(timer);
+                sockets.forEach((socket) => socket.terminate());
+                await closedSockets;
             }
             if (!server)
                 return;
             const closing = new Promise((resolve) => void server.close(() => resolve()));
             server.closeAllConnections();
+            //The WebSockets not answering their close, and the connections taken over by an upgrade of the application, hold the close of the server
+            destroyConnections?.();
             await closing;
         },
         notify: (clientId, event, args) => {

package/dist/cjs/lib/Connections.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from 'node:net';
+/**
+ * Track the connections of a server, to destroy the ones its `closeAllConnections()` leaves open: the connections taken
+ * over by an upgrade (a WebSocket: socket.io, ws, the hot reload of a development server) or by a CONNECT request,
+ * which hold the close of the server forever. Unlike a listener of 'upgrade', it does not change how the server answers
+ * the requests (without one, an upgrade request is answered as any request).
+ * @param server The server whose connections are tracked, before it listens.
+ * @returns A function destroying the connections still open.
+ */
+export declare function trackConnections(server: Server): () => void;

package/dist/cjs/lib/Connections.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackConnections = trackConnections;
+/**
+ * Track the connections of a server, to destroy the ones its `closeAllConnections()` leaves open: the connections taken
+ * over by an upgrade (a WebSocket: socket.io, ws, the hot reload of a development server) or by a CONNECT request,
+ * which hold the close of the server forever. Unlike a listener of 'upgrade', it does not change how the server answers
+ * the requests (without one, an upgrade request is answered as any request).
+ * @param server The server whose connections are tracked, before it listens.
+ * @returns A function destroying the connections still open.
+ */
+function trackConnections(server) {
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    });
+    return () => sockets.forEach((socket) => void socket.destroy());
+}

package/dist/cjs/lib/Envelope.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The envelope of a response: its fields, then the extra fields not named as one of them (an extra field never
+ * replaces errno, errMsg or data)
+ * @param fields The fields of the envelope.
+ * @param extra The extra fields, ignored when they are not an object.
+ */
+export declare function envelopeOf(fields: Record<string, unknown>, extra: unknown): Record<string, unknown>;
+/**
+ * The extra fields of an error response: none when the function giving them fails, an error being answered anyway
+ * @param extra The function giving the extra fields.
+ * @param request The request answered.
+ */
+export declare function errorExtraOf<Request>(extra: ((request: Request) => Record<string, unknown>) | undefined, request: Request): unknown;

package/dist/cjs/lib/Envelope.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envelopeOf = envelopeOf;
+exports.errorExtraOf = errorExtraOf;
+/**
+ * The envelope of a response: its fields, then the extra fields not named as one of them (an extra field never
+ * replaces errno, errMsg or data)
+ * @param fields The fields of the envelope.
+ * @param extra The extra fields, ignored when they are not an object.
+ */
+function envelopeOf(fields, extra) {
+    const envelope = { ...fields };
+    if (extra === null || typeof extra !== 'object')
+        return envelope;
+    for (const [key, value] of Object.entries(extra))
+        if (!Object.prototype.hasOwnProperty.call(envelope, key))
+            envelope[key] = value;
+    return envelope;
+}
+/**
+ * The extra fields of an error response: none when the function giving them fails, an error being answered anyway
+ * @param extra The function giving the extra fields.
+ * @param request The request answered.
+ */
+function errorExtraOf(extra, request) {
+    try {
+        return extra?.(request);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/adapter/express/ExpressHTTPEntrypoint.js

@@ -5,6 +5,7 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 import { HTTPChannel } from '../../channel/BuiltinChannels.js';
 import { EventsResult, FileResult, StatusResult } from '../../lib/Result.js';
 import { RouteNotFoundException } from '../../exceptions/RouteNotFoundException.js';
+import { trackConnections } from '../../lib/Connections.js';
 import { JSONResponder } from './Responders.js';
 /**
  * The first segments of the routes
@@ -50,7 +51,8 @@ function eventFrame(data, event, id) {
  *
  * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
  * entrypoint stops, the server stops accepting connections, 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.
+ * given up to one second after they settle to send their responses before the remaining connections are closed — the
+ * connections taken over by an upgrade (the WebSockets of the application) too, which would hold the stop forever.
  * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
  * application.
  * @returns The adapter, to give to the `http` option of `buildEntrypoints`.
@@ -101,6 +103,7 @@ export function expressHTTPEntrypoint(options = {}) {
     const input = options.input ?? ((request) => ({ ...request.query, ...(request.body && typeof request.body === 'object' ? request.body : {}) }));
     const streams = new Set();
     let server;
+    let destroyConnections;
     let closed;
     let stopping = false;
     //The responses of the actions not sent yet
@@ -239,6 +242,7 @@ export function expressHTTPEntrypoint(options = {}) {
         start: async (runtime) => {
             const app = options.app ?? express();
             server = createServer(options.server ?? {}, app);
+            destroyConnections = trackConnections(server);
             const routes = new Map();
             for (const action of runtime.actions)
                 routes.set(action.address.route, (routes.get(action.address.route) ?? new Set()).add(action.address.method));
@@ -288,6 +292,8 @@ export function expressHTTPEntrypoint(options = {}) {
                 })]);
             clearTimeout(timer);
             server?.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closed;
             await options.stop?.();
         }

package/dist/esm/adapter/express/Responders.js

@@ -1,4 +1,5 @@
 import { describeError, statusOfError } from '../../lib/HTTPErrors.js';
+import { envelopeOf, errorExtraOf } from '../../lib/Envelope.js';
 export { describeError, statusOfError };
 /**
  * The default responder of {@link expressHTTPEntrypoint}: a result is sent as JSON, no result as an empty 204 (or the
@@ -21,7 +22,8 @@ export const JSONResponder = {
  * Create a responder for {@link expressHTTPEntrypoint} 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
  * @example
@@ -46,8 +48,15 @@ export const JSONResponder = {
  *         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 express middlewares with their status (404, 401…)
- *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *             //found and the errors of the express middlewares with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: jsonEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })
@@ -55,12 +64,12 @@ export const JSONResponder = {
  */
 export function jsonEnvelope(options = {}) {
     return {
-        success: (response, data) => {
-            response.json({ errno: null, errMsg: null, data: data === undefined ? null : data });
+        success: (response, data, request) => {
+            response.json(envelopeOf({ errno: null, errMsg: null, data: data === undefined ? null : data }, options.extra?.(request)));
         },
-        error: (response, error, _request, origin) => {
+        error: (response, error, request, origin) => {
             const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
-            response.status(status ?? statusOfError(error)).json({ ...describeError(error), data: null });
+            response.status(status ?? statusOfError(error)).json(envelopeOf({ ...describeError(error), data: null }, errorExtraOf(options.extra, request)));
         }
     };
 }

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

@@ -5,6 +5,7 @@ import { HTTPContext } from '../../context/HTTPContext.js';
 import { HTTPChannel } from '../../channel/BuiltinChannels.js';
 import { EventsResult, FileResult, StatusResult } from '../../lib/Result.js';
 import { RouteNotFoundException } from '../../exceptions/RouteNotFoundException.js';
+import { trackConnections } from '../../lib/Connections.js';
 import { FastifyJSONResponder } from './Responders.js';
 /**
  * The content types of the common file extensions
@@ -79,7 +80,8 @@ function isFastifyInstance(value) {
  * 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.
+ * remaining connections are closed — the connections taken over by an upgrade (the WebSockets of the application) too,
+ * which would hold the stop forever.
  * @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
@@ -131,6 +133,7 @@ export function fastifyHTTPEntrypoint(options = {}) {
     }));
     const streams = new Set();
     let app;
+    let destroyConnections;
     let closed;
     let stopping = false;
     //The responses not sent yet
@@ -260,6 +263,7 @@ export function fastifyHTTPEntrypoint(options = {}) {
         start: async (runtime) => {
             const fastify = isFastifyInstance(options.fastify) ? options.fastify : Fastify(options.fastify ?? {});
             app = fastify;
+            destroyConnections = trackConnections(fastify.server);
             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()));
@@ -326,6 +330,8 @@ export function fastifyHTTPEntrypoint(options = {}) {
                 })]);
             clearTimeout(timer);
             app?.server.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closed;
             await options.stop?.();
         }

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

@@ -1,4 +1,5 @@
 import { describeError, statusOfError } from '../../lib/HTTPErrors.js';
+import { envelopeOf, errorExtraOf } from '../../lib/Envelope.js';
 /**
  * Send JSON
  * @param reply
@@ -29,7 +30,8 @@ export const FastifyJSONResponder = {
  * 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
  * @example
@@ -54,8 +56,15 @@ export const FastifyJSONResponder = {
  *         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})})
+ *             //found and the errors of the hooks with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: fastifyJSONEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })
@@ -63,11 +72,11 @@ export const FastifyJSONResponder = {
  */
 export function fastifyJSONEnvelope(options = {}) {
     return {
-        success: (reply, data) => sendJSON(reply, { errno: null, errMsg: null, data: data === undefined ? null : data }),
-        error: (reply, error, _request, origin) => {
+        success: (reply, data, request) => sendJSON(reply, envelopeOf({ errno: null, errMsg: null, data: data === undefined ? null : data }, options.extra?.(request))),
+        error: (reply, error, request, origin) => {
             const status = origin === 'action' ? options.actionErrorStatus ?? options.errorStatus : options.errorStatus;
             reply.code(status ?? statusOfError(error));
-            sendJSON(reply, { ...describeError(error), data: null });
+            sendJSON(reply, envelopeOf({ ...describeError(error), data: null }, errorExtraOf(options.extra, request)));
         }
     };
 }

package/dist/esm/adapter/http/HTTPServiceEntrypoint.js

@@ -4,6 +4,7 @@ import { ServiceContext } from '../../context/ServiceContext.js';
 import { ServiceChannel } from '../../channel/BuiltinChannels.js';
 import { ServiceResponseCodec } from '../../lib/ServiceResponseCodec.js';
 import { EntrypointStoppedException } from '../../exceptions/EntrypointStoppedException.js';
+import { trackConnections } from '../../lib/Connections.js';
 /**
  * Get the HTTP request carrying a service action's request, when {@link httpServiceEntrypoint} serves it (to read its
  * headers, its remote address…).
@@ -88,7 +89,8 @@ async function readBody(request, limit) {
  *
  * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
  * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
- * streams are closed and the server shuts down.
+ * streams are closed and the server shuts down, closing its remaining connections (the ones taken over by an upgrade of
+ * the application too).
  * @param options The adapter options; by default it listens on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example
@@ -131,6 +133,7 @@ export function httpServiceEntrypoint(options = {}) {
     const eventsPath = `${base}/events`;
     const limit = options.limit ?? 10 * 1024 * 1024;
     let server;
+    let destroyConnections;
     let stopping = false;
     let keepAlive;
     //The event streams of each client (a client may listen several times)
@@ -218,6 +221,7 @@ export function httpServiceEntrypoint(options = {}) {
             //The event streams kept open by the proxies
             keepAlive = setInterval(() => clients.forEach((streams) => streams.forEach((stream) => stream.write(': keep-alive\n\n'))), 15000);
             keepAlive.unref();
+            destroyConnections = trackConnections(server);
             await new Promise((resolve, reject) => {
                 server.once('error', reject).listen(options.port ?? 3000, options.host, () => {
                     server.off('error', reject);
@@ -238,6 +242,8 @@ export function httpServiceEntrypoint(options = {}) {
                 return;
             const closing = new Promise((resolve) => void server.close(() => resolve()));
             server.closeAllConnections();
+            //The connections taken over by an upgrade (a WebSocket) are not closed by closeAllConnections() and hold the close of the server
+            destroyConnections?.();
             await closing;
         },
         notify: (clientId, event, args) => {

package/dist/esm/adapter/jsonrpc/JSONRPCServiceEntrypoint.js

@@ -3,6 +3,7 @@ import { createServer } from 'node:http';
 import { ServiceChannel } from '../../channel/BuiltinChannels.js';
 import { JSONRPCErrorCode, JSONRPCProtocol } from './JSONRPCProtocol.js';
 import { applicationOf } from '../../lib/ApplicationOf.js';
+import { trackConnections } from '../../lib/Connections.js';
 /**
  * The headers of the responses of HTTP: the tools of the browsers may call the adapter
  */
@@ -137,7 +138,8 @@ function readMessages(input, framing, limit, receive, ended, oversized) {
  *
  * When an HTTP client disconnects before its response, the action's abort signal fires. When the entrypoint stops,
  * stdio stops reading, the new requests are answered with `STOPPING`, and once the requests in progress are answered
- * the WebSocket connections are closed (code 1001) and the server shuts down.
+ * the WebSocket connections are closed (code 1001; the ones not answering within a second are terminated) and the
+ * server shuts down, closing its remaining connections (the ones taken over by an upgrade of the application too).
  * @param options The adapter options; by default it serves HTTP on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example
@@ -192,6 +194,7 @@ export function jsonRPCServiceEntrypoint(options = {}) {
     const path = (options.path ?? '/').replace(/(.)\/+$/, '$1');
     let stopping = false;
     let server;
+    let destroyConnections;
     let webSocketServer;
     let stopReading;
     let heartbeat;
@@ -227,6 +230,7 @@ export function jsonRPCServiceEntrypoint(options = {}) {
         return handled;
     };
     const listen = async (target) => {
+        destroyConnections = trackConnections(target);
         await new Promise((resolve, reject) => {
             target.once('error', reject).listen(options.port ?? 3000, options.host, () => {
                 target.off('error', reject);
@@ -339,13 +343,25 @@ export function jsonRPCServiceEntrypoint(options = {}) {
             await Promise.allSettled([...inProgress]);
             clients.clear();
             if (webSocketServer) {
-                webSocketServer.clients.forEach((socket) => socket.close(1001, 'The service stops'));
-                await new Promise((resolve) => webSocketServer.close(() => resolve()));
+                //The WebSockets are given a second to answer their close, then the ones not answering are terminated (the
+                //close of the server waits for them all)
+                const sockets = webSocketServer.clients;
+                const closedSockets = new Promise((resolve) => webSocketServer.close(() => resolve()));
+                sockets.forEach((socket) => socket.close(1001, 'The service stops'));
+                let timer;
+                await Promise.race([closedSockets, new Promise((resolve) => {
+                        timer = setTimeout(resolve, 1000);
+                    })]);
+                clearTimeout(timer);
+                sockets.forEach((socket) => socket.terminate());
+                await closedSockets;
             }
             if (!server)
                 return;
             const closing = new Promise((resolve) => void server.close(() => resolve()));
             server.closeAllConnections();
+            //The WebSockets not answering their close, and the connections taken over by an upgrade of the application, hold the close of the server
+            destroyConnections?.();
             await closing;
         },
         notify: (clientId, event, args) => {

package/dist/esm/lib/Connections.js

@@ -0,0 +1,16 @@
+/**
+ * Track the connections of a server, to destroy the ones its `closeAllConnections()` leaves open: the connections taken
+ * over by an upgrade (a WebSocket: socket.io, ws, the hot reload of a development server) or by a CONNECT request,
+ * which hold the close of the server forever. Unlike a listener of 'upgrade', it does not change how the server answers
+ * the requests (without one, an upgrade request is answered as any request).
+ * @param server The server whose connections are tracked, before it listens.
+ * @returns A function destroying the connections still open.
+ */
+export function trackConnections(server) {
+    const sockets = new Set();
+    server.on('connection', (socket) => {
+        sockets.add(socket);
+        socket.once('close', () => sockets.delete(socket));
+    });
+    return () => sockets.forEach((socket) => void socket.destroy());
+}

package/dist/esm/lib/Envelope.js

@@ -0,0 +1,28 @@
+/**
+ * The envelope of a response: its fields, then the extra fields not named as one of them (an extra field never
+ * replaces errno, errMsg or data)
+ * @param fields The fields of the envelope.
+ * @param extra The extra fields, ignored when they are not an object.
+ */
+export function envelopeOf(fields, extra) {
+    const envelope = { ...fields };
+    if (extra === null || typeof extra !== 'object')
+        return envelope;
+    for (const [key, value] of Object.entries(extra))
+        if (!Object.prototype.hasOwnProperty.call(envelope, key))
+            envelope[key] = value;
+    return envelope;
+}
+/**
+ * The extra fields of an error response: none when the function giving them fails, an error being answered anyway
+ * @param extra The function giving the extra fields.
+ * @param request The request answered.
+ */
+export function errorExtraOf(extra, request) {
+    try {
+        return extra?.(request);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/types/adapter/express/ExpressHTTPEntrypoint.d.ts

@@ -123,7 +123,8 @@ export type ExpressHTTPEntrypointOptions = {
  *
  * When the client disconnects before the response, the action's abort signal fires and nothing is written. When the
  * entrypoint stops, the server stops accepting connections, 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.
+ * given up to one second after they settle to send their responses before the remaining connections are closed — the
+ * connections taken over by an upgrade (the WebSockets of the application) too, which would hold the stop forever.
  * @param options The adapter options; by default it listens on port 80 of all the interfaces with a new express
  * application.
  * @returns The adapter, to give to the `http` option of `buildEntrypoints`.

package/dist/types/adapter/express/Responders.d.ts

@@ -49,12 +49,23 @@ export type JSONEnvelopeOptions = {
      * @default `errorStatus`
      */
     actionErrorStatus?: number;
+    /**
+     * The extra fields of the envelope, such as the `timestamp`, `nonce` or `requestId` of the envelopes of the
+     * applications of lakutata 2.x: called for each response (a result or an error), its fields added after `errno`,
+     * `errMsg` and `data`, which they never replace. When it throws, a result is answered as an error, and an error
+     * without the extra fields.
+     * @param request The express request being answered.
+     * @returns The fields to add to the envelope.
+     * @default no extra field
+     */
+    extra?: (request: Request) => Record<string, unknown>;
 };
 /**
  * Create a responder for {@link expressHTTPEntrypoint} 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `expressHTTPEntrypoint`.
  * @example
@@ -79,8 +90,15 @@ export type JSONEnvelopeOptions = {
  *         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 express middlewares with their status (404, 401…)
- *             http: expressHTTPEntrypoint({port: 8080, respond: jsonEnvelope({actionErrorStatus: 200})})
+ *             //found and the errors of the express middlewares with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: expressHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: jsonEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })

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

@@ -109,7 +109,8 @@ export type FastifyHTTPEntrypointOptions = {
  * 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.
+ * remaining connections are closed — the connections taken over by an upgrade (the WebSockets of the application) too,
+ * which would hold the stop forever.
  * @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

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

@@ -48,12 +48,23 @@ export type FastifyJSONEnvelopeOptions = {
      * @default `errorStatus`
      */
     actionErrorStatus?: number;
+    /**
+     * The extra fields of the envelope, such as the `timestamp`, `nonce` or `requestId` of the envelopes of the
+     * applications of lakutata 2.x: called for each response (a result or an error), its fields added after `errno`,
+     * `errMsg` and `data`, which they never replace. When it throws, a result is answered as an error, and an error
+     * without the extra fields.
+     * @param request The fastify request being answered.
+     * @returns The fields to add to the envelope.
+     * @default no extra field
+     */
+    extra?: (request: FastifyRequest) => Record<string, unknown>;
 };
 /**
  * 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.
+ * the `errorStatus` option, or for the errors of the actions the `actionErrorStatus` option; the `extra` option adds
+ * fields to both.
  * @param options The envelope options.
  * @returns The responder, to give to the `respond` option of `fastifyHTTPEntrypoint`.
  * @example
@@ -78,8 +89,15 @@ export type FastifyJSONEnvelopeOptions = {
  *         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})})
+ *             //found and the errors of the hooks with their status (404, 401…); every envelope with
+ *             //its timestamp ({"errno": null, "errMsg": null, "data": "pong", "timestamp": 1767225600000})
+ *             http: fastifyHTTPEntrypoint({
+ *                 port: 8080,
+ *                 respond: fastifyJSONEnvelope({
+ *                     actionErrorStatus: 200,
+ *                     extra: (): Record<string, unknown> => ({timestamp: Date.now()})
+ *                 })
+ *             })
  *         })
  *     }
  * })

package/dist/types/adapter/http/HTTPServiceEntrypoint.d.ts

@@ -77,7 +77,8 @@ export declare function httpRequestOfContext(context: ServiceContext): IncomingM
  *
  * When a client disconnects before its response, the action's abort signal fires. When the entrypoint stops, the new
  * requests are answered with an `EntrypointStoppedException` error; once the requests in progress end, the event
- * streams are closed and the server shuts down.
+ * streams are closed and the server shuts down, closing its remaining connections (the ones taken over by an upgrade of
+ * the application too).
  * @param options The adapter options; by default it listens on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example

package/dist/types/adapter/jsonrpc/JSONRPCServiceEntrypoint.d.ts

@@ -103,7 +103,8 @@ export type JSONRPCServiceEntrypointOptions = JSONRPCMappingOptions & {
  *
  * When an HTTP client disconnects before its response, the action's abort signal fires. When the entrypoint stops,
  * stdio stops reading, the new requests are answered with `STOPPING`, and once the requests in progress are answered
- * the WebSocket connections are closed (code 1001) and the server shuts down.
+ * the WebSocket connections are closed (code 1001; the ones not answering within a second are terminated) and the
+ * server shuts down, closing its remaining connections (the ones taken over by an upgrade of the application too).
  * @param options The adapter options; by default it serves HTTP on port 3000 of all the interfaces, on the path `/`.
  * @returns The adapter, to give to the `service` option of `buildEntrypoints`.
  * @example

package/dist/types/lib/Connections.d.ts

@@ -0,0 +1,10 @@
+import type { Server } from 'node:net';
+/**
+ * Track the connections of a server, to destroy the ones its `closeAllConnections()` leaves open: the connections taken
+ * over by an upgrade (a WebSocket: socket.io, ws, the hot reload of a development server) or by a CONNECT request,
+ * which hold the close of the server forever. Unlike a listener of 'upgrade', it does not change how the server answers
+ * the requests (without one, an upgrade request is answered as any request).
+ * @param server The server whose connections are tracked, before it listens.
+ * @returns A function destroying the connections still open.
+ */
+export declare function trackConnections(server: Server): () => void;

package/dist/types/lib/Envelope.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The envelope of a response: its fields, then the extra fields not named as one of them (an extra field never
+ * replaces errno, errMsg or data)
+ * @param fields The fields of the envelope.
+ * @param extra The extra fields, ignored when they are not an object.
+ */
+export declare function envelopeOf(fields: Record<string, unknown>, extra: unknown): Record<string, unknown>;
+/**
+ * The extra fields of an error response: none when the function giving them fails, an error being answered anyway
+ * @param extra The function giving the extra fields.
+ * @param request The request answered.
+ */
+export declare function errorExtraOf<Request>(extra: ((request: Request) => Record<string, unknown>) | undefined, request: Request): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakutata/entrypoint",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "description": "The entrypoint component of the lakutata framework: controllers and the dispatch of the CLI, HTTP and service actions.",
   "type": "module",
   "main": "./dist/cjs/exports/Entrypoint.js",
@@ -110,8 +110,8 @@
   },
   "peerDependencies": {
     "@inquirer/prompts": "^7.0.0 || ^8.0.0",
-    "@lakutata/core": "3.0.0-beta.1",
-    "@lakutata/utils": "3.0.0-beta.1",
+    "@lakutata/core": "3.0.0-beta.3",
+    "@lakutata/utils": "3.0.0-beta.3",
     "commander": "^12.0.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
     "express": "^4.21.0 || ^5.0.0",
     "fastify": "^5.0.0",