overmux 0.0.1 → 0.0.3

package/src/internal/server/http/operation-handler.ts

@@ -0,0 +1,93 @@
+// Handles operation request validation, execution, cancellation, and lifecycle logs.
+// Operation payloads are limited to 1 MiB before JSON parsing.
+import type { Handler } from "hono";
+
+import type { AuthEnvironment } from "../auth/auth-http";
+import type { ServerLogger } from "../server-logger";
+import type { Runtime } from "../runtime/create-runtime";
+import { OperationValidationError } from "../runtime/runtime-operations";
+
+const maxOperationRequestBytes = 1_048_576;
+
+const parseOperationRequest = async (request: Request) => {
+  const contentType = request.headers.get("Content-Type")?.split(";", 1)[0];
+  if (contentType?.toLowerCase() !== "application/json") {
+    return {
+      error: "Content-Type must be application/json",
+      status: 415,
+    } as const;
+  }
+  const contentLength = Number(request.headers.get("Content-Length") ?? 0);
+  if (contentLength > maxOperationRequestBytes) {
+    return { error: "Request body is too large", status: 413 } as const;
+  }
+  try {
+    const body = await request.arrayBuffer();
+    if (body.byteLength > maxOperationRequestBytes) {
+      return { error: "Request body is too large", status: 413 } as const;
+    }
+    const text = new TextDecoder().decode(body);
+    return { input: text ? (JSON.parse(text) as unknown) : undefined };
+  } catch {
+    return { error: "Invalid JSON request body", status: 400 } as const;
+  }
+};
+
+export const createOperationHandler =
+  ({
+    runtime,
+    serverLogger,
+  }: {
+    runtime: Runtime;
+    serverLogger?: ServerLogger;
+  }): Handler<AuthEnvironment, "/api/operations/:name"> =>
+  async (context) => {
+    const operation = runtime.getOperation(context.req.param("name"));
+    if (!operation) {
+      return context.json({ error: "Operation not found" }, 404);
+    }
+    const parsed = await parseOperationRequest(context.req.raw);
+    if ("error" in parsed) {
+      return context.json({ error: parsed.error }, parsed.status);
+    }
+    const correlationId =
+      context.res.headers.get("X-Overmux-Correlation-Id") ?? serverLogger?.id();
+    const startedAt = Date.now();
+    serverLogger?.log({
+      correlationId,
+      details: { registeredName: context.req.param("name") },
+      event: "operation-start",
+    });
+    try {
+      const output = await operation.execute(
+        parsed.input,
+        context.req.raw.signal,
+      );
+      serverLogger?.log({
+        correlationId,
+        details: { registeredName: context.req.param("name") },
+        durationMs: Date.now() - startedAt,
+        event: "operation-complete",
+      });
+      return operation.returnsVoid
+        ? new Response(undefined, { status: 204 })
+        : context.json(output);
+    } catch (cause) {
+      const message =
+        cause instanceof Error ? cause.message : "Operation failed";
+      serverLogger?.log({
+        correlationId,
+        details: { registeredName: context.req.param("name") },
+        durationMs: Date.now() - startedAt,
+        event: "operation-error",
+        level: "error",
+        message,
+      });
+      return context.json(
+        { error: message },
+        cause instanceof OperationValidationError && cause.phase === "input"
+          ? 400
+          : 500,
+      );
+    }
+  };

package/src/internal/server/http/request-logging.ts

@@ -0,0 +1,34 @@
+// Adds request correlation IDs and emits the final HTTP request log entry.
+// Logging runs after the matched middleware and route handler complete.
+import type { MiddlewareHandler } from "hono";
+
+import type { AuthEnvironment } from "../auth/auth-http";
+import type { ServerLogger } from "../server-logger";
+
+export const createRequestLoggingMiddleware =
+  ({
+    serverLogger,
+  }: {
+    serverLogger?: ServerLogger;
+  }): MiddlewareHandler<AuthEnvironment> =>
+  async (context, next) => {
+    const correlationId = serverLogger?.id();
+    const startedAt = Date.now();
+    if (correlationId) {
+      context.header("X-Overmux-Correlation-Id", correlationId);
+    }
+    await next();
+    const failed = context.res.status >= 400 || Boolean(context.error);
+    serverLogger?.log({
+      correlationId,
+      details: {
+        method: context.req.method,
+        path: context.req.path,
+        status: context.res.status,
+      },
+      durationMs: Date.now() - startedAt,
+      event: failed ? "http-request-failure" : "http-request",
+      level: failed ? "error" : undefined,
+      message: context.error?.message,
+    });
+  };

