overmux 0.0.1 → 0.0.2

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

@@ -0,0 +1,162 @@
+// Defines replaceable persistence for background-notification keys and subscriptions.
+// The file implementation owns the required XDG data location and atomic updates.
+import {
+  backgroundNotificationSubscriptionSchema,
+  type BackgroundNotificationSubscription,
+} from "../../shared/index";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+
+import { getOvermuxPaths } from "../paths";
+import {
+  createPrivateJsonExclusively,
+  readPrivateJson,
+  replacePrivateJsonAtomically,
+} from "./private-json-file";
+
+const vapidKeysSchema = z
+  .object({ privateKey: z.string().min(1), publicKey: z.string().min(1) })
+  .strict();
+const storedSubscriptionSchema = z.object({
+  sessionId: z.string(),
+  subscription: backgroundNotificationSubscriptionSchema,
+});
+const subscriptionsSchema = z.array(storedSubscriptionSchema);
+
+type VapidKeys = z.infer<typeof vapidKeysSchema>;
+export type StoredBackgroundNotificationSubscription = z.infer<
+  typeof storedSubscriptionSchema
+>;
+
+export type BackgroundNotificationStore = {
+  getOrCreateKeys: (generate: () => VapidKeys) => Promise<VapidKeys>;
+  listSubscriptions: () => Promise<
+    readonly StoredBackgroundNotificationSubscription[]
+  >;
+  removeSessionSubscriptions: (
+    sessionIds: ReadonlySet<string>,
+  ) => Promise<void>;
+  removeSubscription: (endpoint: string) => Promise<void>;
+  upsertSubscription: (
+    sessionId: string,
+    subscription: BackgroundNotificationSubscription,
+  ) => Promise<void>;
+};
+
+const backgroundNotificationDataDirectory = ({
+  environment,
+  homeDirectory,
+}: {
+  environment: NodeJS.ProcessEnv;
+  homeDirectory: string;
+}) =>
+  join(
+    getOvermuxPaths({ environment, homeDir: homeDirectory }).dataDir,
+    "background-notifications",
+  );
+
+export const createFileBackgroundNotificationStore = ({
+  environment = process.env,
+  homeDirectory = homedir(),
+}: {
+  environment?: NodeJS.ProcessEnv;
+  homeDirectory?: string;
+} = {}): BackgroundNotificationStore => {
+  const directory = backgroundNotificationDataDirectory({
+    environment,
+    homeDirectory,
+  });
+  const keysPath = join(directory, "vapid.json");
+  const subscriptionsPath = join(directory, "subscriptions.json");
+  let pendingSubscriptionWrite = Promise.resolve();
+
+  const readSubscriptions = async () =>
+    (await readPrivateJson(subscriptionsPath, subscriptionsSchema)) ?? [];
+
+  const updateSubscriptions = (
+    update: (
+      subscriptions: StoredBackgroundNotificationSubscription[],
+    ) => StoredBackgroundNotificationSubscription[] | undefined,
+  ) => {
+    const operation = pendingSubscriptionWrite.then(async () => {
+      const subscriptions = await readSubscriptions();
+      const updated = update(subscriptions);
+      if (updated) {
+        await replacePrivateJsonAtomically(subscriptionsPath, updated);
+      }
+    });
+    pendingSubscriptionWrite = operation.catch(() => undefined);
+    return operation;
+  };
+
+  return {
+    getOrCreateKeys: async (generate) => {
+      const existing = await readPrivateJson(keysPath, vapidKeysSchema);
+      if (existing) {
+        return existing;
+      }
+      const generated = vapidKeysSchema.parse(generate());
+      try {
+        await createPrivateJsonExclusively(keysPath, generated);
+        return generated;
+      } catch (cause) {
+        if ((cause as NodeJS.ErrnoException).code !== "EEXIST") {
+          throw cause;
+        }
+        const concurrentlyCreated = await readPrivateJson(
+          keysPath,
+          vapidKeysSchema,
+        );
+        if (!concurrentlyCreated) {
+          throw cause;
+        }
+        return concurrentlyCreated;
+      }
+    },
+    listSubscriptions: async () => {
+      await pendingSubscriptionWrite;
+      return readSubscriptions();
+    },
+    removeSubscription: (endpoint) =>
+      updateSubscriptions((subscriptions) => {
+        if (
+          !subscriptions.some(
+            (entry) => entry.subscription.endpoint === endpoint,
+          )
+        ) {
+          return undefined;
+        }
+        return subscriptions.filter(
+          (entry) => entry.subscription.endpoint !== endpoint,
+        );
+      }),
+    removeSessionSubscriptions: (sessionIds) =>
+      updateSubscriptions((subscriptions) => {
+        const updated = subscriptions.filter(
+          (entry) => !sessionIds.has(entry.sessionId),
+        );
+        return updated.length === subscriptions.length ? undefined : updated;
+      }),
+    upsertSubscription: (sessionId, subscription) => {
+      const parsed =
+        backgroundNotificationSubscriptionSchema.parse(subscription);
+      return updateSubscriptions((subscriptions) => {
+        const entry = { sessionId, subscription: parsed };
+        const existing = subscriptions.find(
+          (candidate) => candidate.subscription.endpoint === parsed.endpoint,
+        );
+        if (isDeepStrictEqual(existing, entry)) {
+          return undefined;
+        }
+        return [
+          ...subscriptions.filter(
+            (candidate) => candidate.subscription.endpoint !== parsed.endpoint,
+          ),
+          entry,
+        ];
+      });
+    },
+  };
+};

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

