overmux 0.0.1 → 0.0.2

package/src/internal/server/coordinator/server-coordinator.ts

@@ -0,0 +1,262 @@
+// Supervises one disposable application child and the parent-owned update watcher.
+// The coordinator retains only lifecycle state and the stable startup address.
+
+import { fork, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { errorMessage } from "../server-logger";
+import type {
+  OvermuxServer,
+  OvermuxServerOptions,
+} from "../start-overmux-server";
+import {
+  parseChildMessage,
+  type ChildServerOptions,
+  type ParentToChildMessage,
+} from "./ipc-protocol";
+import { startUpdateWatcher, type UpdateWatcher } from "./update-watcher";
+
+type ChildInstance = {
+  process: ChildProcess;
+  host: string;
+  port: number;
+  url: string;
+  watch: boolean;
+};
+
+const send = (
+  child: ChildProcess,
+  message: ParentToChildMessage,
+  onError?: (cause: Error) => void,
+) => {
+  if (!child.connected) {
+    onError?.(new Error("Server child IPC channel is closed"));
+    return;
+  }
+  try {
+    child.send(message, (cause) => {
+      if (cause) {
+        onError?.(cause);
+      }
+    });
+  } catch (cause) {
+    onError?.(cause instanceof Error ? cause : new Error(String(cause)));
+  }
+};
+
+const stopChild = (child: ChildProcess): Promise<void> =>
+  new Promise((resolve) => {
+    let timeout: NodeJS.Timeout | undefined;
+    const finish = () => {
+      child.off("exit", finish);
+      clearTimeout(timeout);
+      resolve();
+    };
+    child.once("exit", finish);
+    if (child.exitCode !== null || child.signalCode !== null) {
+      finish();
+      return;
+    }
+    timeout = setTimeout(() => {
+      if (!child.kill("SIGKILL")) {
+        finish();
+      }
+    }, 5_000);
+    send(child, { type: "stop" });
+  });
+
+const serverChildPath = () =>
+  fileURLToPath(import.meta.resolve("#server-child"));
+
+const startChild = (
+  options: ChildServerOptions,
+  onRestartRequested: () => void,
+): Promise<ChildInstance> =>
+  new Promise((resolve, reject) => {
+    const child = fork(serverChildPath(), [], {
+      serialization: "json",
+      stdio: ["inherit", "inherit", "inherit", "ipc"],
+    });
+    let settled = false;
+    const fail = (cause: unknown) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill();
+      }
+      reject(cause instanceof Error ? cause : new Error(String(cause)));
+    };
+    child.on("error", fail);
+    child.on("exit", (code, signal) => {
+      fail(
+        new Error(
+          `Server child exited before readiness (${signal ?? code ?? "unknown"})`,
+        ),
+      );
+    });
+    child.on("message", (raw) => {
+      let message;
+      try {
+        message = parseChildMessage(raw);
+      } catch (cause) {
+        fail(cause);
+        return;
+      }
+      if (message.type === "restart-requested") {
+        if (settled) {
+          onRestartRequested();
+        }
+        return;
+      }
+      if (message.type === "startup-failed") {
+        fail(new Error(message.message));
+        return;
+      }
+      if (!settled) {
+        settled = true;
+        resolve({
+          host: message.host,
+          port: message.port,
+          process: child,
+          url: message.url,
+          watch: message.watch,
+        });
+      }
+    });
+    send(child, { options, type: "start" }, fail);
+  });
+
+export const startServerCoordinator = async (
+  initialOptions: OvermuxServerOptions,
+): Promise<OvermuxServer> => {
+  let child: ChildInstance | undefined;
+  let closed = false;
+  let closePromise: Promise<void> | undefined;
+  let restartPromise: Promise<void> | undefined;
+  let updateDuringRestart = false;
+  let startupAddress: { host: string; port: number } | undefined;
+  let watcher: UpdateWatcher | undefined;
+
+  const adoptChild = (next: ChildInstance) => {
+    child = next;
+    next.process.once("exit", () => {
+      if (child?.process === next.process) {
+        child = undefined;
+      }
+    });
+  };
+
+  const restart = () => {
+    if (closed || restartPromise) {
+      return restartPromise ?? Promise.resolve();
+    }
+    restartPromise = (async () => {
+      const previous = child;
+      child = undefined;
+      if (previous) {
+        await stopChild(previous.process);
+      }
+      if (closed || !startupAddress) {
+        return;
+      }
+      try {
+        const replacement = await startChild(
+          {
+            ...initialOptions,
+            host: startupAddress.host,
+            port: startupAddress.port,
+          },
+          () => void restart(),
+        );
+        if (closed) {
+          await stopChild(replacement.process);
+          return;
+        }
+        adoptChild(replacement);
+        if (updateDuringRestart) {
+          updateDuringRestart = false;
+          send(replacement.process, { type: "update-available" });
+        }
+      } catch (cause) {
+        process.stderr.write(
+          `[overmux] replacement child failed: ${errorMessage(cause)}\n`,
+        );
+      }
+    })().finally(() => {
+      const shouldRetry = updateDuringRestart && !child && !closed;
+      updateDuringRestart = false;
+      restartPromise = undefined;
+      if (shouldRetry) {
+        void restart();
+      }
+    });
+    return restartPromise;
+  };
+
+  const onUpdate = () => {
+    if (closed) {
+      return;
+    }
+    if (restartPromise) {
+      updateDuringRestart = true;
+      return;
+    }
+    if (child) {
+      send(child.process, { type: "update-available" });
+      return;
+    }
+    void restart();
+  };
+
+  const initial = await startChild(initialOptions, () => void restart());
+  startupAddress = { host: initial.host, port: initial.port };
+  adoptChild(initial);
+  try {
+    if (initial.watch) {
+      watcher = startUpdateWatcher({
+        configPath: initialOptions.configPath,
+        onUpdate,
+      });
+    }
+  } catch (cause) {
+    await stopChild(initial.process);
+    throw cause;
+  }
+
+  const close = () => {
+    if (closePromise) {
+      return closePromise;
+    }
+    closed = true;
+    closePromise = (async () => {
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+      watcher?.close();
+      const active = child;
+      child = undefined;
+      if (active) {
+        await stopChild(active.process);
+      }
+      await restartPromise;
+    })();
+    return closePromise;
+  };
+  const onSignal = () => {
+    void close().catch((cause: unknown) => {
+      process.stderr.write(
+        `[overmux] coordinator shutdown failed: ${errorMessage(cause)}\n`,
+      );
+    });
+  };
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+
+  return {
+    announceUpdateAvailable: onUpdate,
+    close,
+    port: initial.port,
+    url: initial.url,
+  };
+};

