overmux 0.0.1 → 0.0.2

package/src/internal/server/runtime/runtime-operations.ts

@@ -0,0 +1,78 @@
+// Registers named operations with validated input, output, and notification context.
+// Lookup metadata stays aligned with the names published in the runtime manifest.
+
+import type {
+  HandlerContext,
+  OperationDefinition,
+} from "../../../public/index";
+import type { Notifications } from "../../../public/index";
+import { z } from "zod";
+
+export class OperationValidationError extends Error {
+  constructor(
+    readonly phase: "input" | "output",
+    cause: z.ZodError,
+  ) {
+    super(cause.message, { cause });
+  }
+}
+
+export type RuntimeOperation = {
+  execute: (input: unknown, signal?: AbortSignal) => Promise<unknown>;
+  returnsVoid: boolean;
+};
+
+export type RuntimeOperations = {
+  get: (name: string) => RuntimeOperation | undefined;
+  names: readonly string[];
+};
+
+type AnyOperation = OperationDefinition<z.ZodTypeAny, z.ZodTypeAny>;
+
+export type RuntimeOperationDefinitions = Readonly<
+  Record<string, AnyOperation>
+>;
+
+type CreateRuntimeOperationsOptions = {
+  context: (signal?: AbortSignal) => HandlerContext;
+  definitions: RuntimeOperationDefinitions;
+  notifications: Notifications;
+};
+
+export const createRuntimeOperations = ({
+  context,
+  definitions,
+  notifications,
+}: CreateRuntimeOperationsOptions): RuntimeOperations => {
+  const operations = new Map<string, RuntimeOperation>();
+  Object.entries(definitions).forEach(([name, definition]) => {
+    if (!name) {
+      throw new Error("Operation names must not be empty");
+    }
+    operations.set(name, {
+      execute: async (rawInput, signal) => {
+        const operationContext = context(signal);
+        operationContext.signal.throwIfAborted();
+        const input = definition.input.safeParse(rawInput);
+        if (!input.success) {
+          throw new OperationValidationError("input", input.error);
+        }
+        const rawOutput = await definition.handle(input.data, {
+          ...operationContext,
+          notifications,
+        });
+        operationContext.signal.throwIfAborted();
+        const output = definition.output.safeParse(rawOutput);
+        if (!output.success) {
+          throw new OperationValidationError("output", output.error);
+        }
+        return output.data;
+      },
+      returnsVoid: definition.output instanceof z.ZodVoid,
+    });
+  });
+  return {
+    get: (name) => operations.get(name),
+    names: [...operations.keys()],
+  };
+};

package/src/internal/server/runtime/runtime-resources.ts