@@ -0,0 +1,70 @@
+// Orchestrates operation notifications across live and background delivery.
+// Provider-specific details stay behind the background-notification service.
+import {
+  notificationSchema,
+  type Notification,
+  type Notifications,
+} from "../../../public/index";
+
+import { errorDetails, type ServerLogger } from "../server-logger";
+import type { BackgroundNotificationService } from "./background-notification-service";
+
+type NotificationService = Notifications & {
+  attachLiveDelivery: (deliver: (notification: Notification) => void) => void;
+};
+
+const deliverSafely = async ({
+  deliver,
+  event,
+  logger,
+}: {
+  deliver: () => void | Promise<void>;
+  event: string;
+  logger?: ServerLogger;
+}) => {
+  try {
+    await deliver();
+  } catch (cause) {
+    logger?.log({
+      details: errorDetails(cause),
+      event,
+      level: "error",
+    });
+  }
+};
+
+export const createNotificationService = ({
+  backgroundNotifications,
+  logger,
+}: {
+  backgroundNotifications: BackgroundNotificationService;
+  logger?: ServerLogger;
+}): NotificationService => {
+  let liveDeliveryAttached = false;
+  let deliverLive: (notification: Notification) => void = () => undefined;
+
+  return {
+    send: async (input) => {
+      const notification = notificationSchema.parse(input);
+      await Promise.all([
+        deliverSafely({
+          deliver: () => deliverLive(notification),
+          event: "live-notification-dispatch-failure",
+          logger,
+        }),
+        deliverSafely({
+          deliver: () => backgroundNotifications.send(notification),
+          event: "background-notification-dispatch-failure",
+          logger,
+        }),
+      ]);
+    },
+    attachLiveDelivery: (deliver) => {
+      if (liveDeliveryAttached) {
+        throw new Error("Live delivery is already attached");
+      }
+      liveDeliveryAttached = true;
+      deliverLive = deliver;
+    },
+  };
+};

package/src/internal/server/notifications/private-json-file.ts

