mcp-pacemaker 2.0.2 → 2.1.1

package/bin/managed-runtime.mjs

@@ -0,0 +1,170 @@
+import { fork } from 'node:child_process';
+import { closeSync, existsSync, openSync } from 'node:fs';
+import { get } from 'node:http';
+import { connect } from 'node:net';
+import { join } from 'node:path';
+import { loadInstance, readManagedJson } from './managed-state.mjs';
+import { controlManagedService, resumeService, servicePaths, stopManagedService, validateServiceRecord } from './service-control.mjs';
+import { requireUserRuntimeContext } from './runtime-context.mjs';
+
+const launches = new Map();
+
+export function listenerOpen(port) {
+  return new Promise((resolveProbe, reject) => {
+    const socket = connect({ host: '127.0.0.1', port });
+    socket.once('connect', () => { socket.destroy(); resolveProbe(true); });
+    socket.once('error', error => {
+      if (error.code === 'ECONNREFUSED') resolveProbe(false);
+      else reject(error);
+    });
+    socket.setTimeout(2000, () => socket.destroy(new Error('Listener identity probe timed out.')));
+  });
+}
+
+export function backendStatus(port) {
+  return new Promise((resolveStatus, reject) => {
+    const request = get(`http://127.0.0.1:${port}/api/status`, response => {
+      let body = '';
+      response.on('data', bytes => {
+        body += bytes;
+        if (body.length > 4 * 1024 * 1024) request.destroy(new Error('Oversized backend status.'));
+      });
+      response.on('end', () => {
+        try {
+          if (response.statusCode !== 200) throw new Error('Backend not ready.');
+          resolveStatus(JSON.parse(body));
+        } catch (error) { reject(error); }
+      });
+    });
+    request.on('error', reject);
+    request.setTimeout(2000, () => request.destroy(new Error('Backend readiness timed out.')));
+  });
+}
+
+export function serviceSelection(instance) {
+  return { root: instance.active.root, config: instance.config, port: instance.port };
+}
+
+function assertInstanceService(instance) {
+  const record = validateServiceRecord(
+    readManagedJson(servicePaths(instance.config, instance.port).record), serviceSelection(instance));
+  if (record.managedInstance !== instance.directory) {
+    throw new Error('Supervisor belongs to a different managed instance; no service action was sent.');
+  }
+}
+
+export async function startInstance(directory, { pending = false, token } = {}) {
+  await requireUserRuntimeContext();
+  let instance = loadInstance(directory);
+  const journalPath = join(directory, 'journal.json');
+  if (existsSync(journalPath)) {
+    const journal = readManagedJson(journalPath);
+    const legacyStart = journal.phase === 'legacy-launching' &&
+      journal.legacy?.protocol === 1 &&
+      journal.legacy.acknowledged === 'restart-with-uncertain-http-and-partial-tree-v1';
+    const authorized = (['launching', 'rollback-launching'].includes(journal.phase) || legacyStart) &&
+      journal.launchToken === token &&
+      pending;
+    if (!['committed', 'rolled-back', 'aborted'].includes(journal.phase) &&
+        !authorized) throw new Error('Unfinished upgrade journal blocks start; use explicit recovery.');
+  }
+  if (instance.port !== 0 &&
+      await listenerOpen(instance.port)) throw new Error('Selected port is busy; no listener was adopted.');
+  if (instance.port) resumeService(instance.config, instance.port);
+  const log = openSync(join(directory, 'launcher.log'), 'a', 0o600);
+  const child = fork(join(directory, 'stable-launcher.mjs'), [], {
+    execPath: instance.node, execArgv: [], detached: true, windowsHide: true,
+    stdio: ['ignore', log, log, 'ipc'],
+    env: {
+      ...process.env, MCP_PACEMAKER_UPGRADE_PENDING: pending ? '1' : '0',
+      MCP_PACEMAKER_UPGRADE_TOKEN: token ?? '',
+    },
+  });
+  closeSync(log);
+  const exited = new Promise(resolveExit => child.once('exit', resolveExit));
+  const running = launches.get(directory) ?? [];
+  running.push({ child, exited });
+  launches.set(directory, running);
+  let timer;
+  let startupStopped = false;
+  let startupStopId;
+  child.on('message', message => {
+    if (message?.type === 'supervisor-stopped' &&
+        message.stopped === true) {
+      startupStopped = true;
+      startupStopId = message.id;
+    }
+  });
+  try {
+    const ready = await new Promise((resolveReady, reject) => {
+      child.once('error', reject);
+      child.once('exit', () => reject(new Error(`Managed startup failed. Inspect ${join(directory, 'launcher.log')}.`)));
+      child.on('message', message => {
+        if (message?.type === 'supervisor-ready') resolveReady(message);
+      });
+      timer = setTimeout(() => reject(new Error('Managed startup readiness timed out.')), 15000);
+    });
+    instance = loadInstance(directory, { verifyFiles: false });
+    const valid = ready.version === instance.active.version &&
+      ready.port === instance.port &&
+      ready.held === pending;
+    if (!valid) throw new Error('Started backend identity does not match the active selection.');
+    const status = await backendStatus(instance.port);
+    if (status.service !== 'mcp-pacemaker' ||
+        status.version !== ready.version ||
+        status.instanceId !== ready.instanceId) throw new Error('Actual listener did not verify the started backend.');
+    return { instance, ready };
+  } catch (error) {
+    if (child.connected) {
+      child.send('stop');
+      await new Promise((resolveExit, reject) => {
+        if (child.exitCode !== null) { resolveExit(); return; }
+        const deadline = setTimeout(() => reject(new Error('Failed startup shutdown is unverified; retain journal and package.')), 12000);
+        child.once('exit', () => { clearTimeout(deadline); resolveExit(); });
+      });
+    }
+    error.startupStopped = startupStopped;
+    if (startupStopped) error.startupProof = {
+      supervisorId: startupStopId, root: instance.active.root, config: instance.config,
+      port: instance.port, launchToken: token,
+    };
+    if (!startupStopped) error.cleanupUnverified = true;
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    if (child.connected) child.disconnect();
+    child.unref();
+  }
+}
+
+export async function stopInstance(instance, quiescedInstanceId) {
+  assertInstanceService(instance);
+  const selection = serviceSelection(instance);
+  const stopped = await stopManagedService({ ...selection, quiescedInstanceId });
+  if (await listenerOpen(instance.port)) throw new Error('Stopped supervisor still has a live listener; recovery required.');
+  await waitForInstanceExit(instance.directory);
+  return stopped;
+}
+
+export async function waitForInstanceExit(directory) {
+  const running = launches.get(directory) ?? [];
+  let timeout;
+  try {
+    await Promise.race([
+      Promise.all(running.map(entry => entry.exited)),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new Error('Owned stable launcher did not exit; retain its files.')), 12000);
+      }),
+    ]);
+    launches.delete(directory);
+  } finally { clearTimeout(timeout); }
+}
+
+export async function inspectInstance(instance, action = 'inspect', expected = {}) {
+  assertInstanceService(instance);
+  const response = await controlManagedService(serviceSelection(instance), action, expected);
+  const status = await backendStatus(instance.port);
+  if (status.version !== response.version ||
+      status.instanceId !== response.instanceId) throw new Error('Listener and managed supervisor identity disagree.');
+  return response;
+}