package/src/internal/server/http/routes.ts

@@ -0,0 +1,241 @@
+import { serveStatic } from "@hono/node-server/serve-static";
+import type { Handler, Hono, MiddlewareHandler } from "hono";
+import { join } from "node:path";
+
+import {
+  createHttpAuthenticationHandlers,
+  type AuthBoundary,
+  type AuthEnvironment,
+} from "../auth/auth-http";
+import type { BackgroundNotificationService } from "../notifications/background-notification-service";
+import type { Runtime } from "../runtime/create-runtime";
+import type { ServerLogger } from "../server-logger";
+import { createBackgroundNotificationHandlers } from "./background-notification-handlers";
+import { createDevelopmentWebHandler } from "./development-web-backend";
+import {
+  createHealthHandler,
+  createRestartHandler,
+  type ShutdownState,
+} from "./control-handlers";
+import { createOperationHandler } from "./operation-handler";
+import { createRequestLoggingMiddleware } from "./request-logging";
+import { createRuntimeManifestHandler } from "./runtime-manifest-handler";
+import { overmuxLogoutPath, overmuxSettingsPath } from "@overmux/shared";
+import { viteInfrastructurePath } from "../../shared/routes";
+
+// Registration order is the public/protected boundary. Authentication state,
+// login, and health are registered before the session gate; runtime APIs and
+// static assets are registered after it. Keep every Hono route visible in this
+// file for review.
+type RouteDescriptor =
+  | {
+      method: "USE";
+      path: string;
+      handler: MiddlewareHandler<AuthEnvironment>;
+    }
+  | {
+      method: "GET" | "POST" | "PUT" | "DELETE" | "ALL";
+      path: string;
+      handler: Handler<AuthEnvironment> | MiddlewareHandler<AuthEnvironment>;
+      middleware?: MiddlewareHandler<AuthEnvironment>;
+    };
+
+type RegisterHttpRoutesOptions = {
+  app: Hono<AuthEnvironment>;
+  auth: AuthBoundary;
+  authAssetsDirectory?: string;
+  backgroundNotifications?: BackgroundNotificationService;
+  developmentWebTarget?: string;
+  onRestartRequested?: () => void;
+  runtime: Runtime;
+  serverLogger?: ServerLogger;
+  shutdown: ShutdownState;
+  webAssetsDir?: string;
+};
+
+const applyDescriptor = (
+  app: Hono<AuthEnvironment>,
+  route: RouteDescriptor,
+) => {
+  if (route.method === "USE") {
+    app.use(route.path, route.handler);
+    return;
+  }
+  if (route.middleware) {
+    app.on(route.method, route.path, route.middleware, route.handler);
+    return;
+  }
+  app.on(route.method, route.path, route.handler);
+};
+
+export const registerHttpRoutes = ({
+  app,
+  auth,
+  authAssetsDirectory,
+  backgroundNotifications,
+  developmentWebTarget,
+  onRestartRequested,
+  runtime,
+  serverLogger,
+  shutdown,
+  webAssetsDir,
+}: RegisterHttpRoutesOptions) => {
+  const authentication = createHttpAuthenticationHandlers({
+    auth,
+    authAssetsDirectory,
+  });
+  const notificationHandlers = backgroundNotifications
+    ? createBackgroundNotificationHandlers({ backgroundNotifications })
+    : undefined;
+  const developmentWebHandler = developmentWebTarget
+    ? createDevelopmentWebHandler({
+        auth,
+        serverLogger,
+        target: developmentWebTarget,
+      })
+    : undefined;
+  const productionWebHandler = webAssetsDir
+    ? serveStatic({ path: join(webAssetsDir, "index.html") })
+    : undefined;
+  const hostedWebHandler = developmentWebHandler ?? productionWebHandler;
+  const routes: RouteDescriptor[] = [
+    {
+      method: "USE",
+      path: "*",
+      handler: createRequestLoggingMiddleware({ serverLogger }),
+    },
+    // BEGIN: UNAUTHENTICATED
+    {
+      method: "GET",
+      path: "/_overmux/auth-shell/*",
+      handler: authentication.asset,
+    },
+    {
+      method: "GET",
+      path: "/api/auth/state",
+      handler: authentication.state,
+    },
+    {
+      method: "POST",
+      path: "/api/auth/login",
+      middleware: authentication.loginBodyLimitMiddleware,
+      handler: authentication.login,
+    },
+    {
+      method: "GET",
+      path: "/login",
+      handler: authentication.loginPage,
+    },
+    {
+      method: "GET",
+      path: "/api/health",
+      handler: createHealthHandler({ shutdown }),
+    },
+    // END: UNAUTHENTICATED
+    {
+      method: "USE",
+      path: "*",
+      handler: authentication.authenticate,
+    },
+    // BEGIN: AUTHENTICATED
+    {
+      method: "POST",
+      path: "/api/auth/logout",
+      handler: authentication.logout,
+    },
+    {
+      method: "POST",
+      path: "/api/operations/:name",
+      handler: createOperationHandler({ runtime, serverLogger }),
+    },
+    {
+      method: "POST",
+      path: "/api/restart",
+      handler: createRestartHandler({ onRestartRequested, shutdown }),
+    },
+    {
+      method: "GET",
+      path: "/api/runtime-manifest",
+      handler: createRuntimeManifestHandler({ runtime }),
+    },
+    ...(notificationHandlers
+      ? [
+          {
+            method: "GET" as const,
+            path: "/api/background-notifications/public-key",
+            handler: notificationHandlers.publicKey,
+          },
+          {
+            method: "PUT" as const,
+            path: "/api/background-notifications/subscription",
+            handler: notificationHandlers.enable,
+          },
+          {
+            method: "DELETE" as const,
+            path: "/api/background-notifications/subscription",
+            handler: notificationHandlers.disable,
+          },
+        ]
+      : []),
+    {
+      method: "ALL",
+      path: "/api/*",
+      handler: (context) => context.notFound(),
+    },
+    ...(developmentWebHandler
+      ? [
+          {
+            method: "ALL" as const,
+            path: viteInfrastructurePath,
+            handler: developmentWebHandler,
+          },
+        ]
+      : []),
+    ...(hostedWebHandler
+      ? [
+          {
+            method: "GET" as const,
+            path: overmuxSettingsPath,
+            handler: hostedWebHandler,
+          },
+          {
+            method: "GET" as const,
+            path: overmuxLogoutPath,
+            handler: hostedWebHandler,
+          },
+        ]
+      : []),
+    {
+      method: "ALL",
+      path: "/_overmux/*",
+      handler: (context) => context.notFound(),
+    },
+    ...(developmentWebHandler
+      ? [
+          {
+            method: "ALL" as const,
+            path: "*",
+            handler: developmentWebHandler,
+          },
+        ]
+      : []),
+    ...(webAssetsDir
+      ? [
+          {
+            method: "USE" as const,
+            path: "*",
+            handler: serveStatic({ root: webAssetsDir }),
+          },
+          // Serve the SPA shell for client-side routes that do not match a static asset.
+          {
+            method: "GET" as const,
+            path: "*",
+            handler: serveStatic({ path: join(webAssetsDir, "index.html") }),
+          },
+        ]
+      : []),
+    // END: AUTHENTICATED
+  ];
+
+  routes.forEach((route) => applyDescriptor(app, route));
+};

