@forklaunch/hyper-express 0.7.11 → 0.8.0

package/lib/index.js

@@ -100,9 +100,149 @@ var trace = (schemaValidator, path, contractDetails, ...handlers2) => {
 var import_common3 = require("@forklaunch/common");
 var import_http13 = require("@forklaunch/core/http");
 var import_hyper_express_fork = require("@forklaunch/hyper-express-fork");
+var import_zod = require("@forklaunch/validator/zod");
 var import_express_api_reference = require("@scalar/express-api-reference");
 var import_crypto = __toESM(require("crypto"));
 
+// src/cluster/hyperExpress.cluster.ts
+var import_node_cluster = __toESM(require("cluster"));
+var os = __toESM(require("os"));
+var uWS = __toESM(require("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 (import_node_cluster.default.isPrimary) {
+    let startWorker2 = function(i) {
+      if (isShuttingDown) return;
+      const worker = import_node_cluster.default.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 ?? import_node_cluster.default.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
 var import_common = require("@forklaunch/common");
 var import_http11 = require("@forklaunch/core/http");
@@ -283,6 +423,9 @@ function swagger(path, document, opts, options2, customCss, customfavIcon, swagg
 // src/hyperExpressApplication.ts
 var Application = class extends import_http13.ForklaunchExpressLikeApplication {
   docsConfiguration;
+  mcpConfiguration;
+  openapiConfiguration;
+  hostingConfiguration;
   /**
    * Creates an instance of the Application class.
    *
@@ -302,7 +445,11 @@ var Application = class extends import_http13.ForklaunchExpressLikeApplication {
   constructor(schemaValidator, openTelemetryCollector, configurationOptions) {
     super(
       schemaValidator,
-      new import_hyper_express_fork.Server(configurationOptions?.server),
+      new import_hyper_express_fork.Server({
+        key_file_name: configurationOptions?.hosting?.ssl?.keyFile,
+        cert_file_name: configurationOptions?.hosting?.ssl?.certFile,
+        ...configurationOptions?.server
+      }),
       [
         contentParse(configurationOptions),
         enrichResponseTransmission
@@ -310,7 +457,10 @@ var Application = class extends import_http13.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") {
@@ -330,66 +480,162 @@ Correlation id: ${(0, import_http13.isForklaunchRequest)(req) ? req.context.corr
           [import_http13.ATTR_HTTP_RESPONSE_STATUS_CODE]: statusCode ?? 500
         });
       });
-      const openApiServerUrls = (0, import_common3.getEnvVar)("DOCS_SERVER_URLS")?.split(",") ?? [
-        `${protocol}://${host}:${port}`
-      ];
-      const openApiServerDescriptions = (0, import_common3.getEnvVar)(
-        "DOCS_SERVER_DESCRIPTIONS"
-      )?.split(",") ?? ["Main Server"];
-      const openApi = (0, import_http13.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"}`,
-          (0, import_express_api_reference.apiReference)({
-            ...this.docsConfiguration,
-            sources: [
-              {
-                content: openApi[import_http13.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 import_zod.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 = (0, import_http13.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[import_http13.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) {
+          (0, import_http13.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 import_crypto.default.createHash("sha256").update((0, import_common3.safeStringify)(openApi)).digest("hex");
-          res.send(hash);
+      }
+      if (this.openapiConfiguration !== false) {
+        const openApiServerUrls = (0, import_common3.getEnvVar)("DOCS_SERVER_URLS")?.split(",") ?? [
+          `${protocol}://${host}:${port}`
+        ];
+        const openApiServerDescriptions = (0, import_common3.getEnvVar)(
+          "DOCS_SERVER_DESCRIPTIONS"
+        )?.split(",") ?? ["Main Server"];
+        const openApi = (0, import_http13.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"}`,
+            (0, import_express_api_reference.apiReference)({
+              ...this.docsConfiguration,
+              sources: [
+                {
+                  content: openApi[import_http13.OPENAPI_DEFAULT_VERSION],
+                  title: "API Reference"
+                },
+                ...Object.entries(openApi).map(([version, spec]) => ({
+                  content: typeof this.openapiConfiguration === "boolean" ? spec : this.openapiConfiguration?.discreteVersions === false ? {
+                    ...openApi[import_http13.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[import_http13.OPENAPI_DEFAULT_VERSION],
+              ...Object.fromEntries(
+                Object.entries(openApi).map(([version, spec]) => [
+                  `v${version}`,
+                  typeof this.openapiConfiguration === "boolean" ? spec : this.openapiConfiguration?.discreteVersions === false ? {
+                    ...openApi[import_http13.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[import_http13.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[import_http13.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 import_crypto.default.createHash("sha256").update((0, import_common3.safeStringify)(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") {
@@ -426,7 +672,8 @@ var Router = class _Router extends import_http14.ForklaunchExpressLikeRouter {
         contentParse(options2),
         enrichResponseTransmission
       ],
-      openTelemetryCollector
+      openTelemetryCollector,
+      options2
     );
     this.basePath = basePath;
     this.configOptions = options2;
@@ -462,7 +709,11 @@ var Router = class _Router extends import_http14.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(