overmux 0.0.1 → 0.0.2

package/src/internal/server/start-application-server.ts

@@ -0,0 +1,412 @@
+// Starts one immutable application runtime inside the supervised child process.
+// It owns config loading, transport, and the listening socket.
+
+import { serve, type ServerType as NodeServer } from "@hono/node-server";
+import {
+  loadOvermuxConfig,
+  type RuntimeConfigDefinition,
+} from "@overmux/shared/node";
+import { once } from "node:events";
+import type { AddressInfo } from "node:net";
+import { resolve } from "node:path";
+
+import { createAuthService, type AuthService } from "./auth/auth-service";
+import {
+  createAuthBoundary,
+  validateAuthOrigin,
+  type AuthBoundary,
+} from "./auth/auth-http";
+import { startInstanceControl } from "./auth/instance-control";
+import { createHttpApp } from "./http/create-http-app";
+import { createWebSocketServer } from "./websocket-server";
+import {
+  createBackgroundNotificationService,
+  type BackgroundNotificationService,
+} from "./notifications/background-notification-service";
+import { createFileBackgroundNotificationStore } from "./notifications/background-notification-store";
+import { createNotificationService } from "./notifications/notification-service";
+import { createRuntime, type Runtime } from "./runtime/create-runtime";
+import {
+  createServerLogger,
+  errorDetails,
+  type ServerLogger,
+} from "./server-logger";
+import {
+  resolveServerStartupOptions,
+  type ResolvedServerStartupOptions,
+} from "./server-startup-options";
+import type { OvermuxServerOptions } from "./start-overmux-server";
+
+type ResourceCleanup = () => void | Promise<void>;
+type ServerResources = ReturnType<typeof createResources>;
+type NotificationService = ReturnType<typeof createNotificationService>;
+type ApplicationLogger = ReturnType<typeof createServerLogger>;
+type StartApplicationServerOptions = {
+  onRestartRequested: () => void;
+  options: OvermuxServerOptions;
+};
+
+export type ApplicationServer = {
+  announceUpdateAvailable: () => void;
+  close: () => Promise<void>;
+  host: string;
+  port: number;
+  url: string;
+  watch: boolean;
+};
+
+const cleanupResources = async (cleanups: ResourceCleanup[]) => {
+  const errors: unknown[] = [];
+  for (const cleanup of [...cleanups].reverse()) {
+    try {
+      await cleanup();
+    } catch (cause) {
+      errors.push(cause);
+    }
+  }
+  if (errors.length > 0) {
+    throw new AggregateError(errors, "Failed to clean up server resources");
+  }
+};
+
+const createResources = () => {
+  const cleanups: ResourceCleanup[] = [];
+  let closePromise: Promise<void> | undefined;
+  return {
+    add: (cleanup: ResourceCleanup) => cleanups.push(cleanup),
+    close: () => {
+      const next = closePromise ?? cleanupResources(cleanups);
+      closePromise = next;
+      return next;
+    },
+  };
+};
+
+const closeNodeServer = (
+  server: NodeServer,
+  cancelActiveWork: () => Promise<void>,
+): Promise<void> => {
+  const closed = new Promise<void>((resolveClose, reject) => {
+    server.close((error) => {
+      if (
+        error &&
+        (error as NodeJS.ErrnoException).code !== "ERR_SERVER_NOT_RUNNING"
+      ) {
+        reject(error);
+        return;
+      }
+      resolveClose();
+    });
+  });
+  const cancellation = cancelActiveWork();
+  if ("closeAllConnections" in server) {
+    server.closeAllConnections();
+  }
+  return Promise.all([closed, cancellation]).then(() => undefined);
+};
+
+const getServerAddress = async (server: NodeServer): Promise<AddressInfo> => {
+  if (!server.address()) {
+    await once(server, "listening");
+  }
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Overmux server did not bind a TCP address");
+  }
+  return address;
+};
+
+const registerProcessErrorLogging = (logger: ServerLogger) => {
+  const onUncaughtException = (
+    cause: Error,
+    origin: "uncaughtException" | "unhandledRejection",
+  ) =>
+    logger.log({
+      details: errorDetails(cause),
+      event:
+        origin === "unhandledRejection"
+          ? "unhandled-rejection"
+          : "uncaught-exception",
+      level: "error",
+    });
+  process.on("uncaughtExceptionMonitor", onUncaughtException);
+  return () => {
+    process.off("uncaughtExceptionMonitor", onUncaughtException);
+  };
+};
+
+const loadServerSettings = async ({
+  configPath,
+  options,
+}: {
+  configPath: string;
+  options: OvermuxServerOptions;
+}) => {
+  const { config } = await loadOvermuxConfig({
+    aliases: options.configAliases,
+    configPath,
+  });
+  const startup = resolveServerStartupOptions({
+    config,
+    configPath,
+    overrides: options,
+  });
+  return { config, startup };
+};
+
+const createAuthOrigins = ({
+  configuredOrigins,
+  startup,
+}: {
+  configuredOrigins?: string[];
+  startup: ResolvedServerStartupOptions;
+}) => {
+  const urlHost = startup.host.includes(":")
+    ? `[${startup.host}]`
+    : startup.host;
+  let values = (configuredOrigins ?? [`http://${urlHost}:${startup.port}`]).map(
+    validateAuthOrigin,
+  );
+  return {
+    establish: (localUrl: string) => {
+      values = (configuredOrigins ?? [localUrl]).map(validateAuthOrigin);
+      return values;
+    },
+    get: () => values,
+  };
+};
+
+const createApplicationServices = async ({
+  config,
+  logger,
+  resources,
+  startup,
+}: {
+  config: RuntimeConfigDefinition;
+  logger: ServerLogger;
+  resources: ServerResources;
+  startup: ResolvedServerStartupOptions;
+}) => {
+  // Browser origins are fixed from trusted startup data, never discovered from
+  // requests. Ephemeral listener ports are finalized after binding.
+  const authOrigins = createAuthOrigins({
+    configuredOrigins: config.auth.origins,
+    startup,
+  });
+  const authService = createAuthService({ config: config.auth });
+  const auth = createAuthBoundary({
+    origins: authOrigins.get,
+    service: authService,
+    trustedProxyPeer: config.auth.trustedProxyPeer,
+  });
+  const backgroundNotifications = createBackgroundNotificationService({
+    isSessionActive: authService.isSessionActive,
+    logger,
+    store: createFileBackgroundNotificationStore(),
+  });
+  // Background subscriptions belong to browser sessions, so revocation also
+  // removes delivery credentials owned by those sessions.
+  resources.add(
+    authService.onSessionsRevoked((sessionIds) => {
+      void backgroundNotifications
+        .disableSessions(sessionIds)
+        .catch((cause: unknown) => {
+          logger.log({
+            details: errorDetails(cause),
+            event: "background-notification-session-cleanup-failed",
+            level: "error",
+          });
+        });
+    }),
+  );
+  const notifications = createNotificationService({
+    backgroundNotifications,
+    logger,
+  });
+  const runtime = await createRuntime({
+    config,
+    debug: logger.enabled,
+    notifications,
+  });
+  resources.add(runtime.dispose);
+  return {
+    auth,
+    authOrigins,
+    authService,
+    backgroundNotifications,
+    notifications,
+    runtime,
+  };
+};
+
+const startApplicationTransport = async ({
+  auth,
+  authOrigins,
+  authService,
+  backgroundNotifications,
+  developmentWebTarget,
+  logger,
+  notifications,
+  onRestartRequested,
+  resources,
+  runtime,
+  startup,
+}: {
+  auth: AuthBoundary;
+  authOrigins: ReturnType<typeof createAuthOrigins>;
+  authService: AuthService;
+  backgroundNotifications: BackgroundNotificationService;
+  developmentWebTarget?: string;
+  logger: ServerLogger;
+  notifications: NotificationService;
+  onRestartRequested: () => void;
+  resources: ServerResources;
+  runtime: Runtime;
+  startup: ResolvedServerStartupOptions;
+}) => {
+  let announceRestarting: () => void = () => undefined;
+  const app = createHttpApp({
+    auth,
+    backgroundNotifications,
+    developmentWebTarget,
+    onRestartRequested: () => {
+      announceRestarting();
+      onRestartRequested();
+    },
+    runtime,
+    serverLogger: logger,
+    webAssetsDir: developmentWebTarget
+      ? undefined
+      : startup.productionWebAssetsDir,
+  });
+  const server = serve({
+    fetch: app.fetch,
+    hostname: startup.host,
+    port: startup.port,
+  });
+  resources.add(() => closeNodeServer(server, runtime.dispose));
+  const webSockets = createWebSocketServer({
+    auth,
+    developmentWebTarget,
+    runtime,
+    server,
+    serverLogger: logger,
+  });
+  resources.add(webSockets.close);
+  announceRestarting = webSockets.announceRestarting;
+  notifications.attachLiveDelivery(webSockets.broadcastNotification);
+
+  const address = await getServerAddress(server);
+  const urlHost = startup.host.includes(":")
+    ? `[${startup.host}]`
+    : startup.host;
+  const localUrl = `http://${urlHost}:${address.port}`;
+  const controlApiHost =
+    startup.host === "0.0.0.0"
+      ? "127.0.0.1"
+      : startup.host === "::"
+        ? "[::1]"
+        : urlHost;
+  const origins = authOrigins.establish(localUrl);
+  authService.setOrigins(origins);
+  const instanceControl = await startInstanceControl({
+    auth: authService,
+    apiUrl: `http://${controlApiHost}:${address.port}`,
+    port: address.port,
+    url: origins[0]!,
+  });
+  resources.add(instanceControl.close);
+  return { address, app, localUrl, webSockets };
+};
+
+const closeApplicationServer = async ({
+  app,
+  logger,
+  resources,
+}: {
+  app: ReturnType<typeof createHttpApp>;
+  logger: ServerLogger;
+  resources: ServerResources;
+}) => {
+  logger.log({ event: "server-stop" });
+  app.beginShutdown();
+  await resources.close();
+};
+
+const failApplicationServerStartup = async (
+  cause: unknown,
+  resources: ServerResources,
+): Promise<never> => {
+  try {
+    await resources.close();
+  } catch (cleanupCause) {
+    throw new AggregateError(
+      [cause, cleanupCause],
+      "Server startup and cleanup failed",
+    );
+  }
+  throw cause;
+};
+
+export const startApplicationServer = async ({
+  onRestartRequested,
+  options,
+}: StartApplicationServerOptions): Promise<ApplicationServer> => {
+  const logger = createServerLogger({
+    enabled: options.debug ?? false,
+    logFile: options.logFile ? resolve(options.logFile) : undefined,
+  });
+  const resources = createResources();
+  resources.add(registerProcessErrorLogging(logger));
+
+  try {
+    const configPath = resolve(options.configPath);
+    logger.log({ details: { configPath }, event: "server-start" });
+    const { config, startup } = await loadServerSettings({
+      configPath,
+      options,
+    });
+    logger.setEnabled(Boolean(options.debug || config.debug));
+    if (startup.logFile) {
+      logger.setLogFile(startup.logFile);
+    }
+    const {
+      auth,
+      authOrigins,
+      authService,
+      backgroundNotifications,
+      notifications,
+      runtime,
+    } = await createApplicationServices({
+      config,
+      logger,
+      resources,
+      startup,
+    });
+    const { address, app, localUrl, webSockets } =
+      await startApplicationTransport({
+        auth,
+        authOrigins,
+        authService,
+        backgroundNotifications,
+        developmentWebTarget: options.developmentWebTarget,
+        logger,
+        notifications,
+        onRestartRequested,
+        resources,
+        runtime,
+        startup,
+      });
+
+    return {
+      announceUpdateAvailable: webSockets.announceUpdateAvailable,
+      close: () => closeApplicationServer({ app, logger, resources }),
+      host: startup.host,
+      port: address.port,
+      url: localUrl,
+      watch: startup.watch,
+    };
+  } catch (cause) {
+    return failApplicationServerStartup(cause, resources);
+  }
+};

