mcp-pacemaker 2.0.1

package/bin/prewarm.mjs

@@ -0,0 +1,233 @@
+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 { status: response.status, body: result };
+}
+
+function validatePendingReceipt(receipt, name, port) {
+  const invalid = 'Bridge returned an invalid HTTP 202 receipt. Reread settings before retrying.';
+  const nonempty = (value) => typeof value === 'string' && value.length > 0;
+  const fieldsValid = receipt?.ok === true && receipt.pending === true &&
+    receipt.name === name && nonempty(receipt.batchId) &&
+    nonempty(receipt.undoId) && nonempty(receipt.revision);
+  if (!fieldsValid) throw new Error(invalid);
+
+  const snapshot = receipt.snapshot;
+  const snapshotValid = snapshot?.service === 'mcp-pacemaker' &&
+    snapshot.port === port && nonempty(snapshot.instanceId) &&
+    Number.isSafeInteger(snapshot.snapshotVersion) && snapshot.snapshotVersion > 0 &&
+    Array.isArray(snapshot.servers) && snapshot.servers.some((server) => server?.name === name) &&
+    snapshot.prewarm?.revision === receipt.revision &&
+    Number.isSafeInteger(snapshot.prewarm.maxWarm) && snapshot.prewarm.maxWarm > 0 &&
+    Number.isFinite(snapshot.prewarm.batchDelayMs) && snapshot.prewarm.batchDelayMs > 0 &&
+    Array.isArray(snapshot.prewarm.batches);
+  if (!snapshotValid) throw new Error(invalid);
+
+  const batch = snapshot.prewarm.batches.find((candidate) => candidate?.id === receipt.batchId);
+  const timingValid = batch?.status === 'pending' ? Number.isFinite(batch.applyAt)
+    : batch?.status === 'applying' && batch.applyAt === null;
+  const changesValid = Array.isArray(batch?.changes) && batch.changes.length > 0 &&
+    batch.changes.some((change) => change?.name === name) &&
+    batch.changes.every((change) => nonempty(change?.name) &&
+      (change.mode === 'pool'
+        ? change.minWarm === undefined ||
+          Number.isSafeInteger(change.minWarm) && change.minWarm >= 1 && change.minWarm <= snapshot.prewarm.maxWarm
+        : change.mode === 'isolated' && change.minWarm === undefined));
+  if (!timingValid ||
+      !changesValid ||
+      batch.revision !== receipt.revision) {
+    throw new Error(invalid);
+  }
+}
+
+export function formatPrewarm(snapshot, now = Date.now()) {
+  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)));
+  const history = snapshot.prewarm?.batches ?? [];
+  const latestFinished = history.find((batch) => ['applied', 'failed', 'cancelled'].includes(batch.status));
+  const batches = history
+    .filter((batch) => ['pending', 'applying'].includes(batch.status) ||
+      batch === latestFinished && batch.status === 'failed')
+    .map((batch) => {
+      const changes = batch.changes.map((change) => {
+        const target = change.minWarm === undefined
+          ? 'pooling with configured target' : `${change.minWarm} warm slot(s)`;
+        return `${change.name}: ${change.mode === 'pool' ? target : 'pre-warming off'}`;
+      }).join(', ');
+      if (batch.status === 'failed') return `Batch failed (${changes}): ${batch.error || 'Reread settings before retrying.'}`;
+      if (batch.status === 'applying') return `Applying batch: ${changes}.`;
+      const secondsLeft = Math.max(0, Math.ceil((batch.applyAt - now) / 1000));
+      return `Pending batch (reload in ${secondsLeft}s): ${changes}. Active settings above have not changed.`;
+    });
+  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.',
+    ...(typeof snapshot.prewarm?.saveWarning === 'string'
+      ? [`File save notice: ${snapshot.prewarm.saveWarning}`] : []),
+    ...batches,
+  ].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 { body: 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();
+  if (!options.json &&
+      typeof snapshot.prewarm.saveWarning === 'string') {
+    write(`File save notice: ${snapshot.prewarm.saveWarning}`);
+  }
+  const response = await jsonRequest(snapshot.port, `/admin/servers/${encodeURIComponent(name)}/pooling`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-mcp-nonce': nonce, 'x-mcp-pooling-batch': '1' },
+    body: JSON.stringify(body),
+  });
+  const result = response.body;
+  if (response.status === 202) {
+    validatePendingReceipt(result, name, snapshot.port);
+  } else if (response.status !== 200 ||
+             result?.pending === true) {
+    throw new Error('Bridge returned an unexpected pooling response status. Reread settings before retrying.');
+  }
+  if (result?.ok !== true) throw new Error(result?.error || 'Bridge did not confirm the pooling change');
+  if (options.json) {
+    write(JSON.stringify(result));
+  } else if (result.pending) {
+    const batch = result.snapshot?.prewarm?.batches?.find((candidate) => candidate.id === result.batchId);
+    const scope = batch?.changes.map((change) => change.name).join(', ') || name;
+    const secondsLeft = batch?.applyAt == null ? null : Math.max(0, Math.ceil((batch.applyAt - Date.now()) / 1000));
+    const timing = secondsLeft === null ? '' : ` in ${secondsLeft}s`;
+    let action;
+    if (options.undo) action = 'previous batch configuration staged';
+    else if (body.mode === 'pool') action = `${body.minWarm} warm slot(s) staged`;
+    else action = 'pre-warming disable staged';
+    write(`${name}: ${action}. Pending reload${timing}; not active yet.`);
+    if (result.undoId) {
+      write(`Cancel while pending / undo after apply (entire batch: ${scope}): ${formatUndoCommand(snapshot.port, name, result.undoId, options.config)}`);
+    }
+  } else if (result.cancelled) {
+    write(`${name}: pending batch cancelled. Active settings were not changed.`);
+  } 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 };
+}