@webtypen/webframez-core 0.3.109 → 0.3.110

package/README.md

@@ -23,6 +23,24 @@ This README reflects the current API in this repository and focuses on:
 npm i @webtypen/webframez-core
 ```
 
+## Optional server extensions
+
+`WebApplication.boot({ extensions: [...] })` accepts `WebServerExtension` instances.
+Their synchronous `attach({ server, basename, kernel, modulesLoader })` method runs
+after routes are registered and before the HTTP server listens. This allows optional
+transports such as `@webtypen/webframez-sockets` to share the application's port
+without adding their dependencies to Core.
+
+Call `await application.close()` to release extensions in reverse order before
+closing HTTP. Cleanup continues if an extension fails, and the returned promise
+reports the failure. Partially attached extensions are also closed after startup
+failure. Application instances boot once; create a new instance after shutdown.
+`port: 0` selects an ephemeral port, and `onBoot(port)` receives the actual port.
+
+Socket integrations can report `socket.event.start`, `socket.event.end` and
+`socket.event.error` through `WebframezHooks` using the same operation context as
+HTTP and queue execution.
+
 ## Authentication
 
 New integrations can use `SessionAuth` for hashed, revocable device sessions,

package/dist/Hooks/WebframezHooks.d.ts

@@ -1,4 +1,4 @@
-export type WebframezHookOperation = "http.request" | "route.handler" | "console.command" | "queue.job" | "queue.worker" | "app.boot" | "lambda.invoke";
+export type WebframezHookOperation = "http.request" | "route.handler" | "console.command" | "queue.job" | "queue.worker" | "app.boot" | "lambda.invoke" | "socket.event";
 export type WebframezHookPhase = "start" | "end" | "error";
 export type WebframezHookEventName = `${WebframezHookOperation}.${WebframezHookPhase}`;
 export type WebframezHookAttributeValue = string | number | boolean | null;

package/dist/Http/WebServerExtension.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="node" />
+import type { Server } from "http";
+import type { ModulesLoader } from "../Modules/ModulesLoader";
+export type WebServerExtensionContext = {
+    server: Server;
+    basename: string | null;
+    kernel: any;
+    modulesLoader: ModulesLoader;
+};
+/** Optional transports attach before listen; close must release their connections. */
+export interface WebServerExtension {
+    attach(context: WebServerExtensionContext): void;
+    close(): void | Promise<void>;
+}

package/dist/Http/WebServerExtension.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/WebApplication.d.ts

@@ -4,6 +4,10 @@ import { ModulesLoader } from "./Modules/ModulesLoader";
 export declare class WebApplication {
     private server;
     modulesLoader: ModulesLoader | null;
+    private serverExtensions;
+    private closing;
+    /** Close optional transports before waiting for the HTTP server to stop. */
+    close(): Promise<void>;
     /**
      * Init the routes and start the http-server
      */

package/dist/WebApplication.js

@@ -30,6 +30,35 @@ const NotificationService_1 = require("./Notifications/NotificationService");
 class WebApplication {
     constructor() {
         this.modulesLoader = null;
+        this.serverExtensions = [];
+        this.closing = null;
+    }
+    /** Close optional transports before waiting for the HTTP server to stop. */
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closing = (() => __awaiter(this, void 0, void 0, function* () {
+            let failure;
+            for (const extension of this.serverExtensions.splice(0).reverse()) {
+                try {
+                    yield extension.close();
+                }
+                catch (error) {
+                    failure = failure || error;
+                }
+            }
+            if (this.server) {
+                yield new Promise((resolve, reject) => this.server.close((error) => {
+                    if (error && error.code !== "ERR_SERVER_NOT_RUNNING")
+                        reject(error);
+                    else
+                        resolve();
+                }));
+            }
+            if (failure)
+                throw failure;
+        }))();
+        return this.closing;
     }
     /**
      * Init the routes and start the http-server
@@ -46,6 +75,12 @@ class WebApplication {
         });
     }
     bootScoped(options) {
+        if (this.server || this.closing)
+            throw new Error("WebApplication instances can only boot once.");
+        const extensions = (options === null || options === void 0 ? void 0 : options.extensions) || [];
+        if (!Array.isArray(extensions) || extensions.some(extension => !extension || typeof extension.attach !== "function" || typeof extension.close !== "function")) {
+            throw new Error("WebApplication extensions must implement attach(context) and close().");
+        }
         const bootOperationId = WebframezHooks_1.WebframezHooks.createOperationId("app");
         void WebframezHooks_1.WebframezHooks.emit("app.boot.start", {
             operationId: bootOperationId,
@@ -99,7 +134,7 @@ class WebApplication {
         if (options.jobs && options.jobs.length > 0) {
             QueueJobsRegisty_1.QueueJobsRegisty.registerJob(options.jobs);
         }
-        const port = options && options.port ? options.port : 3000;
+        const port = (options === null || options === void 0 ? void 0 : options.port) !== undefined ? options.port : 3000;
         this.server = http_1.default.createServer((req, res) => ErrorHandler_1.ErrorHandler.withContext({ applicationType: "WebApplication", scope: "controller", operationId: WebframezHooks_1.WebframezHooks.createOperationId("http") }, () => __awaiter(this, void 0, void 0, function* () {
             try {
                 const handled = yield HttpKernelHandlerRegistry_1.HttpKernelHandlerRegistry.handle({
@@ -131,6 +166,7 @@ class WebApplication {
             }
         })));
         this.server.on("error", (error) => {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
             void ErrorHandler_1.ErrorHandler.report(error, { applicationType: "WebApplication", scope: "boot", source: "http.server" });
             void WebframezHooks_1.WebframezHooks.emit("app.boot.error", {
                 operationId: bootOperationId,
@@ -149,26 +185,45 @@ class WebApplication {
         // this.server.on("close", () => {
         //     void SigNozTelemetry.shutdown();
         // });
-        this.server.listen(port, () => {
-            void WebframezHooks_1.WebframezHooks.emit("app.boot.end", {
-                operationId: bootOperationId,
-                name: "web",
-                status: "ok",
-                attributes: {
-                    "server.port": port,
-                    "webframez.mode": options && options.mode ? options.mode : "web",
-                },
-            });
-            const runtimeConsole = typeof globalThis !== "undefined" ? globalThis.console : undefined;
-            if (runtimeConsole && typeof runtimeConsole.log === "function") {
-                runtimeConsole.log("Server started and listening on port " +
-                    port +
-                    (Router_1.Router.basename ? " (Basename: " + Router_1.Router.basename + ")" : ""));
-            }
-            if (options && options.onBoot) {
-                options.onBoot(port);
+        try {
+            for (const extension of extensions) {
+                this.serverExtensions.push(extension);
+                extension.attach({ server: this.server, basename: Router_1.Router.basename,
+                    kernel: (options === null || options === void 0 ? void 0 : options.kernel) || null, modulesLoader: this.modulesLoader });
             }
-        });
+        }
+        catch (error) {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
+            throw error;
+        }
+        try {
+            this.server.listen(port, () => {
+                const address = this.server.address();
+                const listeningPort = address && typeof address === "object" ? address.port : port;
+                void WebframezHooks_1.WebframezHooks.emit("app.boot.end", {
+                    operationId: bootOperationId,
+                    name: "web",
+                    status: "ok",
+                    attributes: {
+                        "server.port": listeningPort,
+                        "webframez.mode": options && options.mode ? options.mode : "web",
+                    },
+                });
+                const runtimeConsole = typeof globalThis !== "undefined" ? globalThis.console : undefined;
+                if (runtimeConsole && typeof runtimeConsole.log === "function") {
+                    runtimeConsole.log("Server started and listening on port " +
+                        listeningPort +
+                        (Router_1.Router.basename ? " (Basename: " + Router_1.Router.basename + ")" : ""));
+                }
+                if (options && options.onBoot) {
+                    options.onBoot(listeningPort);
+                }
+            });
+        }
+        catch (error) {
+            void this.close().catch(closeError => ErrorHandler_1.ErrorHandler.report(closeError, { source: "http.server.close" }));
+            throw error;
+        }
         return this.server;
     }
 }

package/dist/index.d.ts

@@ -61,6 +61,7 @@ export * from "./Api/ApiScopeRegistry";
 export * from "./Ai/AiTypes";
 export * from "./Mcp/McpTypes";
 export * from "./Http/HttpKernelHandlerRegistry";
+export * from "./Http/WebServerExtension";
 export * from "./Auth";
 export * from "./Notifications/Notification";
 export * from "./Notifications/BaseNotificationsController";

package/dist/index.js

@@ -78,6 +78,7 @@ __exportStar(require("./Api/ApiScopeRegistry"), exports);
 __exportStar(require("./Ai/AiTypes"), exports);
 __exportStar(require("./Mcp/McpTypes"), exports);
 __exportStar(require("./Http/HttpKernelHandlerRegistry"), exports);
+__exportStar(require("./Http/WebServerExtension"), exports);
 __exportStar(require("./Auth"), exports);
 __exportStar(require("./Notifications/Notification"), exports);
 __exportStar(require("./Notifications/BaseNotificationsController"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.109",
+    "version": "0.3.110",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",