taskchef 7.22.4 → 7.22.5

package/src/dashboard-ownership.js

@@ -5,8 +5,12 @@ import path from "node:path";
 
 export const DASHBOARD_CONTROL_VERSION = 1;
 export const DASHBOARD_OWNER_FILE = ".taskchef-dashboard-owner.json";
+export const DASHBOARD_HANDOFF_FILE = ".taskchef-dashboard-handoff.json";
 export const DASHBOARD_CONTROL_CHALLENGE_PATH = "/api/control/challenge";
 export const DASHBOARD_CONTROL_SHUTDOWN_PATH = "/api/control/shutdown";
+export const DASHBOARD_CONTROL_SESSION_PATH = "/api/control/session";
+export const DASHBOARD_CONTROL_HANDOFF_PATH = "/api/control/handoff";
+export const DASHBOARD_CONTROL_HANDOFF_COMMIT_PATH = "/api/control/handoff/commit";
 
 const OWNER_MAX_BYTES = 4_096;
 const SECRET_PATTERN = /^[a-f0-9]{64}$/;
@@ -17,6 +21,19 @@ function ownerPath(workspace) {
   return path.join(workspace, DASHBOARD_OWNER_FILE);
 }
 
+function handoffPath(workspace) {
+  return path.join(workspace, DASHBOARD_HANDOFF_FILE);
+}
+
+async function syncDirectory(directory) {
+  const handle = await open(directory, constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
 function exactKeys(value, keys) {
   return value && typeof value === "object" && !Array.isArray(value)
     && Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
@@ -75,6 +92,32 @@ export function dashboardOwnerMetadata({
   };
 }
 
+export function dashboardHandoffMetadata({
+  workspace,
+  host,
+  port,
+  taskchefVersion,
+  serverVersion,
+  id,
+  pids,
+  secret,
+}) {
+  return {
+    schemaVersion: 1,
+    service: "taskchef-dashboard-handoff",
+    controlVersion: DASHBOARD_CONTROL_VERSION,
+    workspace,
+    host,
+    port,
+    taskchefVersion,
+    serverVersion,
+    launcher: "session",
+    id,
+    pids,
+    proof: dashboardControlProof(secret, `handoff-final:${JSON.stringify(pids)}`, id),
+  };
+}
+
 function validOwner(value) {
   const keys = [
     "schemaVersion", "service", "controlVersion", "workspace", "host", "port",
@@ -89,41 +132,108 @@ function validOwner(value) {
     && Number.isInteger(value.port) && value.port >= 0 && value.port <= 65_535
     && typeof value.taskchefVersion === "string"
     && typeof value.serverVersion === "string"
-    && value.launcher === "mcp"
+    && new Set(["mcp", "session"]).has(value.launcher)
     && typeof value.secret === "string" && SECRET_PATTERN.test(value.secret);
 }
 
-export async function readDashboardOwner(workspace) {
-  const filePath = ownerPath(workspace);
+function validHandoff(value) {
+  const keys = [
+    "schemaVersion", "service", "controlVersion", "workspace", "host", "port",
+    "taskchefVersion", "serverVersion", "launcher", "id", "pids", "proof",
+  ];
+  return exactKeys(value, keys)
+    && value.schemaVersion === 1
+    && value.service === "taskchef-dashboard-handoff"
+    && value.controlVersion === DASHBOARD_CONTROL_VERSION
+    && typeof value.workspace === "string"
+    && LOOPBACK_HOSTS.has(value.host)
+    && Number.isInteger(value.port) && value.port >= 1 && value.port <= 65_535
+    && typeof value.taskchefVersion === "string"
+    && typeof value.serverVersion === "string"
+    && value.launcher === "session"
+    && validDashboardControlNonce(value.id)
+    && Array.isArray(value.pids) && value.pids.length <= 64
+    && value.pids.every((pid) => Number.isSafeInteger(pid) && pid > 1)
+    && new Set(value.pids).size === value.pids.length
+    && typeof value.proof === "string" && SECRET_PATTERN.test(value.proof);
+}
+
+async function readPrivateJson(filePath) {
   const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
     const info = await handle.stat();
     if (!info.isFile() || (info.mode & 0o777) !== 0o600) {
-      throw new Error("dashboard owner record is not a private regular file");
+      throw new Error("dashboard ownership record is not a private regular file");
     }
     if (typeof process.getuid === "function" && info.uid !== process.getuid()) {
-      throw new Error("dashboard owner record has a different owner");
+      throw new Error("dashboard ownership record has a different owner");
     }
-    if (info.size > OWNER_MAX_BYTES) throw new Error("dashboard owner record is too large");
+    if (info.size > OWNER_MAX_BYTES) throw new Error("dashboard ownership record is too large");
     const buffer = Buffer.alloc(OWNER_MAX_BYTES + 1);
     const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
-    if (bytesRead > OWNER_MAX_BYTES) throw new Error("dashboard owner record is too large");
-    const value = JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
-    if (!validOwner(value) || value.workspace !== workspace) {
-      throw new Error("dashboard owner record is invalid");
-    }
-    return value;
+    if (bytesRead > OWNER_MAX_BYTES) throw new Error("dashboard ownership record is too large");
+    return JSON.parse(buffer.subarray(0, bytesRead).toString("utf8"));
   } finally {
     await handle.close();
   }
 }
 
-export async function writeDashboardOwner(workspace, value) {
+export async function readDashboardOwner(workspace) {
+  const filePath = ownerPath(workspace);
+  const value = await readPrivateJson(filePath);
+  if (!validOwner(value) || value.workspace !== workspace) {
+    throw new Error("dashboard owner record is invalid");
+  }
+  return value;
+}
+
+export async function readDashboardHandoff(workspace) {
+  const value = await readPrivateJson(handoffPath(workspace));
+  if (!validHandoff(value) || value.workspace !== workspace) {
+    throw new Error("dashboard handoff record is invalid");
+  }
+  return value;
+}
+
+export async function writeDashboardOwner(workspace, value, { signal } = {}) {
   if (!validOwner(value) || value.workspace !== workspace) {
     throw new Error("dashboard owner record does not match its canonical workspace");
   }
   const filePath = ownerPath(workspace);
   const temporary = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  const throwIfAborted = () => {
+    if (signal?.aborted) {
+      throw Object.assign(new Error("dashboard owner publication was cancelled"), {
+        code: "TASKCHEF_DASHBOARD_START_TIMEOUT",
+      });
+    }
+  };
+  try {
+    throwIfAborted();
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value)}\n`, { encoding: "utf8" });
+      throwIfAborted();
+      await handle.sync();
+      throwIfAborted();
+    } finally {
+      await handle.close();
+    }
+    throwIfAborted();
+    await rename(temporary, filePath);
+    await syncDirectory(workspace);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}
+
+export async function writeDashboardHandoff(workspace, value) {
+  if (!validHandoff(value) || value.workspace !== workspace) {
+    throw new Error("dashboard handoff record does not match its canonical workspace");
+  }
+  const filePath = handoffPath(workspace);
+  const temporary = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
   try {
     const handle = await open(temporary, "wx", 0o600);
     try {
@@ -133,6 +243,7 @@ export async function writeDashboardOwner(workspace, value) {
       await handle.close();
     }
     await rename(temporary, filePath);
+    await syncDirectory(workspace);
   } catch (error) {
     await unlink(temporary).catch(() => {});
     throw error;

package/src/dashboard-session-process.js

@@ -0,0 +1,179 @@
+import { realpath } from "node:fs/promises";
+
+import { createDashboardServer } from "./dashboard.js";
+import {
+  dashboardHandoffMetadata,
+  dashboardOwnerMetadata,
+  validDashboardControlSecret,
+  writeDashboardHandoff,
+  writeDashboardOwner,
+} from "./dashboard-ownership.js";
+import {
+  MAX_DASHBOARD_SESSION_PIDS,
+  createDashboardSessionLease,
+  validSessionPid,
+} from "./dashboard-session.js";
+import { DASHBOARD_SERVER_VERSION, TASKCHEF_VERSION } from "./version.js";
+
+export async function runDashboardSessionProcess({
+  workspace = process.env.TASKCHEF_DASHBOARD_WORKSPACE,
+  host = process.env.TASKCHEF_DASHBOARD_HOST ?? "127.0.0.1",
+  port = Number(process.env.TASKCHEF_DASHBOARD_PORT ?? 3210),
+  secret = process.env.TASKCHEF_DASHBOARD_SECRET,
+  sessionPid = Number(process.env.TASKCHEF_DASHBOARD_SESSION_PID),
+  sessionPids,
+  taskchefVersion = TASKCHEF_VERSION,
+  serverVersion = DASHBOARD_SERVER_VERSION,
+  createServer = createDashboardServer,
+  writeOwner = writeDashboardOwner,
+  writeHandoff = writeDashboardHandoff,
+  createLease = createDashboardSessionLease,
+  processObject = process,
+  signal,
+  checkIntervalMs = Number(process.env.TASKCHEF_DASHBOARD_CHECK_INTERVAL_MS ?? 1_000),
+  exitGraceMs = Number(process.env.TASKCHEF_DASHBOARD_EXIT_GRACE_MS ?? 15_000),
+} = {}) {
+  if (processObject.env) delete processObject.env.TASKCHEF_DASHBOARD_SECRET;
+  sessionPids ??= JSON.parse(process.env.TASKCHEF_DASHBOARD_SESSION_PIDS ?? "[]");
+  if (!workspace) throw new Error("dashboard session workspace is required");
+  if (!validDashboardControlSecret(secret)) {
+    throw new Error("dashboard session control credential is invalid");
+  }
+  if (!validSessionPid(sessionPid)) throw new Error("dashboard session PID is invalid");
+  if (!Array.isArray(sessionPids) || sessionPids.length > MAX_DASHBOARD_SESSION_PIDS
+      || sessionPids.some((pid) => !validSessionPid(pid))
+      || new Set([sessionPid, ...sessionPids]).size > MAX_DASHBOARD_SESSION_PIDS) {
+    throw new Error("dashboard transferred session PIDs are invalid");
+  }
+
+  const canonicalWorkspace = await realpath(workspace);
+  let server = null;
+  let lease = null;
+  let closePromise = null;
+  let closing = false;
+  let publishingOwner = false;
+  let deferredClose = null;
+  const abortError = () => Object.assign(new Error("dashboard session startup was cancelled"), {
+    code: "TASKCHEF_DASHBOARD_START_TIMEOUT",
+  });
+  const startupClosedError = () => Object.assign(
+    new Error("dashboard session closed during startup"),
+    { code: "TASKCHEF_DASHBOARD_START_EXIT" },
+  );
+  const removeListeners = () => {
+    processObject.off("SIGINT", close);
+    processObject.off("SIGTERM", close);
+  };
+  const performClose = async () => {
+    let cleanupError = null;
+    try {
+      lease?.close();
+    } catch (error) {
+      cleanupError = error;
+    }
+    await server?.close();
+    if (cleanupError) throw cleanupError;
+  };
+  const close = () => {
+    closing = true;
+    if (!closePromise && publishingOwner) {
+      closePromise = new Promise((resolve, reject) => {
+        deferredClose = { resolve, reject };
+      }).finally(removeListeners);
+    } else if (!closePromise) {
+      closePromise = performClose().finally(removeListeners);
+    }
+    return closePromise;
+  };
+  const onAbort = () => {
+    void close().catch(() => {});
+  };
+  if (signal?.aborted) throw abortError();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  processObject.once("SIGINT", close);
+  processObject.once("SIGTERM", close);
+  const control = {
+    secret,
+    onShutdown: close,
+    onSession: (pid) => {
+      if (closing) {
+        throw Object.assign(new Error("dashboard session is retiring"), {
+          code: "TASKCHEF_DASHBOARD_SESSION_RETIRING",
+        });
+      }
+      lease.register(pid);
+    },
+    onHandoff: (pid) => {
+      if (closing) {
+        throw Object.assign(new Error("dashboard session is retiring"), {
+          code: "TASKCHEF_DASHBOARD_SESSION_RETIRING",
+        });
+      }
+      lease.register(pid);
+      return lease.snapshot();
+    },
+    onHandoffFinalized: ({ id, pids }) => writeHandoff(
+      canonicalWorkspace,
+      dashboardHandoffMetadata({
+        workspace: canonicalWorkspace,
+        host,
+        port: server.port,
+        taskchefVersion,
+        serverVersion,
+        id,
+        pids,
+        secret,
+      }),
+    ),
+  };
+
+  try {
+    server = await createServer({
+      workspace: canonicalWorkspace,
+      host,
+      port,
+      taskchefVersion,
+      serverVersion,
+      launcher: "session",
+      control,
+    });
+    if (closing) {
+      closePromise = null;
+      if (signal?.aborted) throw abortError();
+      throw startupClosedError();
+    }
+    lease = createLease({ initialPid: sessionPid, checkIntervalMs, exitGraceMs, onExpire: close });
+    for (const pid of sessionPids) lease.register(pid);
+    publishingOwner = true;
+    try {
+      await writeOwner(canonicalWorkspace, dashboardOwnerMetadata({
+        workspace: canonicalWorkspace,
+        host,
+        port: server.port,
+        taskchefVersion,
+        serverVersion,
+        launcher: "session",
+        secret,
+      }), { signal });
+    } finally {
+      publishingOwner = false;
+      if (deferredClose) {
+        const pending = deferredClose;
+        deferredClose = null;
+        void performClose().then(pending.resolve, pending.reject);
+      }
+    }
+    if (closing) {
+      await closePromise;
+      if (signal?.aborted) throw abortError();
+      throw startupClosedError();
+    }
+    if (signal?.aborted) throw abortError();
+    signal?.removeEventListener("abort", onAbort);
+    return { server, lease, close };
+  } catch (error) {
+    signal?.removeEventListener("abort", onAbort);
+    await close().catch(() => {});
+    throw error;
+  }
+}

package/src/dashboard-session.js

@@ -0,0 +1,91 @@
+const DEFAULT_CHECK_INTERVAL_MS = 1_000;
+const DEFAULT_EXIT_GRACE_MS = 15_000;
+export const MAX_DASHBOARD_SESSION_PIDS = 64;
+export const MAX_TRANSFERRED_DASHBOARD_SESSION_PIDS = MAX_DASHBOARD_SESSION_PIDS - 1;
+
+export function processIsAlive(pid, processObject = process) {
+  try {
+    processObject.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+export function validSessionPid(pid) {
+  return Number.isSafeInteger(pid) && pid > 1;
+}
+
+export function createDashboardSessionLease({
+  initialPid,
+  checkIntervalMs = DEFAULT_CHECK_INTERVAL_MS,
+  exitGraceMs = DEFAULT_EXIT_GRACE_MS,
+  isAlive = processIsAlive,
+  now = Date.now,
+  onExpire,
+} = {}) {
+  if (!validSessionPid(initialPid)) throw new Error("dashboard session PID is invalid");
+  if (!Number.isFinite(checkIntervalMs) || checkIntervalMs <= 0) {
+    throw new Error("dashboard session check interval must be positive");
+  }
+  if (!Number.isFinite(exitGraceMs) || exitGraceMs < 0) {
+    throw new Error("dashboard session exit grace must be non-negative");
+  }
+  if (typeof onExpire !== "function") throw new Error("dashboard session expiry callback is required");
+
+  const pids = new Set([initialPid]);
+  let absentSince = null;
+  let expiryPromise = null;
+  let timer = null;
+
+  const activePids = () => {
+    let active = false;
+    for (const pid of pids) {
+      if (isAlive(pid)) active = true;
+      else pids.delete(pid);
+    }
+    return active;
+  };
+
+  const tick = () => {
+    if (expiryPromise) return;
+    const active = activePids();
+    if (active) {
+      absentSince = null;
+      return;
+    }
+    absentSince ??= now();
+    if (now() - absentSince < exitGraceMs) return;
+    expiryPromise = Promise.resolve().then(onExpire).catch(() => {});
+  };
+
+  timer = setInterval(tick, checkIntervalMs);
+  timer.unref?.();
+
+  return {
+    register(pid) {
+      if (!validSessionPid(pid)) throw new Error("dashboard session PID is invalid");
+      if (expiryPromise) {
+        throw Object.assign(new Error("dashboard session is expiring"), {
+          code: "TASKCHEF_DASHBOARD_SESSION_RETIRING",
+        });
+      }
+      activePids();
+      if (!pids.has(pid) && pids.size >= MAX_DASHBOARD_SESSION_PIDS) {
+        throw new Error("dashboard session PID limit reached");
+      }
+      pids.add(pid);
+      absentSince = null;
+    },
+    snapshot() {
+      activePids();
+      return [...pids];
+    },
+    tick,
+    close() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
+    get sessionCount() { return pids.size; },
+  };
+}