@@ -0,0 +1,201 @@
+// Owns named runtime resource lookup, validated reads, dependency watchers, and invalidation.
+
+import {
+  type HandlerContext,
+  type ResourceDefinition,
+  type RuntimeDisposer,
+} from "../../../public/index";
+import type { ResourceContract } from "../../../public/index";
+import { isDeepStrictEqual } from "node:util";
+
+import {
+  createResourceDependencyGraph,
+  getInvalidatedResourceIds,
+} from "./resource-dependency-graph";
+import type { RuntimeLifecycle } from "./runtime-lifecycle";
+
+export type RuntimeResource = {
+  read: (input: unknown, signal?: AbortSignal) => Promise<unknown>;
+  subscribe: (
+    input: unknown,
+    listener: () => void,
+    signal?: AbortSignal,
+  ) => RuntimeDisposer;
+};
+
+export type RuntimeResourceDefinitions = Readonly<
+  Record<string, ResourceDefinition>
+>;
+
+export type RuntimeResources = {
+  context: (signal?: AbortSignal) => HandlerContext;
+  get: (name: string) => RuntimeResource | undefined;
+  invalidate: (contract: ResourceContract, input?: unknown) => void;
+  names: readonly string[];
+};
+
+type InvalidationListener = {
+  input: unknown;
+  listener: () => void;
+  resourceId: string;
+};
+
+type CreateRuntimeResourcesOptions = {
+  definitions: RuntimeResourceDefinitions;
+  lifecycle: RuntimeLifecycle;
+};
+
+export const createRuntimeResources = ({
+  definitions,
+  lifecycle,
+}: CreateRuntimeResourcesOptions): RuntimeResources => {
+  const graph = createResourceDependencyGraph(definitions);
+  const invalidationListeners = new Set<InvalidationListener>();
+  const contracts = new Map<ResourceContract, string[]>();
+  const resources = new Map<string, RuntimeResource>();
+
+  Object.entries(definitions).forEach(([id, definition]) => {
+    contracts.set(definition.contract, [
+      ...(contracts.get(definition.contract) ?? []),
+      id,
+    ]);
+  });
+
+  const invalidateResource = (
+    id: string,
+    input: unknown,
+    allInputs = false,
+  ) => {
+    if (lifecycle.signal.aborted) {
+      return;
+    }
+    const ids = getInvalidatedResourceIds(graph, id);
+    invalidationListeners.forEach((entry) => {
+      if (
+        ids.has(entry.resourceId) &&
+        (allInputs || isDeepStrictEqual(entry.input, input))
+      ) {
+        entry.listener();
+      }
+    });
+  };
+
+  const invalidate = (contract: ResourceContract, input?: unknown) => {
+    const ids =
+      contracts.get(contract) ??
+      Object.entries(definitions)
+        .filter(
+          ([, definition]) =>
+            definition.contract.input === contract.input &&
+            definition.contract.output === contract.output,
+        )
+        .map(([id]) => id);
+    if (!ids.length) {
+      throw new Error("Cannot invalidate a resource outside this runtime");
+    }
+    ids.forEach((id) => {
+      const definition = definitions[id]!;
+      const parsedInput =
+        input === undefined
+          ? undefined
+          : definition.contract.input.parse(input);
+      invalidateResource(id, parsedInput, input === undefined);
+    });
+  };
+
+  const context = (signal?: AbortSignal): HandlerContext => ({
+    invalidate,
+    signal: lifecycle.requestSignal(signal),
+  });
+
+  const read = async (
+    id: string,
+    rawInput: unknown,
+    signal?: AbortSignal,
+  ): Promise<unknown> => {
+    const definition = definitions[id]!;
+    const operationSignal = lifecycle.requestSignal(signal);
+    operationSignal.throwIfAborted();
+    const input = definition.contract.input.parse(rawInput);
+    const rawOutput =
+      definition.kind === "derived"
+        ? definition.combine(
+            Object.fromEntries(
+              await Promise.all(
+                Object.entries(
+                  definition.dependencies as Readonly<Record<string, string>>,
+                ).map(async ([name, dependencyId]) => [
+                  name,
+                  await read(dependencyId, rawInput, signal),
+                ]),
+              ),
+            ),
+          )
+        : await definition.read(input, context(signal));
+    operationSignal.throwIfAborted();
+    return definition.contract.output.parse(rawOutput);
+  };
+
+  const activateWatchers = (
+    id: string,
+    rawInput: unknown,
+    signal: AbortSignal | undefined,
+    activated: Set<string>,
+    disposers: RuntimeDisposer[],
+  ) => {
+    if (activated.has(id)) {
+      return;
+    }
+    activated.add(id);
+    const definition = definitions[id]!;
+    const input = definition.contract.input.parse(rawInput);
+    if (definition.kind === "subscription") {
+      const dispose = definition.subscribe(
+        input,
+        () => invalidateResource(id, input),
+        context(signal),
+      );
+      if (typeof dispose !== "function") {
+        throw new Error(`Resource ${id} subscribe must return a disposer`);
+      }
+      disposers.push(dispose);
+      return;
+    }
+    if (definition.kind === "derived") {
+      graph.dependencies.get(id)?.forEach((dependencyId) => {
+        activateWatchers(dependencyId, rawInput, signal, activated, disposers);
+      });
+    }
+  };
+
+  Object.keys(definitions).forEach((name) => {
+    resources.set(name, {
+      read: (input, signal) => read(name, input, signal),
+      subscribe: (rawInput, listener, signal) => {
+        lifecycle.requestSignal(signal).throwIfAborted();
+        const input = definitions[name]!.contract.input.parse(rawInput);
+        const entry = { input, listener, resourceId: name };
+        const watcherDisposers: RuntimeDisposer[] = [];
+        invalidationListeners.add(entry);
+        try {
+          activateWatchers(name, rawInput, signal, new Set(), watcherDisposers);
+        } catch (cause) {
+          invalidationListeners.delete(entry);
+          void lifecycle.disposeAll(watcherDisposers).catch(() => undefined);
+          throw cause;
+        }
+        return lifecycle.track(async () => {
+          invalidationListeners.delete(entry);
+          await lifecycle.disposeAll(watcherDisposers);
+        }, signal);
+      },
+    });
+  });
+
+  return {
+    context,
+    get: (name) => resources.get(name),
+    invalidate,
+    names: [...resources.keys()],
+  };
+};

package/src/internal/server/runtime/runtime-streams.ts