package/src/internal/server/start-overmux-server.ts

@@ -0,0 +1,26 @@
+import type { ServerConfigDefinition } from "../../public/index";
+import { resolve } from "node:path";
+
+import { startServerCoordinator } from "./coordinator/server-coordinator";
+
+export type OvermuxServerOptions = ServerConfigDefinition & {
+  configAliases?: Record<string, string>;
+  debug?: boolean;
+  developmentWebTarget?: string;
+  configPath: string;
+};
+
+export type OvermuxServer = {
+  announceUpdateAvailable: () => void;
+  close: () => Promise<void>;
+  port: number;
+  url: string;
+};
+
+export const startOvermuxServer = async (
+  options: OvermuxServerOptions,
+): Promise<OvermuxServer> =>
+  startServerCoordinator({
+    ...options,
+    configPath: resolve(options.configPath),
+  });

package/src/internal/server/test-port.ts

@@ -0,0 +1,23 @@
+// Shared utility for tests that need an ephemeral local port.
+import { createServer } from "node:net";
+
+export const findAvailablePort = async (): Promise<number> =>
+  new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close();
+        reject(new Error("Failed to allocate a test port"));
+        return;
+      }
+      server.close((cause) => {
+        if (cause) {
+          reject(cause);
+          return;
+        }
+        resolve(address.port);
+      });
+    });
+  });

