mcp-pacemaker 1.3.1

package/bin/pooling-writer.mjs

@@ -0,0 +1,169 @@
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { PoolingConfigStore, PoolingConfigError } from './pooling-config.mjs';
+import { PoolingExecution, POOLING_BUDGET_MS } from './pooling-execution.mjs';
+
+if (!isMainThread &&
+    workerData?.kind === 'mcp-pooling-writer') {
+  const store = new PoolingConfigStore(workerData.configPath);
+  parentPort.on('message', ({ id, method, request, deadline, buffer }) => {
+    if (method === 'close') {
+      parentPort.close();
+      return;
+    }
+    const execution = new PoolingExecution(deadline, buffer);
+    try {
+      execution.check();
+      if (method !== 'apply' &&
+          method !== 'undo') {
+        throw new PoolingConfigError(400, 'INVALID_REQUEST', 'Unknown pooling operation.');
+      }
+      const result = store[method](request, execution);
+      const completedLate = execution.complete();
+      parentPort.postMessage({ id, result, completedLate });
+    } catch (error) {
+      execution.fail();
+      const known = error instanceof PoolingConfigError;
+      parentPort.postMessage({ id, error: {
+        statusCode: known ? error.statusCode : 500,
+        code: known ? error.code : 'WRITER_FAILED',
+        message: known ? error.message : 'Pooling writer failed. Reread the config before retrying.',
+      } });
+    }
+  });
+}
+
+export class PoolingConfigWriter {
+  #configPath;
+  #worker;
+  #pending = new Map();
+  #sequence = 0;
+  #closed = false;
+  #closing;
+  #resolveClose;
+  #failure;
+
+  constructor(configPath) {
+    this.#configPath = configPath;
+  }
+
+  apply(request, options = {}) {
+    return this.#send('apply', request, options);
+  }
+
+  undo(request, options = {}) {
+    return this.#send('undo', request, options);
+  }
+
+  #send(method, request, options) {
+    if (this.#closed) {
+      return Promise.reject(new PoolingConfigError(503, 'WRITER_CLOSED', 'Pooling writer is shutting down.'));
+    }
+    if (this.#failure) return Promise.reject(this.#failure);
+    const defaultDeadline = process.hrtime.bigint() + BigInt(POOLING_BUDGET_MS) * 1000000n;
+    const deadline = options.deadline === undefined ? defaultDeadline
+      : options.deadline < defaultDeadline ? options.deadline : defaultDeadline;
+    const execution = new PoolingExecution(deadline);
+    if (options.signal?.aborted) return Promise.reject(execution.cancel());
+    try {
+      execution.check();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    if (this.#pending.size >= 16) {
+      return Promise.reject(new PoolingConfigError(503, 'WRITER_BUSY', 'Too many pending pooling changes.'));
+    }
+    if (!this.#worker) this.#start();
+    const id = ++this.#sequence;
+    return new Promise((resolve, reject) => {
+      const pending = { resolve, reject, execution, options, settled: false };
+      const cancel = (expired) => {
+        if (pending.settled) return;
+        const error = execution.cancel(expired);
+        if (!error) return;
+        this.#settle(pending, error);
+      };
+      pending.abort = () => cancel(false);
+      this.#pending.set(id, pending);
+      try {
+        options.signal?.addEventListener('abort', pending.abort, { once: true });
+        pending.timer = setTimeout(() => cancel(true), execution.remainingMs());
+        this.#worker.postMessage({ id, method, request, deadline, buffer: execution.state.buffer });
+      } catch (error) {
+        this.#pending.delete(id);
+        this.#settle(pending, error);
+      }
+    });
+  }
+
+  #start() {
+    this.#worker = new Worker(new URL(import.meta.url), {
+      workerData: { kind: 'mcp-pooling-writer', configPath: this.#configPath },
+    });
+    this.#worker.on('message', ({ id, result, error, completedLate }) => {
+      const pending = this.#pending.get(id);
+      if (!pending) return;
+      this.#pending.delete(id);
+      const failure = error
+        ? new PoolingConfigError(error.statusCode, error.code, error.message)
+        : completedLate ? pending.execution.committedLate() : undefined;
+      if (pending.settled ||
+          completedLate) this.#lateSettlement(pending, failure, result);
+      this.#settle(pending, failure, result);
+    });
+    this.#worker.on('error', () => this.#failed());
+    this.#worker.on('exit', (code) => {
+      if (code !== 0 ||
+          this.#pending.size > 0 ||
+          !this.#closed) {
+        this.#failed();
+      }
+      this.#worker = null;
+      this.#resolveClose?.();
+    });
+  }
+
+  #failed() {
+    this.#failure ??= new PoolingConfigError(500, 'WRITER_FAILED',
+      'Pooling writer stopped. Reread the config and restart the bridge before retrying.');
+    for (const pending of this.#pending.values()) {
+      const commitFailure = pending.execution.workerFailure();
+      const failure = commitFailure ?? this.#failure;
+      if (pending.settled ||
+          commitFailure) this.#lateSettlement(pending, failure, undefined, Boolean(commitFailure));
+      this.#settle(pending, failure);
+    }
+    this.#pending.clear();
+  }
+
+  #settle(pending, error, result) {
+    if (pending.settled) return;
+    pending.settled = true;
+    clearTimeout(pending.timer);
+    pending.options.signal?.removeEventListener('abort', pending.abort);
+    if (error) pending.reject(error);
+    else pending.resolve(result);
+  }
+
+  #lateSettlement(pending, error, result, commitStarted = false) {
+    if (pending.options.onLateSettlement) {
+      try {
+        pending.options.onLateSettlement({ error, committed: Boolean(result), commitStarted });
+      } catch {
+        process.emitWarning('Unable to reconcile a pooling operation without a normal result.');
+      }
+    } else if (error &&
+        error.code !== 'WRITER_CANCELLED' &&
+        error.code !== 'WRITER_DEADLINE') {
+      process.emitWarning(`Pooling operation settled without a normal result (${error.code}). Reread the config.`);
+    }
+  }
+
+  close() {
+    this.#closed = true;
+    if (this.#closing) return this.#closing;
+    if (!this.#worker) return Promise.resolve();
+    this.#closing = new Promise((resolve) => { this.#resolveClose = resolve; });
+    this.#worker.postMessage({ method: 'close' });
+    return this.#closing;
+  }
+}

package/bin/prewarm.mjs

@@ -0,0 +1,152 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function portNumber(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) ||
+      port < 1 ||
+      port > 65535) {
+    throw new Error('Port must be an integer between 1 and 65535');
+  }
+  return port;
+}
+
+async function jsonRequest(port, path, options = {}) {
+  const response = await fetch(`http://127.0.0.1:${port}${path}`, {
+    ...options,
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (response.status === 401) {
+    throw new Error('Admin nonce was rejected. Check --config points to the running bridge, then retry.');
+  }
+  let result;
+  try {
+    result = await response.json();
+  } catch {
+    throw new Error(`Bridge on :${port} returned a non-JSON response (${response.status})`);
+  }
+  if (!response.ok) {
+    throw new Error(result.error || `Bridge on :${port} rejected the request (${response.status})`);
+  }
+  return result;
+}
+
+export function formatPrewarm(snapshot) {
+  const seconds = (ms) => ms == null ? '-' : `${(ms / 1000).toFixed(1)}s`;
+  const rows = [
+    ['SERVER', 'MODE', 'WARM/TARGET', 'STARTS', 'COLD P50', 'P95', 'SUGGESTED', 'SHARED CHILD'],
+    ...snapshot.servers.filter((server) => server.type === 'stdio').map((server) => [
+      server.name,
+      server.sharing,
+      server.sharing === 'shared' ? '-' : `${server.warm}/${server.minWarm}`,
+      String(server.spawn?.total ?? '-'),
+      seconds(server.spawn?.p50Ms),
+      seconds(server.spawn?.p95Ms),
+      server.prewarming?.eligible ? String(server.prewarming.suggestedMinWarm) : '-',
+      server.sharing === 'shared' ? server.shared
+        ? `${server.shared.state}: ${server.shared.members} sessions, ${server.shared.unresolved} pending, ${server.shared.queued} queued`
+        : 'not active' : '-',
+    ]),
+  ];
+  const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => row[column].length)));
+  return [
+    `Pre-warming on :${snapshot.port} (process counters since ${snapshot.startedAt || 'bridge start'})`,
+    ...rows.map((row) => row.map((cell, column) => cell.padEnd(widths[column])).join('  ').trimEnd()),
+    'Pre-warming is opt-in. Each warm slot holds one additional resident process.',
+    'Shared mode is separately opt-in: compatible stateless tools sessions reuse one initialized child.',
+  ].join('\n');
+}
+
+function shellArgument(text) {
+  if (process.platform === 'win32') return `"${text}"`;
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+export function formatUndoCommand(port, name, undoId, config) {
+  const executable = process.execPath;
+  const entry = fileURLToPath(new URL('./cli.mjs', import.meta.url));
+  const values = [executable, entry, name, undoId, ...(config ? [config] : [])];
+  const needsExplicitShell = process.platform === 'win32' &&
+    values.some((value) => /[%!$`"^\r\n]|\\$/.test(value));
+  if (needsExplicitShell) {
+    const quote = (value) => `'${value.replaceAll("'", "''")}'`;
+    const configArg = config ? ` --config ${quote(config)}` : '';
+    const command = `& ${quote(executable)} ${quote(entry)} prewarm --port ${port}${configArg} --server ${quote(name)} --undo ${quote(undoId)}`;
+    return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(command, 'utf16le').toString('base64')}`;
+  }
+  const configArg = config ? ` --config ${shellArgument(config)}` : '';
+  const node = process.platform === 'win32' ? 'node.exe' : shellArgument(executable);
+  return `${node} ${shellArgument(entry)} prewarm --port ${port}${configArg} --server ${shellArgument(name)} --undo ${undoId}`;
+}
+
+export async function runPrewarm(options, { configPath, ports, write = console.log } = {}) {
+  const selectedPorts = options.port ? [portNumber(options.port)] : ports.map(portNumber);
+  const actionCount = [options.enable, options.disable, options.undo].filter(Boolean).length;
+  if (actionCount > 1) throw new Error('Choose only one of --enable, --disable or --undo');
+  if (actionCount &&
+      selectedPorts.length !== 1) {
+    throw new Error('Choose --port when changing a server on a multi-bridge setup');
+  }
+  if (options.count &&
+      !options.enable) {
+    throw new Error('--count requires --enable');
+  }
+  if (options.undo &&
+      !options.server) {
+    throw new Error('--undo requires --server');
+  }
+
+  const snapshots = [];
+  for (const port of selectedPorts) {
+    const snapshot = await jsonRequest(port, '/api/status');
+    if (snapshot.service !== 'mcp-pacemaker') throw new Error(`:${port} is not a pacemaker bridge`);
+    snapshots.push(snapshot);
+  }
+
+  if (!actionCount) {
+    if (options.json) {
+      write(JSON.stringify(snapshots.length === 1 ? snapshots[0] : snapshots));
+    } else {
+      for (const snapshot of snapshots) write(formatPrewarm(snapshot));
+    }
+    return;
+  }
+
+  const snapshot = snapshots[0];
+  if (!snapshot.prewarm) throw new Error('The running bridge does not support pooling changes; update and restart it first');
+  const name = options.enable || options.disable || options.server;
+  const server = snapshot.servers.find((candidate) => candidate.name === name);
+  if (!server) throw new Error(`Unknown server: ${name}`);
+  if (server.type !== 'stdio') throw new Error('HTTP proxies have no local child to pre-warm');
+  const body = { revision: snapshot.prewarm.revision };
+  if (options.undo) {
+    body.undoId = options.undo;
+  } else {
+    body.mode = options.enable ? 'pool' : 'isolated';
+    if (options.enable) {
+      if (!server.prewarming?.eligible) throw new Error(server.prewarming?.reason || 'Server is not eligible for pre-warming');
+      body.minWarm = options.count === undefined ? server.prewarming.suggestedMinWarm : Number(options.count);
+      if (!Number.isSafeInteger(body.minWarm) ||
+          body.minWarm < 1 ||
+          body.minWarm > snapshot.prewarm.maxWarm) {
+        throw new Error(`--count must be an integer between 1 and ${snapshot.prewarm.maxWarm}`);
+      }
+    }
+  }
+  const nonce = (await readFile(join(dirname(options.config || configPath), 'admin.nonce'), 'utf8')).trim();
+  const result = await jsonRequest(snapshot.port, `/admin/servers/${encodeURIComponent(name)}/pooling`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-mcp-nonce': nonce },
+    body: JSON.stringify(body),
+  });
+  if (result.ok !== true) throw new Error(result.error || 'Bridge did not confirm the pooling change');
+  if (options.json) {
+    write(JSON.stringify(result));
+  } else {
+    write(`${name}: ${options.undo ? 'restored previous pooling settings' : body.mode === 'pool' ? `enabled ${body.minWarm} warm slot(s)` : 'disabled pre-warming'}`);
+    if (result.undoId) {
+      write(`Undo: ${formatUndoCommand(snapshot.port, name, result.undoId, options.config)}`);
+    }
+  }
+}

package/bin/server-metrics.mjs

@@ -0,0 +1,69 @@
+export class ServerMetrics {
+  constructor(sampleLimit = 50) {
+    this.sampleLimit = sampleLimit;
+    this.servers = new Map();
+  }
+
+  get(name) {
+    let metrics = this.servers.get(name);
+    if (!metrics) {
+      metrics = {
+        attempts: 0,
+        total: 0,
+        failures: 0,
+        warmAdoptions: 0,
+        sessionStarts: 0,
+        sessionResumes: 0,
+        latencies: [],
+      };
+      this.servers.set(name, metrics);
+    }
+    return metrics;
+  }
+
+  attemptingSpawn(name) {
+    this.get(name).attempts++;
+  }
+
+  spawned(name) {
+    this.get(name).total++;
+  }
+
+  failedSpawn(name) {
+    this.get(name).failures++;
+  }
+
+  adoptedWarmChild(name) {
+    this.get(name).warmAdoptions++;
+  }
+
+  openedSession(name, resumed = false) {
+    const metrics = this.get(name);
+    if (resumed) {
+      metrics.sessionResumes++;
+    } else {
+      metrics.sessionStarts++;
+    }
+  }
+
+  initialized(name, elapsedMs) {
+    const samples = this.get(name).latencies;
+    samples.push(elapsedMs);
+    if (samples.length > this.sampleLimit) samples.shift();
+  }
+
+  snapshot(name) {
+    const { latencies, ...counts } = this.get(name);
+    const sorted = [...latencies].sort((a, b) => a - b);
+    const percentile = (fraction) => sorted.length
+      ? sorted[Math.min(sorted.length - 1, Math.floor(fraction * sorted.length))]
+      : null;
+    return {
+      ...counts,
+      samples: sorted.length,
+      p50Ms: percentile(0.5),
+      p95Ms: percentile(0.95),
+      maxMs: sorted.length ? sorted[sorted.length - 1] : null,
+    };
+  }
+}

package/bin/service-control.mjs

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, unlinkSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join, resolve } from 'node:path';
+
+export function servicePaths(config, port) {
+  if (!Number.isInteger(port) ||
+      port < 1 ||
+      port > 65535) {
+    throw new Error('Service port must be an integer from 1 to 65535.');
+  }
+  const directory = dirname(resolve(config));
+  const key = createHash('sha256').update(`${directory}\n${port}`).digest('hex').slice(0, 32);
+  const socket = process.platform === 'win32'
+    ? `\\\\.\\pipe\\mcp-pacemaker-${key}`
+    : join(directory, `service-${port}.sock`);
+  if (process.platform !== 'win32' &&
+      Buffer.byteLength(socket) > 103) {
+    throw new Error('Service socket path exceeds the POSIX limit of 103 UTF-8 bytes. Use a shorter config directory; no alternate endpoint was selected.');
+  }
+  return {
+    record: join(directory, `service-${port}.json`),
+    hold: join(directory, `service-${port}.stopped`),
+    socket,
+  };
+}
+
+export function assertDurableRoot(root) {
+  if (/(^|[/\\])_npx([/\\]|$)/i.test(root)) {
+    throw new Error('Cache-backed npx roots cannot host an unattended service. Install in a durable root, then register autostart there. Use --no-autostart --no-start for wiring only.');
+  }
+}
+
+export function backendDescription(cliVersion, backend, action) {
+  const version = typeof backend?.version === 'string' ? backend.version : 'unknown';
+  const instance = typeof backend?.instanceId === 'string' ? backend.instanceId : 'unknown';
+  return `installed CLI ${cliVersion}; running backend ${version}; instance ${instance} — ${action}` +
+    (version !== cliVersion ? ' (version mismatch; adoption does not upgrade the backend)' : '');
+}
+
+export function resumeService(config, port) {
+  try {
+    unlinkSync(servicePaths(config, port).hold);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+export function validateServiceRecord(record, { root, config, port }) {
+  const matches = record?.protocol === 1 &&
+    record.root === realpathSync(root) &&
+    record.config === resolve(config) &&
+    record.port === port &&
+    record.socket === servicePaths(config, port).socket &&
+    typeof record.id === 'string' &&
+    /^[a-f0-9-]{36}$/.test(record.id) &&
+    typeof record.token === 'string' &&
+    /^[a-f0-9]{64}$/.test(record.token);
+  if (!matches) {
+    throw new Error('Managed service identity does not match this installation root, config, port and endpoint. Use the matching installation CLI; no process was stopped.');
+  }
+  return record;
+}
+
+export function requestService(socket, request) {
+  return new Promise((resolveRequest, reject) => {
+    const client = connect(socket);
+    let data = '';
+    const finish = (error, response) => {
+      client.destroy();
+      if (error) reject(error);
+      else resolveRequest(response);
+    };
+    client.setTimeout(12000, () => finish(new Error('Supervisor response timed out; shutdown is not verified.')));
+    client.on('error', () => finish(new Error('Managed supervisor is unavailable; shutdown is not verified. Older or unmanaged services require verified OS-service shutdown.')));
+    client.on('connect', () => client.write(JSON.stringify(request) + '\n'));
+    client.on('data', (chunk) => {
+      data += chunk;
+      if (data.length > 16384) {
+        finish(new Error('Invalid supervisor response.'));
+        return;
+      }
+      if (!data.includes('\n')) return;
+      let response;
+      try { response = JSON.parse(data.slice(0, data.indexOf('\n'))); }
+      catch { finish(new Error('Invalid supervisor response.')); return; }
+      finish(null, response);
+    });
+    client.on('end', () => finish(new Error('Supervisor closed before acknowledging shutdown.')));
+  });
+}
+
+export async function stopManagedService({ root, config, port, request = requestService }) {
+  const paths = servicePaths(config, port);
+  let record;
+  try {
+    record = JSON.parse(readFileSync(paths.record, 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    throw new Error(`No managed supervisor record for :${port}. Older or direct bridges require verified OS-service shutdown and disabled autostart; no process was stopped.`);
+  }
+  validateServiceRecord(record, { root, config, port });
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync(paths.hold, 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const completed = receipt?.stopped === true &&
+    receipt.id === record.id &&
+    receipt.root === record.root &&
+    receipt.config === record.config &&
+    receipt.port === record.port;
+  if (completed) {
+    return { root: record.root, config: record.config, port, supervisorId: record.id, alreadyStopped: true };
+  }
+  const response = await request(paths.socket, { action: 'stop', id: record.id, token: record.token });
+  if (response?.id !== record.id ||
+      response.stopped !== true ||
+      response.autostartHeld !== true) {
+    throw new Error('Supervisor did not verify shutdown and its autostart hold. Do not replace the installation root.');
+  }
+  return { root: record.root, config: record.config, port, supervisorId: record.id };
+}