@@ -0,0 +1,130 @@
+// Owns named stream registration and ordered, validated session messaging.
+// Session abort, failure, and disposal remain exactly-once across every close path.
+
+import type {
+  HandlerContext,
+  StreamHandlerDefinition,
+} from "../../../public/index";
+import { z } from "zod";
+
+import type { RuntimeLifecycle } from "./runtime-lifecycle";
+
+export type RuntimeStreamSession = {
+  dispose: () => Promise<void>;
+  send: (message: unknown) => Promise<void>;
+};
+
+export type RuntimeStream = {
+  open: (
+    input: unknown,
+    emit: (message: unknown) => void,
+    signal?: AbortSignal,
+    onError?: (cause: unknown) => void,
+  ) => Promise<RuntimeStreamSession>;
+};
+
+export type RuntimeStreams = {
+  get: (name: string) => RuntimeStream | undefined;
+  names: readonly string[];
+};
+
+type AnyStream = StreamHandlerDefinition<
+  z.ZodTypeAny,
+  z.ZodTypeAny,
+  z.ZodTypeAny
+>;
+
+export type RuntimeStreamDefinitions = Readonly<Record<string, AnyStream>>;
+
+type CreateRuntimeStreamsOptions = {
+  context: (signal?: AbortSignal) => HandlerContext;
+  definitions: RuntimeStreamDefinitions;
+  lifecycle: RuntimeLifecycle;
+};
+
+export const createRuntimeStreams = ({
+  context,
+  definitions,
+  lifecycle,
+}: CreateRuntimeStreamsOptions): RuntimeStreams => {
+  const streams = new Map<string, RuntimeStream>();
+  Object.entries(definitions).forEach(([name, definition]) => {
+    if (!name) {
+      throw new Error("Stream names must not be empty");
+    }
+    streams.set(name, {
+      open: async (rawInput, emit, requestSignal, onError) => {
+        const sessionController = new AbortController();
+        const sessionSignal = requestSignal
+          ? AbortSignal.any([requestSignal, sessionController.signal])
+          : sessionController.signal;
+        const operationSignal = lifecycle.requestSignal(sessionSignal);
+        operationSignal.throwIfAborted();
+        const input = definition.contract.input.parse(rawInput);
+        let acceptingMessages = true;
+        let failed = false;
+        let failure: unknown;
+        let opened = false;
+        const fail = (cause: unknown) => {
+          if (failed || operationSignal.aborted) {
+            return;
+          }
+          failed = true;
+          failure = cause;
+          acceptingMessages = false;
+          sessionController.abort(cause);
+          if (opened) {
+            onError?.(cause);
+          }
+        };
+        const session = await definition.open(input, {
+          ...context(sessionSignal),
+          emit: (message) => {
+            if (operationSignal.aborted) {
+              return;
+            }
+            try {
+              emit(definition.contract.serverMessage.parse(message));
+            } catch (cause) {
+              fail(cause);
+            }
+          },
+          fail,
+          signal: operationSignal,
+        });
+        opened = true;
+        if (failed || operationSignal.aborted) {
+          await session.dispose?.();
+          operationSignal.throwIfAborted();
+          throw failure;
+        }
+        let messages = Promise.resolve();
+        const dispose = lifecycle.track(async () => {
+          acceptingMessages = false;
+          sessionController.abort(new Error("Stream session disposed"));
+          await messages.catch(() => undefined);
+          await session.dispose?.();
+        }, requestSignal);
+        return {
+          dispose: async () => dispose(),
+          send: async (rawMessage) => {
+            if (!acceptingMessages) {
+              throw new Error("Stream session is closed");
+            }
+            const message = definition.contract.clientMessage.parse(rawMessage);
+            messages = messages.then(async () => {
+              operationSignal.throwIfAborted();
+              await session.onMessage?.(message);
+              operationSignal.throwIfAborted();
+            });
+            return messages;
+          },
+        };
+      },
+    });
+  });
+  return {
+    get: (name) => streams.get(name),
+    names: [...streams.keys()],
+  };
+};

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