package/bin/managed-state.mjs

@@ -0,0 +1,257 @@
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync,
+  readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const legacyMigrationPhases = [
+  'legacy-prepared', 'legacy-holding', 'legacy-held', 'legacy-stopping',
+  'legacy-stopped', 'legacy-launching', 'legacy-wiring', 'legacy-admitting',
+  'legacy-rollback-stopping', 'legacy-task-restoring', 'legacy-cli-restoring', 'legacy-rollback-launching',
+  'legacy-rolled-back', 'legacy-aborted',
+];
+
+export function readManagedJson(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.nlink !== 1 ||
+      stat.size > 4 * 1024 * 1024) throw new Error('Unsafe managed state file.');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function durableJson(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify(value, null, 2) + '\n');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(temporary, path);
+  if (process.platform !== 'win32') {
+    const directory = openSync(dirname(path), 'r');
+    try { fsyncSync(directory); } finally { closeSync(directory); }
+  }
+}
+
+export function managedPath(config, port) {
+  return join(dirname(resolve(config)), 'managed', String(port));
+}
+
+export function directoryIdentity(path) {
+  const stat = lstatSync(path, { bigint: true });
+  if (!stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      realpathSync(path) !== resolve(path)) throw new Error('Managed directory is linked or replaced.');
+  return `${stat.dev}:${stat.ino}`;
+}
+
+export function readInstanceState(directory) {
+  directory = realpathSync.native(directory);
+  const instance = readManagedJson(join(directory, 'instance.json'));
+  const valid = instance.protocol === 1 &&
+    instance.directory === directory &&
+    instance.directoryIdentity === directoryIdentity(directory) &&
+    typeof instance.id === 'string' &&
+    /^[a-f0-9-]{36}$/.test(instance.id) &&
+    typeof instance.config === 'string' &&
+    resolve(instance.config) === instance.config &&
+    typeof instance.cwd === 'string' &&
+    resolve(instance.cwd) === instance.cwd &&
+    typeof instance.node === 'string' &&
+    realpathSync(instance.node) === instance.node &&
+    Number.isInteger(instance.port) &&
+    instance.port >= 0 &&
+    instance.port <= 65535;
+  if (!valid) throw new Error('Managed instance identity mismatch.');
+  const active = readManagedJson(join(directory, 'active.json'));
+  validateSelectionReference(active);
+  return { ...instance, active };
+}
+
+export function loadInstance(directory, { verifyFiles = true } = {}) {
+  const instance = readInstanceState(directory);
+  verifySelection(instance.active, { verifyFiles });
+  return instance;
+}
+
+export function validateSelectionReference(selection) {
+  const valid = selection &&
+    typeof selection.root === 'string' &&
+    selection.root.length <= 4096 &&
+    resolve(selection.root) === selection.root &&
+    typeof selection.directoryIdentity === 'string' &&
+    selection.directoryIdentity.length < 128 &&
+    typeof selection.version === 'string' &&
+    selection.version.length < 128 &&
+    Array.isArray(selection.files) &&
+    selection.files.length > 0 &&
+    selection.files.length <= 20000;
+  if (!valid) throw new Error('Invalid managed package selection reference.');
+}
+
+export function readRecoveryContext(directory) {
+  const instance = readInstanceState(directory);
+  const journal = readManagedJson(join(instance.directory, 'journal.json'));
+  const binding = { config: instance.config, cwd: instance.cwd, node: instance.node, port: instance.port };
+  if (journal.sxs &&
+      journal.binding?.port === 0) binding.port = 0;
+  const phases = [
+    'prepared', 'quiescing', 'stopping', 'stopped', 'selecting', 'selected', 'launching',
+    'rollback-selecting', 'rollback-selected', 'rollback-launching',
+    'admitting', 'admitting-rollback', 'committed', 'rolled-back', 'aborted', 'starting',
+  ];
+  if (journal.legacy?.protocol === 1) {
+    if (journal.previous !== null ||
+        journal.legacy.acknowledged !== 'restart-with-uncertain-http-and-partial-tree-v1') {
+      throw new Error('Invalid legacy migration journal contract.');
+    }
+    phases.push(...legacyMigrationPhases);
+    validateSelectionReference(journal.recovery);
+  }
+  if (journal.protocol !== 1 ||
+      journal.instanceId !== instance.id ||
+      JSON.stringify(journal.binding) !== JSON.stringify(binding) ||
+      !phases.includes(journal.phase)) throw new Error('Recovery journal identity or phase is invalid.');
+  validateSelectionReference(journal.target);
+  if (journal.previous) validateSelectionReference(journal.previous);
+  const allowed = [journal.previous, journal.target].filter(Boolean);
+  if (!allowed.some(selection => JSON.stringify(selection) === JSON.stringify(instance.active))) {
+    throw new Error('Active selection is not an authorized journal selection.');
+  }
+  if (journal.rollbackStopProof &&
+      !allowed.some(selection => JSON.stringify(selection) === JSON.stringify(journal.rollbackStopProof.selection))) {
+    throw new Error('Rollback proof names a package outside the activation journal.');
+  }
+  return { instance, journal };
+}
+
+export function verifySelection(selection, { verifyFiles = true } = {}) {
+  validateSelectionReference(selection);
+  if (!selection ||
+      typeof selection.root !== 'string' ||
+      selection.directoryIdentity !== directoryIdentity(selection.root)) throw new Error('Active package directory identity changed.');
+  const pkg = readManagedJson(join(selection.root, 'package.json'));
+  if (pkg.name !== 'mcp-pacemaker' ||
+      pkg.version !== selection.version) throw new Error('Active package identity changed.');
+  const required = ['package.json', 'bin/mcp-bridge.mjs', 'supervisor/supervise.mjs', 'bin/upgrade-capability.json'];
+  if (!Array.isArray(selection.files) ||
+      required.some(path => !selection.files.some(file => file.path === path))) {
+    throw new Error('Immutable package inventory is missing required files.');
+  }
+  if (!verifyFiles) return;
+  const seen = new Set();
+  const directories = new Set();
+  for (const file of selection.files) {
+    if (typeof file.path !== 'string' ||
+        !/^[a-zA-Z0-9_./@+-]+$/.test(file.path) ||
+        file.path.split('/').some(part => !part || part === '.' || part === '..') ||
+        !/^[a-f0-9]{64}$/.test(file.sha256) ||
+        seen.has(file.path.toLowerCase())) throw new Error('Invalid immutable package inventory.');
+    seen.add(file.path.toLowerCase());
+    const path = resolve(selection.root, file.path);
+    if (!path.startsWith(selection.root + '/') &&
+        !path.startsWith(selection.root + '\\')) throw new Error('Unsafe package inventory path.');
+    const parent = dirname(path);
+    if (!directories.has(parent)) {
+      if (realpathSync.native(parent) !== parent) throw new Error('Immutable package directory was linked or replaced.');
+      directories.add(parent);
+    }
+    const stat = lstatSync(path);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        createHash('sha256').update(readFileSync(path)).digest('hex') !== file.sha256) throw new Error('Immutable package bytes changed.');
+  }
+}
+
+export function createInstance({ directory, root, config, port, cwd = dirname(config), node = process.execPath,
+  autostart = { kind: 'none' }, selection, controllerOperation }) {
+  directory = resolve(directory);
+  root = realpathSync(root);
+  if (existsSync(directory)) throw new Error('Managed instance already exists; refusing to overwrite it.');
+  mkdirSync(dirname(directory), { recursive: true, mode: 0o700 });
+  mkdirSync(directory, { mode: 0o700 });
+  directory = realpathSync.native(directory);
+  const version = readManagedJson(join(root, 'package.json')).version;
+  const instance = {
+    protocol: 1, id: randomUUID(), directory, directoryIdentity: directoryIdentity(directory),
+    config: resolve(config), cwd: resolve(cwd), port, autostart, node: realpathSync(node),
+    ...(controllerOperation ? { controllerOperation: structuredClone(controllerOperation) } : {}),
+  };
+  for (const file of ['stable-launcher.mjs', 'managed-state.mjs']) {
+    copyFileSync(new URL(`./${file}`, import.meta.url), join(directory, file));
+  }
+  if (process.platform === 'win32') {
+    const launcher = join(directory, 'stable-launcher.mjs');
+    if (/["\r\n]/.test(instance.node + launcher)) throw new Error('Unsupported Windows launcher path.');
+    writeFileSync(join(directory, 'launcher.vbs'),
+      `Set shell = CreateObject("WScript.Shell")\r\nshell.Run """${instance.node}"" ""${launcher}""", 0, False\r\n`,
+      { flag: 'wx', mode: 0o600 });
+  }
+  durableJson(join(directory, 'instance.json'), instance);
+  if (!selection) selection = snapshotPackage(root, join(directory, 'versions', `${version}-${randomUUID()}`));
+  verifySelection(selection);
+  durableJson(join(directory, 'active.json'), selection);
+  return loadInstance(directory, { verifyFiles: false });
+}
+
+export function snapshotPackage(source, destination, { dependencies = true } = {}) {
+  const pkg = readManagedJson(join(source, 'package.json'));
+  if (!Array.isArray(pkg.files)) throw new Error('A packaged file inventory is required for the stable installation.');
+  mkdirSync(destination, { recursive: true, mode: 0o700 });
+  const files = [];
+  const seen = new Set();
+  const copy = relative => {
+    relative = relative.replace(/\/$/, '');
+    if (!/^[a-zA-Z0-9_./@+-]+$/.test(relative) ||
+        relative.split('/').some(part => !part || part === '.' || part === '..')) throw new Error('Invalid package file inventory.');
+    if (seen.has(relative)) return;
+    seen.add(relative);
+    const path = join(source, relative);
+    if (!existsSync(path)) return;
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) throw new Error('Linked package inputs cannot form an immutable installation.');
+    if (stat.isDirectory()) {
+      for (const entry of readdirSync(path)) copy(`${relative}/${entry}`);
+      return;
+    }
+    if (!stat.isFile() ||
+        stat.nlink !== 1) throw new Error('Unsupported package input.');
+    const bytes = readFileSync(path);
+    const output = join(destination, relative);
+    mkdirSync(dirname(output), { recursive: true, mode: 0o700 });
+    writeFileSync(output, bytes, { flag: 'wx', mode: stat.mode & 0o777 });
+    files.push({ path: relative, sha256: createHash('sha256').update(bytes).digest('hex') });
+  };
+  for (const path of ['package.json', 'README.md', 'CHANGELOG.md', 'LICENSE', ...pkg.files]) copy(path);
+  if (!dependencies) return { root: realpathSync(destination), version: pkg.version, directoryIdentity: directoryIdentity(destination), files };
+  if (!existsSync(join(source, 'package-lock.json')) ||
+      !existsSync(join(source, 'node_modules'))) throw new Error('Verified CLI dependencies are required before creating a managed installation.');
+  copy('package-lock.json');
+  if (existsSync(join(source, 'node_modules', '.package-lock.json'))) copy('node_modules/.package-lock.json');
+  const lock = readManagedJson(join(source, 'package-lock.json'));
+  for (const path of Object.keys(lock.packages ?? {})) {
+    if (!path) continue;
+    copy(path);
+  }
+  return { root: realpathSync(destination), version: pkg.version, directoryIdentity: directoryIdentity(destination), files };
+}
+
+export function acquireInstanceLock(directory) {
+  const identity = directoryIdentity(directory);
+  const path = join(directory, 'upgrade.lock');
+  const token = randomUUID();
+  const fd = openSync(path, 'wx', 0o600);
+  try {
+    writeFileSync(fd, JSON.stringify({ token, pid: process.pid }) + '\n');
+    fsyncSync(fd);
+  } finally { closeSync(fd); }
+  return () => {
+    if (directoryIdentity(directory) !== identity) throw new Error('Locked instance directory was replaced; no lock was removed.');
+    if (readManagedJson(path).token !== token) throw new Error('Upgrade lock identity changed; retained for recovery.');
+    unlinkSync(path);
+  };
+}