package/src/internal/server/vite-websocket-proxy.ts

@@ -0,0 +1,201 @@
+import type { IncomingMessage } from "node:http";
+import type { Socket } from "node:net";
+import type { Duplex } from "node:stream";
+import { proxyUpgrade } from "httpxy";
+
+import { webSocketCloseCode } from "../shared/index";
+import type { AuthBoundary, RequestSession } from "./auth/auth-http";
+import {
+  errorDetails as diagnosticErrorDetails,
+  type ServerLogger,
+} from "./server-logger";
+
+type ProxiedSocket = {
+  client: Duplex;
+  closed: boolean;
+  sessionId: string;
+  timer: NodeJS.Timeout;
+  upstream?: Socket;
+};
+
+const setTrustedForwardingHeaders = (
+  request: IncomingMessage,
+  origin: string,
+) => {
+  Object.keys(request.headers).forEach((name) => {
+    if (
+      name === "authorization" ||
+      name === "cookie" ||
+      name === "forwarded" ||
+      name.startsWith("x-forwarded-")
+    ) {
+      Reflect.deleteProperty(request.headers, name);
+    }
+  });
+  const publicUrl = new URL(origin);
+  request.headers["x-forwarded-for"] = request.socket.remoteAddress;
+  request.headers["x-forwarded-host"] = publicUrl.host;
+  request.headers["x-forwarded-port"] =
+    publicUrl.port || (publicUrl.protocol === "https:" ? "443" : "80");
+  request.headers["x-forwarded-proto"] = publicUrl.protocol.slice(0, -1);
+};
+
+// httpxy preserves an established WebSocket as a raw tunnel, so gateway-owned
+// revocation writes the server close frame before ending both sides.
+const closeFrame = (code: number, reason: string) => {
+  const payload = Buffer.allocUnsafe(2 + Buffer.byteLength(reason));
+  payload.writeUInt16BE(code);
+  payload.write(reason, 2);
+  return Buffer.concat([Buffer.from([0x88, payload.length]), payload]);
+};
+
+const closeSocket = (socket: ProxiedSocket, code: number, reason: string) => {
+  if (socket.closed) {
+    return;
+  }
+  socket.closed = true;
+  clearInterval(socket.timer);
+  if (!socket.client.destroyed) {
+    socket.client.end(closeFrame(code, reason));
+  }
+  socket.upstream?.destroy();
+};
+
+const revalidateSocket = async ({
+  auth,
+  serverLogger,
+  origin,
+  socket,
+  token,
+}: {
+  auth: AuthBoundary;
+  origin: string;
+  serverLogger?: ServerLogger;
+  socket: ProxiedSocket;
+  token: string;
+}) => {
+  try {
+    if (!(await auth.service.authenticateToken(token, origin))) {
+      closeSocket(
+        socket,
+        webSocketCloseCode.authenticationRevoked,
+        "authentication revoked",
+      );
+    }
+  } catch (cause) {
+    serverLogger?.log({
+      details: diagnosticErrorDetails(cause),
+      event: "vite-websocket-session-revalidation-failure",
+      level: "error",
+    });
+    closeSocket(
+      socket,
+      webSocketCloseCode.authenticationUnavailable,
+      "authentication unavailable",
+    );
+  }
+};
+
+export const createViteWebSocketProxy = ({
+  auth,
+  serverLogger,
+  target,
+}: {
+  auth: AuthBoundary;
+  serverLogger?: ServerLogger;
+  target: string;
+}) => {
+  const sockets = new Map<Duplex, ProxiedSocket>();
+
+  const connect = ({
+    correlationId,
+    head,
+    origin,
+    request,
+    session,
+    socket,
+  }: {
+    correlationId?: string;
+    head: Buffer;
+    origin: string;
+    request: IncomingMessage;
+    session: RequestSession;
+    socket: Duplex;
+  }) => {
+    let revalidationPending = false;
+    const proxied: ProxiedSocket = {
+      client: socket,
+      closed: false,
+      sessionId: session.id,
+      timer: setInterval(() => {
+        if (revalidationPending) {
+          return;
+        }
+        revalidationPending = true;
+        void revalidateSocket({
+          auth,
+          origin,
+          serverLogger,
+          socket: proxied,
+          token: session.token,
+        }).finally(() => {
+          revalidationPending = false;
+        });
+      }, 1_000),
+    };
+    sockets.set(socket, proxied);
+    socket.once("close", () => {
+      clearInterval(proxied.timer);
+      sockets.delete(socket);
+    });
+    setTrustedForwardingHeaders(request, origin);
+    void proxyUpgrade(target, request, socket, head, {
+      changeOrigin: true,
+      xfwd: false,
+    }).then(
+      (upstream) => {
+        // Revocation can win while httpxy is opening the private side.
+        if (proxied.closed) {
+          upstream.destroy();
+          return;
+        }
+        proxied.upstream = upstream;
+      },
+      (cause: unknown) => {
+        clearInterval(proxied.timer);
+        sockets.delete(socket);
+        if (proxied.closed) {
+          return;
+        }
+        proxied.closed = true;
+        serverLogger?.log({
+          correlationId,
+          details: diagnosticErrorDetails(cause),
+          event: "vite-websocket-proxy-failure",
+          level: "error",
+        });
+      },
+    );
+  };
+
+  return {
+    close: () => {
+      sockets.forEach((socket) =>
+        closeSocket(socket, 1001, "server shutting down"),
+      );
+      sockets.clear();
+    },
+    connect,
+    revoke: (ids: ReadonlySet<string>) => {
+      sockets.forEach((socket) => {
+        if (ids.has(socket.sessionId)) {
+          closeSocket(
+            socket,
+            webSocketCloseCode.authenticationRevoked,
+            "authentication revoked",
+          );
+        }
+      });
+    },
+  };
+};