package/src/internal/server/http/runtime-manifest-handler.ts

@@ -0,0 +1,12 @@
+// Runtime manifest responses must not be stored by client caches.
+import type { Handler } from "hono";
+
+import type { AuthEnvironment } from "../auth/auth-http";
+import type { Runtime } from "../runtime/create-runtime";
+
+export const createRuntimeManifestHandler =
+  ({ runtime }: { runtime: Runtime }): Handler<AuthEnvironment> =>
+  (context) => {
+    context.header("Cache-Control", "no-store");
+    return context.json(runtime.manifest);
+  };

package/src/internal/server/index.ts

@@ -0,0 +1,16 @@
+export {
+  checkOvermux,
+  type CheckDiagnostic,
+  type CheckOvermuxOptions,
+  type CheckResult,
+} from "./check-overmux";
+export {
+  getOvermuxPaths,
+  type GetOvermuxPathsOptions,
+  type OvermuxPaths,
+} from "./paths";
+export {
+  startOvermuxServer,
+  type OvermuxServer,
+  type OvermuxServerOptions,
+} from "./start-overmux-server";

package/src/internal/server/notifications/background-notification-payload.ts

@@ -0,0 +1,74 @@
+// Fits background notification payloads within the Web Push provider limit.
+// Input is validated by the notification service before this internal boundary.
+import type { Notification } from "../../../public/index";
+
+const maxPayloadBytes = 3_800;
+
+const payloadBytes = (payload: unknown) =>
+  new TextEncoder().encode(JSON.stringify(payload)).byteLength;
+
+const largestFittingPrefix = (
+  characters: string[],
+  accepts: (prefix: string) => boolean,
+  low = 0,
+  high = characters.length,
+): string => {
+  if (low >= high) {
+    return characters.slice(0, low).join("");
+  }
+  const middle = Math.ceil((low + high) / 2);
+  return accepts(characters.slice(0, middle).join(""))
+    ? largestFittingPrefix(characters, accepts, middle, high)
+    : largestFittingPrefix(characters, accepts, low, middle - 1);
+};
+
+const notificationPayload = (notification: Notification) => ({
+  notification,
+  type: "notification" as const,
+});
+
+export const createBackgroundNotificationPayload = (
+  notification: Notification,
+) => {
+  const original = notificationPayload(notification);
+  if (payloadBytes(original) <= maxPayloadBytes) {
+    return JSON.stringify(original);
+  }
+
+  const withoutBody = { ...notification, body: undefined };
+  const body = largestFittingPrefix(
+    [...(notification.body ?? "")],
+    (prefix) =>
+      payloadBytes(
+        notificationPayload({
+          ...withoutBody,
+          ...(prefix ? { body: prefix } : {}),
+        }),
+      ) <= maxPayloadBytes,
+  );
+  const bodyTruncated = notificationPayload({
+    ...withoutBody,
+    ...(body ? { body } : {}),
+  });
+  if (payloadBytes(bodyTruncated) <= maxPayloadBytes) {
+    return JSON.stringify(bodyTruncated);
+  }
+
+  const title = largestFittingPrefix(
+    [...notification.title],
+    (prefix) =>
+      Boolean(prefix) &&
+      payloadBytes(notificationPayload({ ...withoutBody, title: prefix })) <=
+        maxPayloadBytes,
+  );
+  if (title) {
+    return JSON.stringify(notificationPayload({ ...withoutBody, title }));
+  }
+  const safeTitle = largestFittingPrefix(
+    [...notification.title],
+    (prefix) =>
+      Boolean(prefix) &&
+      payloadBytes(notificationPayload({ title: prefix })) <= maxPayloadBytes,
+  );
+  return JSON.stringify(notificationPayload({ title: safeTitle || "Overmux" }));
+};

