@forklaunch/hyper-express 0.7.11 → 0.8.0

package/lib/index.mjs

@@ -83,16 +83,158 @@ import { getEnvVar, safeStringify as safeStringify2 } from "@forklaunch/common";
 import {
   ATTR_HTTP_RESPONSE_STATUS_CODE,
   ForklaunchExpressLikeApplication,
+  generateMcpServer,
   generateOpenApiSpecs,
   isForklaunchRequest,
+  isPortBound,
   OPENAPI_DEFAULT_VERSION
 } from "@forklaunch/core/http";
 import {
   Server
 } from "@forklaunch/hyper-express-fork";
+import { ZodSchemaValidator } from "@forklaunch/validator/zod";
 import { apiReference } from "@scalar/express-api-reference";
 import crypto from "crypto";
 
+// src/cluster/hyperExpress.cluster.ts
+import cluster from "cluster";
+import * as os from "os";
+import * as uWS from "uWebSockets.js";
+function startHyperExpressCluster(config) {
+  const PORT = config.port;
+  const HOST = config.host;
+  const WORKERS = config.workerCount;
+  const app = config.expressApp;
+  const openTelemetryCollector = config.openTelemetryCollector;
+  if (WORKERS > os.cpus().length) {
+    throw new Error("Worker count cannot be greater than the number of CPUs");
+  }
+  if (cluster.isPrimary) {
+    let startWorker2 = function(i) {
+      if (isShuttingDown) return;
+      const worker = cluster.fork({
+        WORKER_INDEX: i.toString(),
+        PORT: PORT.toString(),
+        HOST
+      });
+      workers.set(worker.id, worker);
+      worker.on("exit", () => {
+        if (isShuttingDown) {
+          return;
+        }
+        workers.delete(worker.id);
+        openTelemetryCollector.warn(
+          `worker ${worker.process.pid} died; restarting in 2s`
+        );
+        setTimeout(() => {
+          if (!isShuttingDown) {
+            startWorker2(i);
+          }
+        }, 2e3);
+      });
+      worker.on(
+        "message",
+        (message) => {
+          if (message && message.type === "worker-ready") {
+            openTelemetryCollector.info(
+              `Worker ${message.index || i} (PID: ${worker.process.pid}) ready`
+            );
+          }
+        }
+      );
+    };
+    var startWorker = startWorker2;
+    const workers = /* @__PURE__ */ new Map();
+    let isShuttingDown = false;
+    openTelemetryCollector.info(
+      `[primary ${process.pid}] starting ${WORKERS} workers on ${HOST}:${PORT}. Using SO_REUSEPORT kernel level routing.`
+    );
+    for (let i = 0; i < WORKERS; i++) {
+      startWorker2(i);
+    }
+    process.on("SIGINT", () => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+      openTelemetryCollector.info(
+        "Received SIGINT, shutting down gracefully..."
+      );
+      workers.forEach((worker) => {
+        worker.send({ type: "shutdown" });
+        worker.kill("SIGTERM");
+      });
+      setTimeout(() => {
+        workers.forEach((worker) => worker.kill("SIGKILL"));
+        process.exit(0);
+      }, 5e3);
+    });
+  } else {
+    const WORKER_PORT = parseInt(process.env.PORT || "0");
+    const IDX = process.env.WORKER_INDEX ?? cluster.worker?.id ?? "0";
+    if (!WORKER_PORT) {
+      openTelemetryCollector.error("Worker port not provided");
+      process.exit(1);
+    }
+    let listenSocket = null;
+    try {
+      app.listen(WORKER_PORT, (socket) => {
+        listenSocket = socket;
+        if (process.send) {
+          process.send({ type: "worker-ready", port: WORKER_PORT, index: IDX });
+        }
+        openTelemetryCollector.info(
+          `[worker ${process.pid}] listening on shared ${HOST}:${WORKER_PORT}`
+        );
+      });
+    } catch (error) {
+      openTelemetryCollector.error("Failed to start worker:", error);
+      process.exit(1);
+    }
+    process.on("message", (msg) => {
+      if (msg?.type === "shutdown") {
+        openTelemetryCollector.info(
+          `[worker ${process.pid}] received shutdown signal from primary`
+        );
+        if (listenSocket) {
+          uWS.us_listen_socket_close(listenSocket);
+        }
+        process.exit(0);
+      }
+    });
+    process.on("SIGINT", () => {
+      openTelemetryCollector.info(
+        `[worker ${process.pid}] shutting down gracefully...`
+      );
+      if (listenSocket) {
+        uWS.us_listen_socket_close(listenSocket);
+      }
+      process.exit(0);
+    });
+    setInterval(() => {
+      const memUsage = process.memoryUsage();
+      const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
+      if (heapUsedMB > 100) {
+        openTelemetryCollector.warn(
+          `High memory usage on worker ${process.pid}: ${heapUsedMB} MB`
+        );
+      }
+    }, 3e4);
+    process.on("uncaughtException", (err) => {
+      openTelemetryCollector.error(
+        `Uncaught exception on worker ${process.pid}:`,
+        err
+      );
+      process.exit(1);
+    });
+    process.on("unhandledRejection", (reason) => {
+      openTelemetryCollector.error(
+        `Unhandled rejection on worker ${process.pid}:`,
+        reason
+      );
+      process.exit(1);
+    });
+  }
+}
+
 // src/middleware/contentParse.middleware.ts
 import { isNever } from "@forklaunch/common";
 import { discriminateBody } from "@forklaunch/core/http";
