defuss-express 0.1.0

package/dist/index.cjs

@@ -0,0 +1,610 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var cluster = require('node:cluster');
+var ultimateExpress = require('ultimate-express');
+var process = require('node:process');
+var os = require('node:os');
+var defussOpenTelemetry = require('defuss-open-telemetry');
+var net = require('node:net');
+
+const express = ultimateExpress;
+
+const withFallback = (candidates) => {
+  const first = candidates[0];
+  if (!first) {
+    throw new Error("defuss-express: no healthy backend candidates are available");
+  }
+  return first;
+};
+const roundRobinLoadBalancer = ({
+  candidates,
+  previousIndex
+}) => {
+  const index = candidates.length === 0 ? 0 : previousIndex % candidates.length;
+  return withFallback(candidates.slice(index).concat(candidates.slice(0, index)));
+};
+const leastConnectionsLoadBalancer = ({
+  candidates
+}) => {
+  const sorted = [...candidates].sort(
+    (left, right) => left.activeProxyConnections - right.activeProxyConnections
+  );
+  return withFallback(sorted);
+};
+const scoreResourceAware = (candidate) => {
+  const stats = candidate.stats;
+  const cpu = stats?.cpuPercent ?? 0;
+  const heapRatio = stats && stats.heapTotalBytes > 0 ? stats.heapUsedBytes / stats.heapTotalBytes : 0;
+  return candidate.activeProxyConnections * 10 + cpu * 2 + heapRatio * 100;
+};
+const resourceAwareLoadBalancer = ({
+  candidates
+}) => {
+  const sorted = [...candidates].sort(
+    (left, right) => scoreResourceAware(left) - scoreResourceAware(right)
+  );
+  return withFallback(sorted);
+};
+const defaultLoadBalancer = roundRobinLoadBalancer;
+const pickBackend = async (context, loadBalancer) => {
+  const chooser = loadBalancer ?? defaultLoadBalancer;
+  return chooser(context);
+};
+
+const defaultLogger = {
+  debug: (...args) => console.debug(...args),
+  info: (...args) => console.info(...args),
+  warn: (...args) => console.warn(...args),
+  error: (...args) => console.error(...args)
+};
+const availableCpus = () => typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+const fallbackConfig = () => ({
+  host: process.env.HOST ?? process.env.LISTEN_HOST ?? "0.0.0.0",
+  port: Number(process.env.PORT ?? process.env.LISTEN_PORT ?? 3e3),
+  workerHost: process.env.WORKER_HOST ?? "127.0.0.1",
+  baseWorkerPort: Number(process.env.BASE_WORKER_PORT ?? 3001),
+  workers: availableCpus(),
+  requestInspectionTimeoutMs: 10,
+  maxHeaderBytes: 16 * 1024,
+  allowHalfOpen: true,
+  workerHeartbeatIntervalMs: 6e4,
+  workerHeartbeatStaleAfterMs: 15e4,
+  gracefulShutdownTimeoutMs: 1e4,
+  respawnWorkers: true,
+  loadBalancer: defaultLoadBalancer,
+  logger: defaultLogger,
+  workerEnv: {},
+  installSignalHandlers: true,
+  telemetry: defussOpenTelemetry.noopTelemetrySink
+});
+let currentConfig = fallbackConfig();
+const resolveServerConfig = (next) => {
+  const defaults = fallbackConfig();
+  const workersInput = next?.workers ?? currentConfig.workers ?? defaults.workers;
+  const workers = workersInput === "auto" ? availableCpus() : Math.max(1, Math.floor(workersInput));
+  const resolvedLogger = {
+    ...defaultLogger,
+    ...currentConfig.logger ?? {},
+    ...next?.logger ?? {}
+  };
+  return {
+    ...defaults,
+    ...currentConfig,
+    ...next,
+    workers,
+    logger: resolvedLogger,
+    workerEnv: {
+      ...currentConfig.workerEnv ?? {},
+      ...next?.workerEnv ?? {}
+    },
+    loadBalancer: next?.loadBalancer ?? currentConfig.loadBalancer ?? defaults.loadBalancer,
+    telemetry: next?.telemetry ?? currentConfig.telemetry ?? defaults.telemetry
+  };
+};
+const setServerConfig = (next) => {
+  currentConfig = resolveServerConfig(next);
+  return currentConfig;
+};
+const getServerConfig = () => currentConfig;
+
+const HEADER_END = Buffer.from("\r\n\r\n");
+const hasCompleteHttpHeaders = (buffer) => buffer.includes(HEADER_END);
+const parseRequestHead = (buffer, remoteAddress, remotePort) => {
+  const rawHead = buffer.toString("latin1");
+  const lines = rawHead.split("\r\n");
+  const requestLine = lines[0] ?? "";
+  const [method, path, httpVersionToken] = requestLine.split(" ");
+  const httpVersion = httpVersionToken?.startsWith("HTTP/") ? httpVersionToken.slice("HTTP/".length) : void 0;
+  const headers = lines.slice(1).reduce((acc, line) => {
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      return acc;
+    }
+    const name = line.slice(0, separatorIndex).trim().toLowerCase();
+    const value = line.slice(separatorIndex + 1).trim();
+    if (name.length > 0) {
+      acc[name] = value;
+    }
+    return acc;
+  }, {});
+  return {
+    method,
+    path,
+    httpVersion,
+    host: headers.host,
+    headers,
+    remoteAddress,
+    remotePort,
+    protocol: method && path ? "http1" : "unknown",
+    rawHead
+  };
+};
+
+const primaryRuntime = {
+  mode: "primary",
+  backends: /* @__PURE__ */ new Map(),
+  workerByIndex: /* @__PURE__ */ new Map(),
+  workerIndexById: /* @__PURE__ */ new Map(),
+  signalHandlersInstalled: false
+};
+const workerRuntime = {
+  mode: "worker",
+  activeConnections: /* @__PURE__ */ new Set(),
+  signalHandlersInstalled: false
+};
+
+const now$1 = () => Date.now();
+const asCandidates = (config) => [...primaryRuntime.backends.values()].filter((backend) => backend.ready).map((backend) => {
+  const stale = backend.lastHeartbeatAt ? now$1() - backend.lastHeartbeatAt > config.workerHeartbeatStaleAfterMs : false;
+  return {
+    id: backend.id,
+    workerIndex: backend.workerIndex,
+    host: backend.host,
+    port: backend.port,
+    pid: backend.pid,
+    ready: backend.ready,
+    healthy: backend.healthy && !stale,
+    lastHeartbeatAt: backend.lastHeartbeatAt,
+    activeProxyConnections: backend.activeProxyConnections,
+    stats: backend.stats
+  };
+}).filter((candidate) => candidate.healthy);
+const waitFor = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const collectPrelude = async (socket, config) => {
+  socket.pause();
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let settled = false;
+    let bufferedSoFar = Buffer.alloc(0);
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      socket.pause();
+      resolve({
+        buffered: bufferedSoFar,
+        request: parseRequestHead(bufferedSoFar, socket.remoteAddress, socket.remotePort)
+      });
+    };
+    const onData = (chunk) => {
+      chunks.push(chunk);
+      total += chunk.length;
+      bufferedSoFar = Buffer.concat(chunks);
+      if (total >= config.maxHeaderBytes || hasCompleteHttpHeaders(bufferedSoFar)) {
+        finish();
+      }
+    };
+    const onClose = () => finish();
+    const onError = () => finish();
+    const timer = setTimeout(finish, config.requestInspectionTimeoutMs);
+    timer.unref();
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.off("data", onData);
+      socket.off("close", onClose);
+      socket.off("end", onClose);
+      socket.off("error", onError);
+    };
+    socket.on("data", onData);
+    socket.once("close", onClose);
+    socket.once("end", onClose);
+    socket.once("error", onError);
+    socket.resume();
+  });
+};
+const updateBackendFromWorkerMessage = (message, config) => {
+  const worker = primaryRuntime.workerByIndex.get(message.workerIndex);
+  const backend = primaryRuntime.backends.get(message.workerIndex) ?? {
+    id: `worker-${message.workerIndex}`,
+    workerIndex: message.workerIndex,
+    host: config.workerHost,
+    port: message.port,
+    pid: message.pid,
+    ready: false,
+    healthy: false,
+    activeProxyConnections: 0
+  };
+  if (message.type === "defuss:worker-stopping") {
+    primaryRuntime.backends.set(message.workerIndex, {
+      ...backend,
+      worker,
+      ready: false,
+      healthy: false,
+      pid: message.pid,
+      lastHeartbeatAt: now$1()
+    });
+    config.telemetry.setGauge("healthy_backends", asCandidates(config).length);
+    return;
+  }
+  primaryRuntime.backends.set(message.workerIndex, {
+    ...backend,
+    worker,
+    pid: message.pid,
+    port: message.port,
+    host: config.workerHost,
+    ready: true,
+    healthy: true,
+    lastHeartbeatAt: now$1(),
+    stats: message.stats
+  });
+  config.telemetry.setGauge("healthy_backends", asCandidates(config).length);
+};
+const forkWorker = (index, config) => {
+  const worker = cluster.fork({
+    ...process.env,
+    ...config.workerEnv,
+    DEFUSS_WORKER_INDEX: String(index)
+  });
+  primaryRuntime.workerByIndex.set(index, worker);
+  primaryRuntime.workerIndexById.set(worker.id, index);
+  worker.on("message", (message) => {
+    if (!message || typeof message !== "object" || !("type" in message)) {
+      return;
+    }
+    updateBackendFromWorkerMessage(message, config);
+  });
+  return worker;
+};
+const installSignalHandlers$1 = (stop, config) => {
+  if (!config.installSignalHandlers || primaryRuntime.signalHandlersInstalled) {
+    return;
+  }
+  primaryRuntime.signalHandlersInstalled = true;
+  process.on("SIGINT", () => {
+    void stop();
+  });
+  process.on("SIGTERM", () => {
+    void stop();
+  });
+};
+const waitForAtLeastOneReadyBackend = async (config) => {
+  const deadline = now$1() + Math.max(5e3, config.gracefulShutdownTimeoutMs);
+  while (now$1() < deadline) {
+    if (asCandidates(config).length > 0) {
+      return;
+    }
+    await waitFor(25);
+  }
+  throw new Error("defuss-express: no worker became ready during startup");
+};
+const connectToBackend = async (client, config, request, buffered, previousIndexRef) => {
+  const candidates = asCandidates(config);
+  if (candidates.length === 0) {
+    client.destroy(new Error("defuss-express: no healthy backends are available"));
+    return;
+  }
+  const backend = await pickBackend(
+    {
+      candidates,
+      request,
+      socket: client,
+      previousIndex: previousIndexRef.value
+    },
+    config.loadBalancer
+  );
+  previousIndexRef.value += 1;
+  const entry = primaryRuntime.backends.get(backend.workerIndex);
+  if (!entry) {
+    client.destroy(new Error("defuss-express: selected backend disappeared"));
+    return;
+  }
+  entry.activeProxyConnections += 1;
+  let released = false;
+  const release = () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    entry.activeProxyConnections = Math.max(0, entry.activeProxyConnections - 1);
+  };
+  const upstream = net.connect({
+    host: entry.host,
+    port: entry.port,
+    allowHalfOpen: config.allowHalfOpen
+  });
+  const cleanup = () => {
+    release();
+    client.destroy();
+    upstream.destroy();
+  };
+  upstream.once("connect", () => {
+    client.setNoDelay(true);
+    upstream.setNoDelay(true);
+    if (buffered.length > 0) {
+      upstream.write(buffered);
+    }
+    client.pipe(upstream);
+    upstream.pipe(client);
+    client.resume();
+  });
+  upstream.once("error", cleanup);
+  upstream.once("close", () => {
+    release();
+    client.destroy();
+  });
+  client.once("error", cleanup);
+  client.once("close", () => {
+    release();
+    upstream.destroy();
+  });
+};
+const createLoadBalancer = (config) => {
+  const previousIndexRef = { value: 0 };
+  const listenServer = net.createServer(
+    {
+      allowHalfOpen: config.allowHalfOpen
+    },
+    async (client) => {
+      config.telemetry.incrementCounter("connections");
+      try {
+        const t0 = performance.now();
+        const { buffered, request } = await collectPrelude(client, config);
+        config.telemetry.recordHistogram("prelude_duration_ms", performance.now() - t0);
+        await connectToBackend(client, config, request, buffered, previousIndexRef);
+      } catch (error) {
+        config.logger.error("[defuss-express] load balancer connection error", error);
+        config.telemetry.incrementCounter("proxy_errors");
+        client.destroy();
+      }
+    }
+  );
+  return new Promise((resolve, reject) => {
+    listenServer.once("error", reject);
+    listenServer.listen(config.port, config.host, () => {
+      listenServer.off("error", reject);
+      config.logger.info(
+        `[defuss-express] primary ${process.pid} listening on tcp://${config.host}:${config.port}`
+      );
+      resolve(listenServer);
+    });
+  });
+};
+const stopPrimaryRuntime = async (config = getServerConfig()) => {
+  if (primaryRuntime.stopPromise) {
+    return primaryRuntime.stopPromise;
+  }
+  if (!primaryRuntime.listenServer) {
+    return;
+  }
+  primaryRuntime.stopPromise = new Promise((resolve) => {
+    const timeout = setTimeout(resolve, config.gracefulShutdownTimeoutMs);
+    timeout.unref();
+    const finish = () => {
+      clearTimeout(timeout);
+      resolve();
+    };
+    try {
+      primaryRuntime.listenServer?.close(finish);
+    } catch {
+      finish();
+    }
+    for (const worker of primaryRuntime.workerByIndex.values()) {
+      worker.kill("SIGTERM");
+    }
+  });
+  return primaryRuntime.stopPromise;
+};
+const startPrimaryRuntime = async (_app, config) => {
+  if (primaryRuntime.startPromise) {
+    return primaryRuntime.startPromise;
+  }
+  primaryRuntime.startPromise = (async () => {
+    for (let index = 0; index < config.workers; index += 1) {
+      forkWorker(index, config);
+    }
+    cluster.on("exit", (worker) => {
+      const index = primaryRuntime.workerIndexById.get(worker.id);
+      if (index === void 0) {
+        return;
+      }
+      primaryRuntime.workerIndexById.delete(worker.id);
+      primaryRuntime.workerByIndex.delete(index);
+      primaryRuntime.backends.delete(index);
+      if (config.respawnWorkers && !primaryRuntime.stopPromise) {
+        config.logger.warn(
+          `[defuss-express] worker ${worker.process.pid ?? "unknown"} exited, respawning index ${index}`
+        );
+        forkWorker(index, config);
+      }
+    });
+    await waitForAtLeastOneReadyBackend(config);
+    primaryRuntime.listenServer = await createLoadBalancer(config);
+    installSignalHandlers$1(() => stopPrimaryRuntime(config), config);
+    return {
+      mode: "primary",
+      pid: process.pid,
+      host: config.host,
+      port: config.port,
+      workers: config.workers
+    };
+  })();
+  return primaryRuntime.startPromise;
+};
+
+const now = () => Date.now();
+const getWorkerIndex = () => Number(process.env.DEFUSS_WORKER_INDEX ?? 0);
+const getWorkerPort = (config) => config.baseWorkerPort + getWorkerIndex();
+const serializeWorkerStats = () => {
+  const memory = process.memoryUsage();
+  return {
+    pid: process.pid,
+    cpuPercent: 0,
+    rssBytes: memory.rss,
+    heapUsedBytes: memory.heapUsed,
+    heapTotalBytes: memory.heapTotal,
+    externalBytes: memory.external,
+    arrayBuffersBytes: memory.arrayBuffers,
+    uptimeMs: process.uptime() * 1e3,
+    activeConnections: workerRuntime.activeConnections.size,
+    sampledAt: now()
+  };
+};
+const createCpuSampler = () => {
+  let previousUsage = process.cpuUsage();
+  let previousTime = process.hrtime.bigint();
+  return () => {
+    const usage = process.cpuUsage(previousUsage);
+    const currentTime = process.hrtime.bigint();
+    const elapsedMicros = Number(currentTime - previousTime) / 1e3;
+    previousUsage = process.cpuUsage();
+    previousTime = currentTime;
+    if (elapsedMicros <= 0) {
+      return 0;
+    }
+    const consumedMicros = usage.user + usage.system;
+    return consumedMicros / elapsedMicros * 100;
+  };
+};
+const createStatsReporter = (config, port) => {
+  const sampleCpu = createCpuSampler();
+  const buildMessage = (type) => {
+    const cpuPercent = sampleCpu();
+    const stats = {
+      ...serializeWorkerStats(),
+      cpuPercent
+    };
+    config.telemetry.setGauge("active_connections", stats.activeConnections);
+    config.telemetry.recordHistogram("cpu_percent", cpuPercent);
+    return {
+      type,
+      workerIndex: getWorkerIndex(),
+      port,
+      pid: process.pid,
+      stats
+    };
+  };
+  return {
+    announceReady: () => process.send?.(buildMessage("defuss:worker-ready")),
+    announceHeartbeat: () => process.send?.(buildMessage("defuss:worker-stats")),
+    announceStopping: () => process.send?.({
+      type: "defuss:worker-stopping",
+      workerIndex: getWorkerIndex(),
+      port,
+      pid: process.pid
+    }),
+    startHeartbeatLoop: () => {
+      workerRuntime.heartbeatTimer = setInterval(() => {
+        process.send?.(buildMessage("defuss:worker-stats"));
+      }, config.workerHeartbeatIntervalMs);
+      workerRuntime.heartbeatTimer.unref();
+    }
+  };
+};
+const registerConnectionTracking = (socket) => {
+  workerRuntime.activeConnections.add(socket);
+  const cleanup = () => {
+    workerRuntime.activeConnections.delete(socket);
+  };
+  socket.once("close", cleanup);
+  socket.once("error", cleanup);
+};
+const stopWorkerRuntime = async (config = getServerConfig()) => {
+  if (workerRuntime.stopPromise) {
+    return workerRuntime.stopPromise;
+  }
+  if (!workerRuntime.appServer) {
+    return;
+  }
+  workerRuntime.stopPromise = new Promise((resolve) => {
+    if (workerRuntime.heartbeatTimer) {
+      clearInterval(workerRuntime.heartbeatTimer);
+      workerRuntime.heartbeatTimer = void 0;
+    }
+    for (const socket of workerRuntime.activeConnections) {
+      socket.destroy();
+    }
+    const timeout = setTimeout(resolve, config.gracefulShutdownTimeoutMs);
+    timeout.unref();
+    try {
+      workerRuntime.appServer?.close(() => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    } catch {
+      clearTimeout(timeout);
+      resolve();
+    }
+  });
+  return workerRuntime.stopPromise;
+};
+const installSignalHandlers = (reporter, config) => {
+  if (!config.installSignalHandlers || workerRuntime.signalHandlersInstalled) {
+    return;
+  }
+  workerRuntime.signalHandlersInstalled = true;
+  const stop = () => {
+    reporter.announceStopping();
+    void stopWorkerRuntime(config).finally(() => process.exit(0));
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+};
+const startWorkerRuntime = async (app, config) => {
+  const port = getWorkerPort(config);
+  const reporter = createStatsReporter(config, port);
+  return new Promise((resolve) => {
+    const server = app.listen(port, config.workerHost, () => {
+      config.logger.info(
+        `[defuss-express] worker ${process.pid} listening on http://${config.workerHost}:${port}`
+      );
+      reporter.announceReady();
+      reporter.announceHeartbeat();
+      resolve({
+        mode: "worker",
+        pid: process.pid,
+        host: config.workerHost,
+        port,
+        workerIndex: getWorkerIndex(),
+        workerPort: port
+      });
+    });
+    workerRuntime.appServer = server;
+    server.on?.("connection", registerConnectionTracking);
+    reporter.startHeartbeatLoop();
+    installSignalHandlers(reporter, config);
+  });
+};
+
+const normalizeConfig = (next) => next ? setServerConfig(next) : resolveServerConfig();
+const startServer = async (app, nextConfig) => {
+  const config = normalizeConfig(nextConfig);
+  return cluster.isPrimary ? startPrimaryRuntime(app, config) : startWorkerRuntime(app, config);
+};
+const stopServer = async () => cluster.isPrimary ? stopPrimaryRuntime(getServerConfig()) : stopWorkerRuntime(getServerConfig());
+
+exports.default = express;
+exports.defaultLoadBalancer = defaultLoadBalancer;
+exports.express = express;
+exports.expressDefault = express;
+exports.getServerConfig = getServerConfig;
+exports.leastConnectionsLoadBalancer = leastConnectionsLoadBalancer;
+exports.resourceAwareLoadBalancer = resourceAwareLoadBalancer;
+exports.roundRobinLoadBalancer = roundRobinLoadBalancer;
+exports.setServerConfig = setServerConfig;
+exports.startServer = startServer;
+exports.stopServer = stopServer;