@@ -0,0 +1,110 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { getOvermuxPaths } from "./paths";
+
+export type ServerLogLevel = "debug" | "error" | "info" | "warn";
+
+export type ServerLogEntry = {
+  // Groups related request, connection, and operation logs for diagnostics.
+  correlationId?: string;
+  details?: Record<string, unknown>;
+  durationMs?: number;
+  event: string;
+  level?: ServerLogLevel;
+  message?: string;
+  source?: "browser" | "server";
+  timestamp?: string;
+};
+
+export type ServerLogger = {
+  enabled: boolean;
+  id: () => string;
+  log: (entry: ServerLogEntry) => void;
+};
+
+type ConfigurableServerLogger = ServerLogger & {
+  setEnabled: (enabled: boolean) => void;
+  setLogFile: (logFile: string) => void;
+};
+
+const lifecycleEvents = new Set([
+  "server-start",
+  "server-stop",
+  "websocket-close",
+  "websocket-close-event",
+  "websocket-connect",
+  "websocket-open",
+]);
+
+export const getDefaultServerLogFile = ({
+  homeDir,
+  xdgStateHome,
+}: {
+  homeDir?: string;
+  xdgStateHome?: string;
+} = {}) =>
+  join(getOvermuxPaths({ homeDir, xdgStateHome }).stateDir, "overmux.log");
+
+const safeJson = (value: unknown) => {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return JSON.stringify({
+      event: "log-serialization-error",
+      level: "error",
+      source: "server",
+      timestamp: new Date().toISOString(),
+    });
+  }
+};
+
+export const createServerLogger = ({
+  enabled,
+  logFile = getDefaultServerLogFile(),
+}: {
+  enabled: boolean;
+  logFile?: string;
+}): ConfigurableServerLogger => {
+  let activeLogFile = logFile;
+  let debugEnabled = enabled;
+  return {
+    get enabled() {
+      return debugEnabled;
+    },
+    id: randomUUID,
+    log: (entry) => {
+      if (
+        !debugEnabled &&
+        entry.level !== "error" &&
+        !lifecycleEvents.has(entry.event)
+      ) {
+        return;
+      }
+      const record = safeJson({
+        timestamp: entry.timestamp ?? new Date().toISOString(),
+        level: entry.level ?? "info",
+        source: entry.source ?? "server",
+        ...entry,
+      });
+      mkdirSync(dirname(activeLogFile), { recursive: true });
+      appendFileSync(activeLogFile, `${record}\n`, "utf8");
+      process.stderr.write(`[overmux:debug] ${record}\n`);
+    },
+    setEnabled: (nextEnabled) => {
+      debugEnabled = nextEnabled;
+    },
+    setLogFile: (nextLogFile) => {
+      activeLogFile = nextLogFile;
+    },
+  };
+};
+
+export const errorMessage = (cause: unknown) =>
+  cause instanceof Error ? cause.message : String(cause);
+
+export const errorDetails = (cause: unknown) => ({
+  message: errorMessage(cause),
+  ...(cause instanceof Error && cause.stack ? { stack: cause.stack } : {}),
+});

package/src/internal/server/server-startup-options.ts

@@ -0,0 +1,51 @@
+import {
+  serverConfigRuntimeSchema,
+  type RuntimeConfigDefinition,
+} from "@overmux/shared/node";
+import { dirname, resolve } from "node:path";
+import { z } from "zod";
+
+import type { ServerConfigDefinition } from "../../public/index";
+
+export type ResolvedServerStartupOptions = {
+  host: string;
+  logFile?: string;
+  port: number;
+  productionWebAssetsDir?: string;
+  watch: boolean;
+};
+
+export const resolveServerStartupOptions = ({
+  config,
+  configPath,
+  overrides = {},
+}: {
+  config: RuntimeConfigDefinition;
+  configPath: string;
+  overrides?: ServerConfigDefinition;
+}): ResolvedServerStartupOptions => {
+  const validatedOverrides = serverConfigRuntimeSchema
+    .omit({ port: true })
+    .extend({ port: z.number().int().min(0).max(65_535).optional() })
+    .parse(overrides);
+  const configuredLogFile = config.logFile
+    ? resolve(dirname(configPath), config.logFile)
+    : undefined;
+  const logFile = validatedOverrides.logFile
+    ? resolve(validatedOverrides.logFile)
+    : configuredLogFile;
+  const configuredWebAssetsDir = config.productionWebAssetsDir
+    ? resolve(dirname(configPath), config.productionWebAssetsDir)
+    : undefined;
+  const productionWebAssetsDir = validatedOverrides.productionWebAssetsDir
+    ? resolve(validatedOverrides.productionWebAssetsDir)
+    : configuredWebAssetsDir;
+
+  return {
+    host: validatedOverrides.host ?? config.host ?? "localhost",
+    ...(logFile === undefined ? {} : { logFile }),
+    port: validatedOverrides.port ?? config.port ?? 4200,
+    ...(productionWebAssetsDir === undefined ? {} : { productionWebAssetsDir }),
+    watch: validatedOverrides.watch ?? config.watch ?? true,
+  };
+};