@web-ts-toolkit/express-runtime 0.40.1 → 0.41.0

package/chunk-VPFBKM2K.mjs

@@ -0,0 +1,487 @@
+// src/index.ts
+import http from "http";
+import express from "express";
+import serverless from "serverless-http";
+
+// src/numeric-validation.ts
+var MAX_INTEGER_OPTION_VALUE = Number.MAX_SAFE_INTEGER;
+function validateFiniteInteger(value, options) {
+  const min = options.min ?? Number.MIN_SAFE_INTEGER;
+  const max = options.max ?? MAX_INTEGER_OPTION_VALUE;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`Invalid ${options.name}: ${String(value)}. Must be a finite integer in ${min}..${max}.`);
+  }
+  return value;
+}
+function parsePortValue(value, name) {
+  if (typeof value === "number") {
+    return validateFiniteInteger(value, { name, min: 0, max: 65535 });
+  }
+  if (value.trim() === "") {
+    throw new Error(
+      `Invalid ${name}: ${JSON.stringify(value)}. Must be a port number in 0..65535 or a named pipe path.`
+    );
+  }
+  if (value.trim() !== value) {
+    throw new Error(
+      `Invalid ${name}: ${JSON.stringify(value)}. Numeric ports must not contain surrounding whitespace.`
+    );
+  }
+  if (/^(0|[1-9]\d*)$/.test(value)) {
+    return validateFiniteInteger(Number(value), { name, min: 0, max: 65535 });
+  }
+  if (/^[+-]?(?:\d+|\d*\.\d+)(?:e[+-]?\d+)?$/i.test(value) || /^[+-]?(?:infinity|nan)$/i.test(value)) {
+    throw new Error(`Invalid ${name}: ${value}. Numeric ports must be canonical decimal integers in 0..65535.`);
+  }
+  return value;
+}
+
+// src/index.ts
+var defaultLogger = {
+  log: (...args) => console.log(...args),
+  error: (...args) => console.error(...args),
+  debug: (...args) => console.debug(...args)
+};
+function applySettings(app, options) {
+  if (options.disablePoweredBy !== false) {
+    app.disable("x-powered-by");
+  }
+  app.set("etag", options.etag ?? false);
+  app.set("trust proxy", options.trustProxy ?? false);
+}
+function applyMiddlewareList(app, list) {
+  if (list) {
+    for (const mw of list) {
+      app.use(mw);
+    }
+  }
+}
+function applyRouters(app, options) {
+  const mounts = [];
+  if (options.router) mounts.push(options.router);
+  if (options.routers) mounts.push(...options.routers);
+  for (const mount of mounts) {
+    const path = typeof mount.path === "function" ? mount.path() : mount.path;
+    app.use(path, mount.handler);
+  }
+}
+function createDefaultErrorHandler(logger) {
+  return (error, _req, _res, next) => {
+    logger.error("Unhandled Express error:", error);
+    next(error);
+  };
+}
+function createExpressApp(options = {}) {
+  const app = express();
+  const logger = options.logger ?? defaultLogger;
+  applySettings(app, options);
+  applyMiddlewareList(app, options.preMiddleware);
+  if (options.json !== false) {
+    app.use(express.json(options.json ?? { limit: "1mb" }));
+  }
+  if (options.urlencoded !== false) {
+    app.use(express.urlencoded(options.urlencoded ?? { extended: false, limit: "1mb" }));
+  }
+  applyMiddlewareList(app, options.middleware);
+  applyRouters(app, options);
+  applyMiddlewareList(app, options.postMiddleware);
+  if (options.finalize) {
+    options.finalize(app);
+  }
+  if (options.errorHandler) {
+    app.use(options.errorHandler);
+  } else {
+    app.use(createDefaultErrorHandler(logger));
+  }
+  return app;
+}
+function defaultRequestHook(req, maxBodyBytes = 1024 * 1024, logger = defaultLogger) {
+  if (!req.body || !Buffer.isBuffer(req.body)) {
+    return;
+  }
+  if (req.body.length > maxBodyBytes) {
+    logger.debug?.(" Skipping oversized serverless body for content-type parsing");
+    return;
+  }
+  const bodyStr = req.body.toString("utf8");
+  const contentType = getHeaderValue(req.headers, "content-type");
+  if (isJsonMediaType(contentType)) {
+    if (isReadableRequest(req)) {
+      return;
+    }
+    try {
+      req.body = JSON.parse(bodyStr);
+    } catch (_error) {
+      void _error;
+    }
+    return;
+  }
+  req.body = bodyStr;
+}
+function getHeaderValue(headers, name) {
+  if (!headers) return "";
+  const direct = headers[name];
+  if (direct !== void 0) return Array.isArray(direct) ? direct.join(", ") : direct;
+  const found = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
+  const value = found?.[1];
+  if (value === void 0) return "";
+  return Array.isArray(value) ? value.join(", ") : value;
+}
+function getMediaType(contentType) {
+  return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+function isJsonMediaType(contentType) {
+  const mediaType = getMediaType(contentType);
+  if (mediaType === "application/json") return true;
+  if (!mediaType.startsWith("application/")) return false;
+  const subtype = mediaType.slice("application/".length);
+  return subtype.endsWith("+json") && subtype.length > "+json".length;
+}
+function isReadableRequest(req) {
+  const candidate = req;
+  return req instanceof http.IncomingMessage || typeof candidate.pipe === "function" && typeof candidate.on === "function" && typeof candidate.read === "function";
+}
+function createServerlessHandler(app, options = {}) {
+  const logger = options.logger ?? defaultLogger;
+  const maxBodyBytes = options.maxBodyBytes ?? 1024 * 1024;
+  const requestHook = options.request ?? ((req) => defaultRequestHook(req, maxBodyBytes, logger));
+  const baseOptions = {
+    ...options.serverlessOptions ?? {},
+    request: requestHook
+  };
+  if (options.response) {
+    baseOptions.response = options.response;
+  }
+  const apiHandler = serverless(app, baseOptions);
+  let initialized = null;
+  let initSettled = false;
+  const ensureInit = () => {
+    if (!initialized) {
+      logger.debug?.("Serverless cold start: running init");
+      initSettled = false;
+      initialized = Promise.resolve().then(() => options.init?.()).then(
+        () => {
+          initSettled = true;
+        },
+        (error) => {
+          initSettled = true;
+          throw error;
+        }
+      );
+    }
+    return initialized;
+  };
+  const handler = async (event, context) => {
+    await ensureInit();
+    return apiHandler(event, context);
+  };
+  handler.reset = () => {
+    if (initialized && !initSettled) {
+      logger.debug?.("Serverless init reset ignored while initialization is pending");
+      return;
+    }
+    initialized = null;
+    initSettled = false;
+  };
+  return handler;
+}
+var DEFAULT_SIGNALS = ["SIGINT", "SIGTERM"];
+var DEFAULT_SHUTDOWN_TIMEOUT = 5e3;
+function normalizePort(val, name = "port") {
+  if (val === void 0 || val === "") {
+    const envPort = process.env.PORT;
+    if (envPort === void 0 || envPort === "") {
+      return 8080;
+    }
+    val = envPort;
+  }
+  return parsePortValue(val, name);
+}
+function defaultOnError(error, port, logger) {
+  if (error.syscall !== "listen") {
+    throw error;
+  }
+  const bind = typeof port === "string" ? `Pipe ${port}` : `Port ${port}`;
+  if (error.code === "EACCES") {
+    logger.error(`${bind} requires elevated privileges`);
+    process.exit(1);
+  } else if (error.code === "EADDRINUSE") {
+    logger.error(`${bind} is already in use`);
+    process.exit(1);
+  } else {
+    throw error;
+  }
+}
+function startLocalServer(app, options = {}) {
+  const logger = options.logger ?? defaultLogger;
+  const port = normalizePort(options.port);
+  const host = options.host ?? process.env.HOST ?? "0.0.0.0";
+  const shutdownTimeout = validateFiniteInteger(options.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT, {
+    name: "shutdownTimeout",
+    min: 0,
+    max: MAX_INTEGER_OPTION_VALUE
+  });
+  const server = http.createServer(app);
+  app.set("port", port);
+  let state = "initializing";
+  let shutdownPromise = null;
+  let readySettled = false;
+  let readyResolve;
+  let readyReject;
+  const ready = new Promise((resolve, reject) => {
+    readyResolve = () => {
+      if (!readySettled) {
+        readySettled = true;
+        resolve();
+      }
+    };
+    readyReject = (err) => {
+      if (!readySettled) {
+        readySettled = true;
+        reject(err);
+      }
+    };
+  });
+  ready.catch(() => {
+  });
+  const ownedSignalHandlers = /* @__PURE__ */ new Map();
+  const cleanupSignalHandlers = () => {
+    for (const [sig, handler] of ownedSignalHandlers.entries()) {
+      process.removeListener(sig, handler);
+    }
+    ownedSignalHandlers.clear();
+  };
+  const handleListenError = (error) => {
+    if (state === "stopping" || state === "stopped" || state === "failed") {
+      logger.error("Server error after terminal state:", error);
+      return;
+    }
+    if (state === "initializing") {
+      state = "failed";
+      cleanupSignalHandlers();
+      readyReject(error);
+      if (options.onError) {
+        try {
+          options.onError(error);
+        } catch (e) {
+          logger.error(e);
+        }
+      } else {
+        try {
+          defaultOnError(error, port, logger);
+        } catch (e) {
+          logger.error(e);
+        }
+      }
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
+      return;
+    }
+    if (options.onError) {
+      try {
+        options.onError(error);
+      } catch (e) {
+        logger.error(e);
+      }
+    } else {
+      try {
+        defaultOnError(error, port, logger);
+      } catch (e) {
+        logger.error(e);
+      }
+    }
+  };
+  const onListening = () => {
+    if (state === "stopping" || state === "stopped" || state === "failed") {
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
+      return;
+    }
+    state = "listening";
+    const addr = server.address();
+    const bind = typeof addr === "string" ? `pipe ${addr}` : `port ${addr?.port}`;
+    const actualPort = typeof addr === "object" && addr !== null ? addr.port : port;
+    if (typeof addr === "object" && addr !== null) {
+      logger.log(`Server running at http://${host}:${actualPort}/ (${bind})`);
+    } else if (typeof addr === "string") {
+      logger.log(`Server running at pipe ${addr} (${bind})`);
+    } else {
+      logger.log(`Server running at http://${host}:${port}/ (${bind})`);
+    }
+    try {
+      options.onListening?.();
+    } catch (e) {
+      logger.error("onListening hook failed:", e);
+    }
+    readyResolve();
+  };
+  const handleClose = () => {
+    if (state === "stopping") {
+      return;
+    }
+    if (state === "listening") {
+      state = "stopped";
+      cleanupSignalHandlers();
+      return;
+    }
+    if (state === "initializing" && !readySettled) {
+      state = "stopped";
+      cleanupSignalHandlers();
+      readyReject(new Error("Server closed before listening"));
+      return;
+    }
+    if (state === "initializing") {
+      state = "stopped";
+      cleanupSignalHandlers();
+    }
+  };
+  server.on("error", handleListenError);
+  server.on("listening", onListening);
+  server.on("close", handleClose);
+  const doShutdown = async () => {
+    if (state === "stopping" || state === "stopped") {
+      return;
+    }
+    if (state === "failed") {
+      state = "stopped";
+      cleanupSignalHandlers();
+      return;
+    }
+    state = "stopping";
+    if (!readySettled) {
+      readyReject(new Error("Server shutdown before listening"));
+    }
+    cleanupSignalHandlers();
+    logger.log("Shutting down...");
+    await new Promise((resolve) => {
+      if (!server.listening) {
+        resolve();
+        return;
+      }
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        try {
+          server.closeAllConnections?.();
+        } catch (_err) {
+          void _err;
+        }
+        done();
+      }, shutdownTimeout);
+      timer.unref?.();
+      try {
+        server.close((err) => {
+          if (err) {
+            logger.error("Server close error:", err);
+          }
+          done();
+        });
+      } catch (err) {
+        logger.error("Server close error:", err);
+        done();
+      }
+    });
+    let shutdownError;
+    try {
+      if (options.onShutdown) {
+        await options.onShutdown();
+      }
+    } catch (err) {
+      logger.error("onShutdown hook failed:", err);
+      shutdownError = err;
+    }
+    if (shutdownError) {
+      state = "failed";
+      if (options.exitAfterShutdown) {
+        process.exit(1);
+      }
+      throw shutdownError;
+    }
+    state = "stopped";
+    if (options.exitAfterShutdown) {
+      process.exit(0);
+    }
+  };
+  const shutdown = () => {
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = doShutdown();
+    return shutdownPromise;
+  };
+  if (options.signals !== false) {
+    const list = options.signals === void 0 || options.signals === true ? DEFAULT_SIGNALS : options.signals;
+    for (const sig of list) {
+      const handler = () => {
+        void shutdown().catch(() => {
+        });
+      };
+      ownedSignalHandlers.set(sig, handler);
+      process.once(sig, handler);
+    }
+  }
+  const start = async () => {
+    try {
+      if (options.init) {
+        await options.init();
+      }
+      if (state === "stopping" || state === "stopped" || state === "failed") {
+        return;
+      }
+      if (typeof port === "number") {
+        server.listen(port, host);
+      } else {
+        server.listen(port);
+      }
+    } catch (err) {
+      if (state === "stopping" || state === "stopped") {
+        logger.error("Init failed after shutdown started:", err);
+        return;
+      }
+      state = "failed";
+      cleanupSignalHandlers();
+      const error = err;
+      readyReject(error);
+      if (options.onError) {
+        try {
+          options.onError(error);
+        } catch (e) {
+          logger.error(e);
+        }
+      } else {
+        logger.error("Init failed:", error);
+      }
+      try {
+        server.close();
+      } catch (_err) {
+        void _err;
+      }
+    }
+  };
+  void start();
+  return {
+    server,
+    shutdown,
+    ready
+  };
+}
+
+export {
+  MAX_INTEGER_OPTION_VALUE,
+  validateFiniteInteger,
+  parsePortValue,
+  createExpressApp,
+  defaultRequestHook,
+  createServerlessHandler,
+  normalizePort,
+  startLocalServer
+};