@@ -0,0 +1,84 @@
+/*
+ * Provides private, schema-validated JSON files with atomic persistence: directories and files
+ * use owner-only modes; writes fsync a temporary file before rename replacement or hard-link
+ * exclusive publication so concurrent first creation safely converges.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  chmod,
+  link,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+} from "node:fs/promises";
+import { dirname } from "node:path";
+import type { z } from "zod";
+
+const missingFile = (cause: unknown) =>
+  (cause as NodeJS.ErrnoException).code === "ENOENT";
+
+const preparePrivateDirectory = async (path: string) => {
+  await mkdir(path, { mode: 0o700, recursive: true });
+  await chmod(path, 0o700);
+};
+
+const writeTemporaryPrivateJson = async (path: string, value: unknown) => {
+  await preparePrivateDirectory(dirname(path));
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}`;
+  try {
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value)}\n`);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    return temporaryPath;
+  } catch (cause) {
+    await rm(temporaryPath, { force: true });
+    throw cause;
+  }
+};
+
+export const readPrivateJson = async <TSchema extends z.ZodType>(
+  path: string,
+  schema: TSchema,
+): Promise<z.output<TSchema> | undefined> => {
+  try {
+    const contents = await readFile(path, "utf8");
+    await chmod(path, 0o600);
+    return schema.parse(JSON.parse(contents));
+  } catch (cause) {
+    if (missingFile(cause)) {
+      return undefined;
+    }
+    throw cause;
+  }
+};
+
+export const replacePrivateJsonAtomically = async (
+  path: string,
+  value: unknown,
+) => {
+  const temporaryPath = await writeTemporaryPrivateJson(path, value);
+  try {
+    await rename(temporaryPath, path);
+  } catch (cause) {
+    await rm(temporaryPath, { force: true });
+    throw cause;
+  }
+};
+
+export const createPrivateJsonExclusively = async (
+  path: string,
+  value: unknown,
+) => {
+  const temporaryPath = await writeTemporaryPrivateJson(path, value);
+  try {
+    await link(temporaryPath, path);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+};

package/src/internal/server/paths.ts

@@ -0,0 +1,13 @@
+import {
+  getOvermuxPaths,
+  type GetOvermuxPathsOptions,
+  type OvermuxPaths,
+} from "@overmux/shared/node";
+import { join } from "node:path";
+
+export { getOvermuxPaths };
+export type { GetOvermuxPathsOptions, OvermuxPaths };
+
+export const getDefaultConfigPath = (
+  options: Pick<GetOvermuxPathsOptions, "homeDir" | "xdgConfigHome"> = {},
+) => join(getOvermuxPaths(options).configDir, "overmux.config.ts");

package/src/internal/server/rate-limiter.ts

@@ -0,0 +1,58 @@
+export type RateLimiter = {
+  attemptsByKey: Map<string, number[]>;
+  globalAttempts: number[];
+  maxAttemptsPerKey: number;
+  maxGlobalAttempts: number;
+  maxTrackedKeys: number;
+  windowMs: number;
+};
+
+export const createRateLimiter = ({
+  maxAttemptsPerKey,
+  maxGlobalAttempts,
+  maxTrackedKeys,
+  windowMs,
+}: {
+  maxAttemptsPerKey: number;
+  maxGlobalAttempts: number;
+  maxTrackedKeys: number;
+  windowMs: number;
+}): RateLimiter => ({
+  attemptsByKey: new Map(),
+  globalAttempts: [],
+  maxAttemptsPerKey,
+  maxGlobalAttempts,
+  maxTrackedKeys,
+  windowMs,
+});
+
+export const hasRateLimitCapacity = ({
+  currentTime = Date.now(),
+  key,
+  limiter,
+}: {
+  currentTime?: number;
+  key: string;
+  limiter: RateLimiter;
+}) => {
+  const threshold = currentTime - limiter.windowMs;
+  const recent = (limiter.attemptsByKey.get(key) ?? []).filter(
+    (attempt) => attempt > threshold,
+  );
+  limiter.globalAttempts = limiter.globalAttempts.filter(
+    (attempt) => attempt > threshold,
+  );
+  if (
+    recent.length >= limiter.maxAttemptsPerKey ||
+    limiter.globalAttempts.length >= limiter.maxGlobalAttempts
+  ) {
+    limiter.attemptsByKey.set(key, recent);
+    return false;
+  }
+  limiter.attemptsByKey.set(key, [...recent, currentTime]);
+  limiter.globalAttempts.push(currentTime);
+  if (limiter.attemptsByKey.size > limiter.maxTrackedKeys) {
+    limiter.attemptsByKey.clear();
+  }
+  return true;
+};

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

@@ -0,0 +1,87 @@
+// Composes one process-lifetime runtime from cohesive lifecycle and protocol components.
+
+import type { RuntimeConfigDefinition } from "@overmux/shared/node";
+
+import type { Notifications } from "../../../public/index";
+import { protocolVersion, type RuntimeManifest } from "../../shared/index";
+
+import { createRuntimeLifecycle } from "./runtime-lifecycle";
+import {
+  createRuntimeOperations,
+  type RuntimeOperation,
+  type RuntimeOperationDefinitions,
+} from "./runtime-operations";
+import {
+  createRuntimeResources,
+  type RuntimeResource,
+  type RuntimeResourceDefinitions,
+} from "./runtime-resources";
+import {
+  createRuntimeStreams,
+  type RuntimeStream,
+  type RuntimeStreamDefinitions,
+} from "./runtime-streams";
+
+export type Runtime = {
+  manifest: RuntimeManifest;
+  dispose: () => Promise<void>;
+  getOperation: (name: string) => RuntimeOperation | undefined;
+  getResource: (name: string) => RuntimeResource | undefined;
+  getStream: (name: string) => RuntimeStream | undefined;
+};
+
+type CreateRuntimeOptions = {
+  config: RuntimeConfigDefinition;
+  debug?: boolean;
+  notifications?: Notifications;
+  signal?: AbortSignal;
+};
+
+export const createRuntime = async ({
+  config,
+  debug = false,
+  notifications = { send: async () => undefined },
+  signal,
+}: CreateRuntimeOptions): Promise<Runtime> => {
+  const lifecycle = createRuntimeLifecycle(signal);
+  try {
+    const resources = createRuntimeResources({
+      definitions: (config.server.resources ??
+        {}) as RuntimeResourceDefinitions,
+      lifecycle,
+    });
+    const context = resources.context;
+    const operations = createRuntimeOperations({
+      context,
+      definitions: (config.server.operations ??
+        {}) as RuntimeOperationDefinitions,
+      notifications,
+    });
+    const streams = createRuntimeStreams({
+      context,
+      definitions: (config.server.streams ?? {}) as RuntimeStreamDefinitions,
+      lifecycle,
+    });
+
+    lifecycle.signal.throwIfAborted();
+    lifecycle.completePreparation();
+
+    const manifest: RuntimeManifest = {
+      debug,
+      operations: [...operations.names],
+      protocolVersion,
+      resources: [...resources.names],
+      streams: [...streams.names],
+    };
+    return {
+      manifest,
+      dispose: lifecycle.dispose,
+      getOperation: operations.get,
+      getResource: resources.get,
+      getStream: streams.get,
+    };
+  } catch (cause) {
+    await lifecycle.dispose(cause).catch(() => undefined);
+    throw cause;
+  }
+};

package/src/internal/server/runtime/resource-dependency-graph.ts

@@ -0,0 +1,128 @@
+// Resource invalidation follows relationships among configured resources.
+// This model owns those relationships and their invariants before runtime work begins.
+
+import type { ResourceDefinition } from "../../../public/index";
+
+// A dependency supplies a derived resource's value; a dependant consumes that value.
+// Keeping both directions makes reads follow dependencies while invalidation follows dependants.
+export type ResourceDependencyGraph = Readonly<{
+  dependencies: ReadonlyMap<string, ReadonlySet<string>>;
+  dependants: ReadonlyMap<string, ReadonlySet<string>>;
+}>;
+
+type MutableResourceGraph = Map<string, Set<string>>;
+
+const emptyGraphFor = (resourceIds: readonly string[]): MutableResourceGraph =>
+  new Map(resourceIds.map((resourceId) => [resourceId, new Set<string>()]));
+
+const visitDependencies = ({
+  dependencies,
+  path,
+  resourceId,
+  visited,
+  visiting,
+}: {
+  dependencies: ReadonlyMap<string, ReadonlySet<string>>;
+  path: readonly string[];
+  resourceId: string;
+  visited: Set<string>;
+  visiting: Set<string>;
+}) => {
+  if (visiting.has(resourceId)) {
+    throw new Error(
+      `Resource dependency cycle: ${[...path, resourceId].join(" -> ")}`,
+    );
+  }
+  if (visited.has(resourceId)) {
+    return;
+  }
+  visiting.add(resourceId);
+  dependencies.get(resourceId)?.forEach((dependencyId) => {
+    visitDependencies({
+      dependencies,
+      path: [...path, resourceId],
+      resourceId: dependencyId,
+      visited,
+      visiting,
+    });
+  });
+  visiting.delete(resourceId);
+  visited.add(resourceId);
+};
+
+const assertAcyclic = (
+  dependencies: ReadonlyMap<string, ReadonlySet<string>>,
+) => {
+  // Derived reads recurse through dependencies, so a cycle could never produce a value or finish activation.
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  dependencies.forEach((_, resourceId) => {
+    visitDependencies({
+      dependencies,
+      path: [],
+      resourceId,
+      visited,
+      visiting,
+    });
+  });
+};
+
+export const createResourceDependencyGraph = (
+  resources: Readonly<Record<string, ResourceDefinition>>,
+): ResourceDependencyGraph => {
+  const resourceIds = Object.keys(resources);
+  if (resourceIds.some((resourceId) => !resourceId)) {
+    throw new Error("Resource IDs must not be empty");
+  }
+  const dependencies = emptyGraphFor(resourceIds);
+  const dependants = emptyGraphFor(resourceIds);
+
+  Object.entries(resources).forEach(([resourceId, resource]) => {
+    if (resource.kind !== "derived") {
+      return;
+    }
+    Object.entries(
+      resource.dependencies as Readonly<Record<string, string>>,
+    ).forEach(([dependencyName, dependencyId]) => {
+      if (!dependencyName) {
+        throw new Error(`Resource ${resourceId} has an empty dependency name`);
+      }
+      if (!dependencyId) {
+        throw new Error(`Resource ${resourceId} has an empty dependency ID`);
+      }
+      if (!dependencies.has(dependencyId)) {
+        throw new Error(`Unknown resource dependency: ${dependencyId}`);
+      }
+      dependencies.get(resourceId)?.add(dependencyId);
+      dependants.get(dependencyId)?.add(resourceId);
+    });
+  });
+
+  assertAcyclic(dependencies);
+  return Object.freeze({ dependencies, dependants });
+};
+
+const collectInvalidatedResourceIds = (
+  graph: ResourceDependencyGraph,
+  resourceId: string,
+  invalidated: Set<string>,
+) => {
+  if (invalidated.has(resourceId)) {
+    return;
+  }
+  invalidated.add(resourceId);
+  graph.dependants.get(resourceId)?.forEach((dependantId) => {
+    collectInvalidatedResourceIds(graph, dependantId, invalidated);
+  });
+};
+
+export const getInvalidatedResourceIds = (
+  graph: ResourceDependencyGraph,
+  resourceId: string,
+): ReadonlySet<string> => {
+  // A changed value invalidates itself and the full reverse-edge closure, not just immediate consumers.
+  // Set membership is essential for diamonds: a shared dependant must notify once despite multiple paths.
+  const invalidated = new Set<string>();
+  collectInvalidatedResourceIds(graph, resourceId, invalidated);
+  return invalidated;
+};

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

@@ -0,0 +1,95 @@
+// Composes runtime and request cancellation while owning asynchronous cleanup.
+// Tracked disposers run exactly once, and aggregate shutdown reports every failure.
+
+import type { RuntimeDisposer } from "../../../public/index";
+
+export type RuntimeLifecycle = {
+  completePreparation: () => void;
+  dispose: (reason?: unknown) => Promise<void>;
+  disposeAll: (disposers: Iterable<RuntimeDisposer>) => Promise<void>;
+  requestSignal: (signal?: AbortSignal) => AbortSignal;
+  signal: AbortSignal;
+  track: (dispose: RuntimeDisposer, signal?: AbortSignal) => RuntimeDisposer;
+};
+
+const asError = (cause: unknown) =>
+  cause instanceof Error ? cause : new Error(String(cause));
+
+const disposeAll = async (disposers: Iterable<RuntimeDisposer>) => {
+  const results = await Promise.allSettled(
+    [...disposers].map(async (dispose) => dispose()),
+  );
+  const errors = results.flatMap((result) =>
+    result.status === "rejected" ? [asError(result.reason)] : [],
+  );
+  if (errors.length) {
+    throw new AggregateError(errors, "Runtime disposal failed");
+  }
+};
+
+export const createRuntimeLifecycle = (
+  preparationSignal?: AbortSignal,
+): RuntimeLifecycle => {
+  const controller = new AbortController();
+  const activeDisposers = new Set<RuntimeDisposer>();
+  let disposal: Promise<void> | undefined;
+  const abortPreparation = () => controller.abort(preparationSignal?.reason);
+  preparationSignal?.addEventListener("abort", abortPreparation, {
+    once: true,
+  });
+  if (preparationSignal?.aborted) {
+    abortPreparation();
+  }
+
+  const completePreparation = () => {
+    preparationSignal?.removeEventListener("abort", abortPreparation);
+  };
+  const requestSignal = (signal?: AbortSignal) =>
+    signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+  const track = (
+    dispose: RuntimeDisposer,
+    signal?: AbortSignal,
+  ): RuntimeDisposer => {
+    let pending: Promise<void> | undefined;
+    const disposeOnce = () => {
+      if (pending) {
+        return pending;
+      }
+      controller.signal.removeEventListener("abort", onAbort);
+      signal?.removeEventListener("abort", onAbort);
+      activeDisposers.delete(disposeOnce);
+      pending = Promise.resolve().then(dispose);
+      return pending;
+    };
+    const onAbort = () => {
+      void disposeOnce().catch(() => undefined);
+    };
+    activeDisposers.add(disposeOnce);
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (controller.signal.aborted || signal?.aborted) {
+      onAbort();
+    }
+    return disposeOnce;
+  };
+  const dispose = (reason: unknown = new Error("Runtime disposed")) => {
+    if (disposal) {
+      return disposal;
+    }
+    completePreparation();
+    const pending = [...activeDisposers];
+    activeDisposers.clear();
+    controller.abort(reason);
+    disposal = disposeAll(pending);
+    return disposal;
+  };
+
+  return {
+    completePreparation,
+    dispose,
+    disposeAll,
+    requestSignal,
+    signal: controller.signal,
+    track,
+  };
+};