package/src/internal/server/notifications/background-notification-service.ts

@@ -0,0 +1,139 @@
+// Delivers background notifications through the browser Web Push standard.
+// Provider payload, VAPID signing, and expired endpoints remain inside this boundary.
+import type { BackgroundNotificationSubscription } from "../../shared/index";
+import type { Notification } from "../../../public/index";
+import webPush from "web-push";
+
+import { errorDetails, type ServerLogger } from "../server-logger";
+import type { BackgroundNotificationStore } from "./background-notification-store";
+import { createBackgroundNotificationPayload } from "./background-notification-payload";
+
+const vapidSubject = "https://github.com/richardgill/overmux";
+
+const webPushStatus = (cause: unknown) => {
+  if (
+    typeof cause === "object" &&
+    cause !== null &&
+    "statusCode" in cause &&
+    typeof cause.statusCode === "number"
+  ) {
+    return cause.statusCode;
+  }
+  return undefined;
+};
+
+const deliverToSubscription = async ({
+  keys,
+  logger,
+  payload,
+  sendWebPush,
+  store,
+  subscription,
+}: {
+  keys: Awaited<ReturnType<BackgroundNotificationStore["getOrCreateKeys"]>>;
+  logger?: ServerLogger;
+  payload: string;
+  sendWebPush: typeof webPush.sendNotification;
+  store: BackgroundNotificationStore;
+  subscription: BackgroundNotificationSubscription;
+}) => {
+  try {
+    await sendWebPush(subscription, payload, {
+      TTL: 60,
+      vapidDetails: {
+        privateKey: keys.privateKey,
+        publicKey: keys.publicKey,
+        subject: vapidSubject,
+      },
+    });
+  } catch (cause) {
+    const status = webPushStatus(cause);
+    if (status === 404 || status === 410) {
+      await store.removeSubscription(subscription.endpoint);
+    }
+    logger?.log({
+      details: {
+        ...errorDetails(cause),
+        ...(status ? { status } : {}),
+      },
+      event: "background-notification-delivery-failure",
+      level: "warn",
+    });
+  }
+};
+
+export type BackgroundNotificationService = {
+  disable: (endpoint: string) => Promise<void>;
+  disableSessions: (sessionIds: ReadonlySet<string>) => Promise<void>;
+  enable: (
+    sessionId: string,
+    subscription: BackgroundNotificationSubscription,
+  ) => Promise<void>;
+  publicKey: () => Promise<string>;
+  send: (notification: Notification) => Promise<void>;
+};
+
+export const createBackgroundNotificationService = ({
+  isSessionActive = async () => true,
+  logger,
+  sendWebPush = webPush.sendNotification,
+  store,
+}: {
+  isSessionActive?: (sessionId: string) => Promise<boolean>;
+  logger?: ServerLogger;
+  sendWebPush?: typeof webPush.sendNotification;
+  store: BackgroundNotificationStore;
+}): BackgroundNotificationService => {
+  let keysPromise:
+    | ReturnType<BackgroundNotificationStore["getOrCreateKeys"]>
+    | undefined;
+  const getKeys = () => {
+    if (!keysPromise) {
+      keysPromise = store
+        .getOrCreateKeys(webPush.generateVAPIDKeys)
+        .catch((cause: unknown) => {
+          keysPromise = undefined;
+          throw cause;
+        });
+    }
+    return keysPromise;
+  };
+
+  return {
+    disable: (endpoint) => store.removeSubscription(endpoint),
+    disableSessions: (sessionIds) =>
+      store.removeSessionSubscriptions(sessionIds),
+    enable: (sessionId, subscription) =>
+      store.upsertSubscription(sessionId, subscription),
+    publicKey: async () => (await getKeys()).publicKey,
+    send: async (notification) => {
+      const storedSubscriptions = await store.listSubscriptions();
+      const active = await Promise.all(
+        storedSubscriptions.map(async (entry) => ({
+          active: await isSessionActive(entry.sessionId),
+          entry,
+        })),
+      );
+      const subscriptions = active.flatMap(
+        ({ active: sessionActive, entry }) => (sessionActive ? [entry] : []),
+      );
+      if (!subscriptions.length) {
+        return;
+      }
+      const keys = await getKeys();
+      const payload = createBackgroundNotificationPayload(notification);
+      await Promise.all(
+        subscriptions.map((entry) =>
+          deliverToSubscription({
+            keys,
+            logger,
+            payload,
+            sendWebPush,
+            store,
+            subscription: entry.subscription,
+          }),
+        ),
+      );
+    },
+  };
+};