package/src/internal/server/coordinator/update-watcher.ts

@@ -0,0 +1,54 @@
+// Owns the coordinator's broad recursive watch of the config directory.
+// Filtering and debounce keep update signaling independent of import analysis.
+
+import { watch } from "node:fs";
+import { dirname } from "node:path";
+
+export type UpdateWatcher = {
+  close: () => void;
+};
+
+export const isRelevantUpdatePath = (path: string): boolean => {
+  const segments = path.split(/[\\/]/);
+  if (segments.some((segment) => segment.toLowerCase() === "node_modules")) {
+    return false;
+  }
+  return /\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts|json|css)$/i.test(path);
+};
+
+export const startUpdateWatcher = ({
+  configPath,
+  onUpdate,
+}: {
+  configPath: string;
+  onUpdate: () => void;
+}): UpdateWatcher => {
+  let closed = false;
+  let timeout: NodeJS.Timeout | undefined;
+  const watcher = watch(
+    dirname(configPath),
+    { recursive: true },
+    (_event, fileName) => {
+      if (closed || !fileName || !isRelevantUpdatePath(fileName.toString())) {
+        return;
+      }
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      timeout = setTimeout(onUpdate, 100);
+    },
+  );
+
+  return {
+    close: () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      watcher.close();
+    },
+  };
+};

package/src/internal/server/http/authenticated-http-app-test-helper.ts

@@ -0,0 +1,45 @@
+import type { AuthService } from "../auth/auth-service";
+import type { RequestAuthentication } from "../auth/auth-http";
+import { createHttpApp, type HttpAppOptions } from "./create-http-app";
+
+const origin = "http://localhost";
+
+const auth: AuthService = {
+  authenticateToken: async () => undefined,
+  consumeLoginGrant: async () => ({ status: "invalid" }),
+  createLoginGrant: async () => {
+    throw new Error("Not implemented in authenticated HTTP tests");
+  },
+  isSessionActive: async () => true,
+  issueLocalBearer: async () => {
+    throw new Error("Not implemented in authenticated HTTP tests");
+  },
+  listSessions: async () => [],
+  onSessionsRevoked: () => () => undefined,
+  revokeAllSessions: async () => 0,
+  revokeSession: async () => false,
+  setOrigins: () => undefined,
+};
+
+const authentication: RequestAuthentication = {
+  authenticate: async () => ({
+    credential: "bearer",
+    id: "test-session",
+    kind: "local",
+    token: "test-token",
+  }),
+  clearCookieHeader: () => "",
+  cookieHeader: () => "",
+};
+
+type TestHttpAppOptions = Omit<HttpAppOptions, "auth">;
+
+export const createAuthenticatedTestHttpApp = (options: TestHttpAppOptions) =>
+  createHttpApp({
+    ...options,
+    auth: {
+      requests: authentication,
+      resolveOrigin: () => origin,
+      service: auth,
+    },
+  });