@@ -275,6 +417,9 @@ function swagger(path, document, opts, options2, customCss, customfavIcon, swagg
 // src/hyperExpressApplication.ts
 var Application = class extends ForklaunchExpressLikeApplication {
   docsConfiguration;
+  mcpConfiguration;
+  openapiConfiguration;
+  hostingConfiguration;
   /**
    * Creates an instance of the Application class.
    *
@@ -294,7 +439,11 @@ var Application = class extends ForklaunchExpressLikeApplication {
   constructor(schemaValidator, openTelemetryCollector, configurationOptions) {
     super(
       schemaValidator,
-      new Server(configurationOptions?.server),
+      new Server({
+        key_file_name: configurationOptions?.hosting?.ssl?.keyFile,
+        cert_file_name: configurationOptions?.hosting?.ssl?.certFile,
+        ...configurationOptions?.server
+      }),
       [
         contentParse(configurationOptions),
         enrichResponseTransmission
@@ -302,7 +451,10 @@ var Application = class extends ForklaunchExpressLikeApplication {
       openTelemetryCollector,
       configurationOptions
     );
+    this.hostingConfiguration = configurationOptions?.hosting;
     this.docsConfiguration = configurationOptions?.docs;
+    this.mcpConfiguration = configurationOptions?.mcp;
+    this.openapiConfiguration = configurationOptions?.openapi;
   }
   async listen(arg0, arg1, arg2) {
     if (typeof arg0 === "number") {
@@ -322,66 +474,162 @@ Correlation id: ${isForklaunchRequest(req) ? req.context.correlationId : "No cor
           [ATTR_HTTP_RESPONSE_STATUS_CODE]: statusCode ?? 500
         });
       });
-      const openApiServerUrls = getEnvVar("DOCS_SERVER_URLS")?.split(",") ?? [
-        `${protocol}://${host}:${port}`
-      ];
-      const openApiServerDescriptions = getEnvVar(
-        "DOCS_SERVER_DESCRIPTIONS"
-      )?.split(",") ?? ["Main Server"];
-      const openApi = generateOpenApiSpecs(
-        this.schemaValidator,
-        openApiServerUrls,
-        openApiServerDescriptions,
-        this
-      );
-      if (this.docsConfiguration == null || this.docsConfiguration.type === "scalar") {
-        this.internal.use(
-          `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}${process.env.DOCS_PATH ?? "/docs"}`,
-          apiReference({
-            ...this.docsConfiguration,
-            sources: [
-              {
-                content: openApi[OPENAPI_DEFAULT_VERSION],
-                title: "API Reference"
-              },
-              ...Object.entries(openApi).map(([version, spec]) => ({
-                content: spec,
-                title: `API Reference - ${version}`
-              })),
-              ...this.docsConfiguration?.sources ?? []
-            ]
-          })
+      if (this.schemaValidator instanceof ZodSchemaValidator && this.mcpConfiguration !== false) {
+        const {
+          port: mcpPort,
+          options: options2,
+          path: mcpPath,
+          version,
+          additionalTools,
+          contentTypeMapping
+        } = this.mcpConfiguration ?? {};
+        const zodSchemaValidator = this.schemaValidator;
+        const finalMcpPort = mcpPort ?? port + 2e3;
+        const mcpServer = generateMcpServer(
+          zodSchemaValidator,
+          protocol,
+          host,
+          finalMcpPort,
+          version ?? "1.0.0",
+          this,
+          this.mcpConfiguration,
+          options2,
+          contentTypeMapping
         );
-      } else if (this.docsConfiguration?.type === "swagger") {
-        const swaggerPath = `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}${process.env.DOCS_PATH ?? "/docs"}`;
-        Object.entries(openApi).forEach(([version, spec]) => {
-          const versionPath = encodeURIComponent(`${swaggerPath}/${version}`);
-          this.internal.use(versionPath, swaggerRedirect(versionPath));
-          this.internal.get(`${versionPath}/*`, swagger(versionPath, spec));
-        });
-      }
-      this.internal.get(
-        `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}/openapi`,
-        (_, res) => {
-          res.type("application/json");
-          res.json({
-            latest: openApi[OPENAPI_DEFAULT_VERSION],
-            ...Object.fromEntries(
-              Object.entries(openApi).map(([version, spec]) => [
-                `v${version}`,
-                spec
-              ])
-            )
+        if (additionalTools) {
+          additionalTools(mcpServer);
+        }
+        if (this.hostingConfiguration?.workerCount && this.hostingConfiguration.workerCount > 1) {
+          isPortBound(finalMcpPort, host).then((isBound) => {
+            if (!isBound) {
+              mcpServer.start({
+                httpStream: {
+                  host,
+                  endpoint: mcpPath ?? "/mcp",
+                  port: finalMcpPort
+                },
+                transportType: "httpStream"
+              });
+            }
+          });
+        } else {
+          mcpServer.start({
+            httpStream: {
+              host,
+              endpoint: mcpPath ?? "/mcp",
+              port: finalMcpPort
+            },
+            transportType: "httpStream"
           });
         }
-      );
-      this.internal.get(
-        `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}/openapi-hash`,
-        async (_, res) => {
-          const hash = await crypto.createHash("sha256").update(safeStringify2(openApi)).digest("hex");
-          res.send(hash);
+      }
+      if (this.openapiConfiguration !== false) {
+        const openApiServerUrls = getEnvVar("DOCS_SERVER_URLS")?.split(",") ?? [
+          `${protocol}://${host}:${port}`
+        ];
+        const openApiServerDescriptions = getEnvVar(
+          "DOCS_SERVER_DESCRIPTIONS"
+        )?.split(",") ?? ["Main Server"];
+        const openApi = generateOpenApiSpecs(
+          this.schemaValidator,
+          openApiServerUrls,
+          openApiServerDescriptions,
+          this,
+          this.openapiConfiguration
+        );
+        if (this.docsConfiguration == null || this.docsConfiguration.type === "scalar") {
+          this.internal.use(
+            `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}${process.env.DOCS_PATH ?? "/docs"}`,
+            apiReference({
+              ...this.docsConfiguration,
+              sources: [
+                {
+                  content: openApi[OPENAPI_DEFAULT_VERSION],
+                  title: "API Reference"
+                },
+                ...Object.entries(openApi).map(([version, spec]) => ({
+                  content: typeof this.openapiConfiguration === "boolean" ? spec : this.openapiConfiguration?.discreteVersions === false ? {
+                    ...openApi[OPENAPI_DEFAULT_VERSION],
+                    ...spec
+                  } : spec,
+                  title: `API Reference - ${version}`
+                })),
+                ...this.docsConfiguration?.sources ?? []
+              ]
+            })
+          );
+        } else if (this.docsConfiguration?.type === "swagger") {
+          const swaggerPath = `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}${process.env.DOCS_PATH ?? "/docs"}`;
+          Object.entries(openApi).forEach(([version, spec]) => {
+            const versionPath = encodeURIComponent(`${swaggerPath}/${version}`);
+            this.internal.use(versionPath, swaggerRedirect(versionPath));
+            this.internal.get(`${versionPath}/*`, swagger(versionPath, spec));
+          });
         }
-      );
+        this.internal.get(
+          `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}/openapi`,
+          (_, res) => {
+            res.type("application/json");
+            res.json({
+              latest: openApi[OPENAPI_DEFAULT_VERSION],
+              ...Object.fromEntries(
+                Object.entries(openApi).map(([version, spec]) => [
+                  `v${version}`,
+                  typeof this.openapiConfiguration === "boolean" ? spec : this.openapiConfiguration?.discreteVersions === false ? {
+                    ...openApi[OPENAPI_DEFAULT_VERSION],
+                    ...spec
+                  } : spec
+                ])
+              )
+            });
+          }
+        );
+        this.internal.get(
+          `/api${process.env.VERSION ? `/${process.env.VERSION}` : ""}/openapi/:id`,
+          async (req, res) => {
+            res.type("application/json");
+            if (req.params.id === "latest") {
+              res.json(openApi[OPENAPI_DEFAULT_VERSION]);
+            } else {
+              if (openApi[req.params.id] == null) {
+                res.status(404).send("Not Found");
+                return;
+              }
+              res.json(
+                typeof this.openapiConfiguration === "boolean" ? openApi[req.params.id] : this.openapiConfiguration?.discreteVersions === false ? {
+                  ...openApi[OPENAPI_DEFAULT_VERSION],
+                  ...openApi[req.params.id]
+                } : openApi[req.params.id]
+              );
+            }
+          }
+        );
+        this.internal.get(
+          `/api/${process.env.VERSION ?? "v1"}/openapi-hash`,
+          async (_, res) => {
+            const hash = await crypto.createHash("sha256").update(safeStringify2(openApi)).digest("hex");
+            res.send(hash);
+          }
+        );
+      }
+      this.internal.get("/health", (_, res) => {
+        res.send("OK");
+      });
+      const { workerCount, ssl, routingStrategy } = this.hostingConfiguration ?? {};
+      if (workerCount != null && workerCount > 1) {
+        this.openTelemetryCollector.warn(
+          "Clustering with hyper-express will default to kernel-level routing."
+        );
+        startHyperExpressCluster({
+          expressApp: this.internal,
+          openTelemetryCollector: this.openTelemetryCollector,
+          port,
+          host,
+          workerCount,
+          routingStrategy,
+          ssl
+        });
+      }
       if (arg1 && typeof arg1 === "string") {
         return this.internal.listen(port, arg1, arg2);
       } else if (arg1 && typeof arg1 === "function") {
@@ -422,7 +670,8 @@ var Router = class _Router extends ForklaunchExpressLikeRouter {
         contentParse(options2),
         enrichResponseTransmission
       ],
-      openTelemetryCollector
+      openTelemetryCollector,
+      options2
     );
     this.basePath = basePath;
     this.configOptions = options2;
@@ -458,7 +707,11 @@ var Router = class _Router extends ForklaunchExpressLikeRouter {
 
 // index.ts
 function forklaunchExpress(schemaValidator, openTelemetryCollector, options2) {
-  return new Application(schemaValidator, openTelemetryCollector, options2);
+  return new Application(
+    schemaValidator,
+    openTelemetryCollector,
+    options2
+  );
 }
 function forklaunchRouter(basePath, schemaValidator, openTelemetryCollector, options2) {
   const router = new Router(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forklaunch/hyper-express",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "description": "Forklaunch framework for hyper-express.",
   "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
   "bugs": {
@@ -25,7 +25,7 @@
     "lib/**"
   ],
   "dependencies": {
-    "@forklaunch/hyper-express-fork": "^6.17.34",
+    "@forklaunch/hyper-express-fork": "^6.17.35",
     "@scalar/express-api-reference": "^0.8.13",
     "cors": "^2.8.5",
     "live-directory": "^3.0.3",
@@ -33,30 +33,30 @@
     "qs": "^6.14.0",
     "swagger-ui-dist": "^5.27.1",
     "swagger-ui-express": "^5.0.1",
-    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.44.0",
-    "@forklaunch/common": "0.4.6",
-    "@forklaunch/validator": "0.8.0",
-    "@forklaunch/core": "0.12.3"
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.52.0",
+    "@forklaunch/common": "0.5.0",
+    "@forklaunch/validator": "0.9.0",
+    "@forklaunch/core": "0.13.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.32.0",
+    "@eslint/js": "^9.33.0",
     "@types/busboy": "^1.5.4",
     "@types/cors": "^2.8.19",
     "@types/jest": "^30.0.0",
     "@types/qs": "^6.14.0",
     "@types/swagger-ui-dist": "^3.30.6",
     "@types/swagger-ui-express": "^4.1.8",
-    "@typescript/native-preview": "7.0.0-dev.20250802.1",
+    "@typescript/native-preview": "7.0.0-dev.20250820.1",
     "jest": "^30.0.5",
     "kill-port-process": "^3.2.1",
     "prettier": "^3.6.2",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.0",
-    "tsx": "^4.20.3",
-    "typedoc": "^0.28.9",
+    "tsx": "^4.20.4",
+    "typedoc": "^0.28.10",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.38.0"
+    "typescript-eslint": "^8.40.0"
   },
   "scripts": {
     "build": "tsgo --noEmit && tsup index.ts --format cjs,esm --no-splitting --dts --tsconfig tsconfig.json --out-dir lib --clean",