package/src/internal/server/http/background-notification-handlers.ts

@@ -0,0 +1,83 @@
+// Exposes browser controls for enabling and disabling background notifications.
+// Subscription details pass directly to the background-delivery boundary.
+import {
+  backgroundNotificationDisableRequestSchema,
+  backgroundNotificationSubscriptionSchema,
+} from "../../shared/index";
+import type { Handler } from "hono";
+import type { z } from "zod";
+
+import type { AuthEnvironment } from "../auth/auth-http";
+import type { BackgroundNotificationService } from "../notifications/background-notification-service";
+
+const requestLimit = 16_384;
+
+const parseJson = async <TSchema extends z.ZodType>(
+  request: Request,
+  schema: TSchema,
+): Promise<z.output<TSchema> | undefined> => {
+  if (
+    request.headers.get("Content-Type")?.split(";", 1)[0]?.toLowerCase() !==
+    "application/json"
+  ) {
+    return undefined;
+  }
+  const contentLength = Number(request.headers.get("Content-Length") ?? 0);
+  if (contentLength > requestLimit) {
+    return undefined;
+  }
+  try {
+    const bytes = await request.arrayBuffer();
+    if (bytes.byteLength > requestLimit) {
+      return undefined;
+    }
+    const parsed = schema.safeParse(
+      JSON.parse(new TextDecoder().decode(bytes)),
+    );
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export const createBackgroundNotificationHandlers = ({
+  backgroundNotifications,
+}: {
+  backgroundNotifications: BackgroundNotificationService;
+}): {
+  disable: Handler<AuthEnvironment>;
+  enable: Handler<AuthEnvironment>;
+  publicKey: Handler<AuthEnvironment>;
+} => ({
+  publicKey: async (context) => {
+    context.header("Cache-Control", "no-store");
+    return context.json({
+      publicKey: await backgroundNotifications.publicKey(),
+    });
+  },
+  enable: async (context) => {
+    const subscription = await parseJson(
+      context.req.raw,
+      backgroundNotificationSubscriptionSchema,
+    );
+    if (!subscription) {
+      return context.json({ error: "Invalid background subscription" }, 400);
+    }
+    await backgroundNotifications.enable(
+      context.get("session").id,
+      subscription,
+    );
+    return context.json({ ok: true });
+  },
+  disable: async (context) => {
+    const input = await parseJson(
+      context.req.raw,
+      backgroundNotificationDisableRequestSchema,
+    );
+    if (!input) {
+      return context.json({ error: "Invalid background subscription" }, 400);
+    }
+    await backgroundNotifications.disable(input.endpoint);
+    return context.json({ ok: true });
+  },
+});

package/src/internal/server/http/control-handlers.ts

@@ -0,0 +1,44 @@
+// Provides server health and acknowledged restart control endpoints.
+// Shutdown state is shared with the HTTP app composition root.
+import type { HttpBindings } from "@hono/node-server";
+import type { Handler } from "hono";
+
+import type { AuthEnvironment } from "../auth/auth-http";
+
+export type ShutdownState = { requested: boolean };
+
+export const createHealthHandler =
+  ({ shutdown }: { shutdown: ShutdownState }): Handler<AuthEnvironment> =>
+  (context) =>
+    shutdown.requested
+      ? context.json({ status: "stopping" }, 503)
+      : context.json({ status: "ok" });
+
+export const createRestartHandler =
+  ({
+    onRestartRequested,
+    shutdown,
+  }: {
+    onRestartRequested?: () => void;
+    shutdown: ShutdownState;
+  }): Handler<AuthEnvironment> =>
+  (context) => {
+    const response = context.json({ status: "restarting" }, 202);
+    if (!onRestartRequested) {
+      return response;
+    }
+    const beginRestart = () => {
+      shutdown.requested = true;
+      onRestartRequested();
+    };
+    const nodeResponse = (context.env as Partial<HttpBindings> | undefined)
+      ?.outgoing;
+    if (nodeResponse) {
+      // Flush the restart acknowledgement before replacing the server.
+      nodeResponse.once("finish", beginRestart);
+    } else {
+      // In-memory Hono requests have no Node response, so defer past the handler.
+      setImmediate(beginRestart);
+    }
+    return response;
+  };

package/src/internal/server/http/create-http-app.ts

@@ -0,0 +1,53 @@
+import { Hono } from "hono";
+
+import type { AuthBoundary, AuthEnvironment } from "../auth/auth-http";
+import type { BackgroundNotificationService } from "../notifications/background-notification-service";
+import type { ServerLogger } from "../server-logger";
+import type { Runtime } from "../runtime/create-runtime";
+import { registerHttpRoutes } from "./routes";
+
+export type HttpAppOptions = {
+  auth: AuthBoundary;
+  authAssetsDirectory?: string;
+  backgroundNotifications?: BackgroundNotificationService;
+  developmentWebTarget?: string;
+  onRestartRequested?: () => void;
+  serverLogger?: ServerLogger;
+  runtime: Runtime;
+  webAssetsDir?: string;
+};
+
+export const createHttpApp = ({
+  auth,
+  authAssetsDirectory,
+  backgroundNotifications,
+  developmentWebTarget,
+  onRestartRequested,
+  serverLogger,
+  runtime,
+  webAssetsDir,
+}: HttpAppOptions) => {
+  const app = new Hono<AuthEnvironment>();
+  const shutdown = { requested: false };
+
+  registerHttpRoutes({
+    app,
+    auth,
+    authAssetsDirectory,
+    backgroundNotifications,
+    developmentWebTarget,
+    onRestartRequested,
+    runtime,
+    serverLogger,
+    shutdown,
+    webAssetsDir,
+  });
+
+  return Object.assign(app, {
+    beginShutdown: () => {
+      shutdown.requested = true;
+    },
+  });
+};
+
+export type OvermuxHttpApp = ReturnType<typeof createHttpApp>;

package/src/internal/server/http/development-web-backend.ts

@@ -0,0 +1,83 @@
+import type { HttpBindings } from "@hono/node-server";
+import { proxyFetch } from "httpxy";
+import type { Handler } from "hono";
+
+import type { AuthBoundary, AuthEnvironment } from "../auth/auth-http";
+import { errorDetails, type ServerLogger } from "../server-logger";
+
+const createForwardingHeaders = ({
+  origin,
+  remoteAddress,
+  request,
+}: {
+  origin: string;
+  remoteAddress?: string;
+  request: Request;
+}) => {
+  const headers = new Headers(request.headers);
+  [...headers.keys()].forEach((name) => {
+    if (
+      name === "authorization" ||
+      name === "cookie" ||
+      name === "forwarded" ||
+      name.startsWith("x-forwarded-")
+    ) {
+      headers.delete(name);
+    }
+  });
+  const publicUrl = new URL(origin);
+  if (remoteAddress) {
+    headers.set("x-forwarded-for", remoteAddress);
+  }
+  headers.set("x-forwarded-host", publicUrl.host);
+  headers.set(
+    "x-forwarded-port",
+    publicUrl.port || (publicUrl.protocol === "https:" ? "443" : "80"),
+  );
+  headers.set("x-forwarded-proto", publicUrl.protocol.slice(0, -1));
+  return headers;
+};
+
+export const createDevelopmentWebHandler =
+  ({
+    auth,
+    serverLogger,
+    target,
+  }: {
+    auth: AuthBoundary;
+    serverLogger?: ServerLogger;
+    target: string;
+  }): Handler<AuthEnvironment> =>
+  async (context) => {
+    const incoming = (context.env as Partial<HttpBindings> | undefined)
+      ?.incoming;
+    const origin = auth.resolveOrigin({
+      remoteAddress: incoming?.socket.remoteAddress,
+      request: context.req.raw,
+    });
+    if (!origin) {
+      return context.text("Request origin was rejected", 403);
+    }
+    const headers = createForwardingHeaders({
+      origin,
+      remoteAddress: incoming?.socket.remoteAddress,
+      request: context.req.raw,
+    });
+    try {
+      return await proxyFetch(
+        target,
+        new Request(context.req.raw, { headers }),
+        undefined,
+        { changeOrigin: true, xfwd: false },
+      );
+    } catch (cause) {
+      serverLogger?.log({
+        details: errorDetails(cause),
+        event: "vite-http-proxy-failure",
+        level: "error",
+      });
+      return context.text("Overmux development server is unavailable", 503, {
+        "Cache-Control": "no-store",
+      });
+    }
+  };