start-command 0.34.0 → 0.35.0

package/src/lib/docker-resource-limits.js

@@ -0,0 +1,211 @@
+/**
+ * Docker resource limits that must survive a resume (issue #176).
+ *
+ * `docker commit` captures a container's filesystem and image config, but not
+ * its HostConfig. A snapshot-based resume (`$ --resume <id> -- <cmd>`) used to
+ * start the replacement container without the memory, CPU and PIDs limits the
+ * original one had — limits a supervisor typically applied with
+ * `docker update`, so they were never part of the stored launch options.
+ *
+ * This module reads the limits back out of `docker inspect` and translates the
+ * non-default ones into `docker run` flags. The flags are kept in the
+ * `--flag=value` form, so the same list is stored in the execution record,
+ * shown in `[Isolation]` status lines, and spliced into `docker run` as is.
+ */
+
+const { getDockerCommand } = require('./docker-cleanup');
+
+/** Docker's default `/dev/shm` size; only a different size is re-applied. */
+const DEFAULT_SHM_SIZE = 64 * 1024 * 1024;
+
+const KIB = 1024;
+const MIB = KIB * 1024;
+const GIB = MIB * 1024;
+
+/**
+ * Format a byte count with the largest binary unit `docker run` accepts that
+ * represents it exactly (`268435456` → `256m`).
+ * @param {number} bytes - Byte count
+ * @returns {string} Docker memory size
+ */
+function formatDockerBytes(bytes) {
+  for (const [unit, size] of [
+    ['g', GIB],
+    ['m', MIB],
+    ['k', KIB],
+  ]) {
+    if (bytes >= size && bytes % size === 0) {
+      return `${bytes / size}${unit}`;
+    }
+  }
+  return String(bytes);
+}
+
+/**
+ * Format `NanoCpus` as the decimal `--cpus` value (`500000000` → `0.5`).
+ * @param {number} nanoCpus - CPU quota in units of 1e-9 CPUs
+ * @returns {string} Docker CPU count
+ */
+function formatDockerCpus(nanoCpus) {
+  return String(Number((nanoCpus / 1e9).toFixed(9)));
+}
+
+function positive(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : null;
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+}
+
+/**
+ * Translate an inspected `HostConfig` into `docker run` flags.
+ *
+ * Only limits that differ from Docker's defaults are emitted, and only in
+ * combinations `docker run` accepts: `--memory-swap` needs `--memory`, and
+ * `--cpus` cannot be combined with `--cpu-quota`/`--cpu-period`.
+ *
+ * @param {?object} hostConfig - `docker inspect` `.HostConfig`
+ * @returns {string[]} Flags in `--flag=value` form
+ */
+function parseDockerResourceLimits(hostConfig) {
+  if (!hostConfig || typeof hostConfig !== 'object') {
+    return [];
+  }
+  const h = hostConfig;
+  const limits = [];
+
+  const memory = positive(h.Memory);
+  if (memory) {
+    limits.push(`--memory=${formatDockerBytes(memory)}`);
+    const swap = Number(h.MemorySwap);
+    if (swap === -1) {
+      limits.push('--memory-swap=-1');
+    } else if (positive(swap)) {
+      limits.push(`--memory-swap=${formatDockerBytes(swap)}`);
+    }
+  }
+  const reservation = positive(h.MemoryReservation);
+  if (reservation) {
+    limits.push(`--memory-reservation=${formatDockerBytes(reservation)}`);
+  }
+
+  const nanoCpus = positive(h.NanoCpus);
+  if (nanoCpus) {
+    limits.push(`--cpus=${formatDockerCpus(nanoCpus)}`);
+  } else {
+    const quota = positive(h.CpuQuota);
+    if (quota) {
+      limits.push(`--cpu-quota=${quota}`);
+    }
+    const period = positive(h.CpuPeriod);
+    if (period) {
+      limits.push(`--cpu-period=${period}`);
+    }
+  }
+  const shares = positive(h.CpuShares);
+  if (shares) {
+    limits.push(`--cpu-shares=${shares}`);
+  }
+  const cpusetCpus = nonEmpty(h.CpusetCpus);
+  if (cpusetCpus) {
+    limits.push(`--cpuset-cpus=${cpusetCpus}`);
+  }
+  const cpusetMems = nonEmpty(h.CpusetMems);
+  if (cpusetMems) {
+    limits.push(`--cpuset-mems=${cpusetMems}`);
+  }
+
+  const pids = positive(h.PidsLimit);
+  if (pids) {
+    limits.push(`--pids-limit=${pids}`);
+  }
+
+  const shm = positive(h.ShmSize);
+  if (shm && shm !== DEFAULT_SHM_SIZE) {
+    limits.push(`--shm-size=${formatDockerBytes(shm)}`);
+  }
+
+  if (h.StorageOpt && typeof h.StorageOpt === 'object') {
+    for (const key of Object.keys(h.StorageOpt).sort()) {
+      const value = nonEmpty(String(h.StorageOpt[key] ?? ''));
+      if (value) {
+        limits.push(`--storage-opt=${key}=${value}`);
+      }
+    }
+  }
+
+  for (const ulimit of Array.isArray(h.Ulimits) ? h.Ulimits : []) {
+    if (ulimit && nonEmpty(ulimit.Name)) {
+      limits.push(`--ulimit=${ulimit.Name}=${ulimit.Soft}:${ulimit.Hard}`);
+    }
+  }
+
+  return limits;
+}
+
+/**
+ * Read a container's resource limits with `docker inspect`.
+ * @param {string} containerName - Container to inspect
+ * @param {Function} runner - `(command, args) => {success, stdout}`
+ * @returns {?string[]} Flags, or null when the container could not be read
+ */
+function readDockerResourceLimits(containerName, runner) {
+  let result;
+  try {
+    result = runner(getDockerCommand(), [
+      'inspect',
+      '--format',
+      '{{json .HostConfig}}',
+      containerName,
+    ]);
+  } catch {
+    return null;
+  }
+  if (!result || !result.success) {
+    return null;
+  }
+  try {
+    return parseDockerResourceLimits(JSON.parse(String(result.stdout).trim()));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize a stored `resourceLimits` value to a list of flags.
+ * @param {*} value - Value from an execution record or options object
+ * @returns {string[]} Flags
+ */
+function normalizeResourceLimits(value) {
+  if (Array.isArray(value)) {
+    return value.map(String).filter((flag) => flag.startsWith('--'));
+  }
+  if (typeof value === 'string' && value.trim() !== '') {
+    return value.split(/\s+/).filter((flag) => flag.startsWith('--'));
+  }
+  return [];
+}
+
+/**
+ * `[Isolation]` status line for resource limits, or null when there are none.
+ * @param {*} value - Stored `resourceLimits`
+ * @returns {?string} Status line
+ */
+function buildResourceLimitsStatusLine(value) {
+  const limits = normalizeResourceLimits(value);
+  return limits.length > 0
+    ? `[Isolation] Resource limits: ${limits.join(' ')}`
+    : null;
+}
+
+module.exports = {
+  DEFAULT_SHM_SIZE,
+  buildResourceLimitsStatusLine,
+  formatDockerBytes,
+  formatDockerCpus,
+  normalizeResourceLimits,
+  parseDockerResourceLimits,
+  readDockerResourceLimits,
+};

package/src/lib/docker-runtime-args.js

@@ -0,0 +1,141 @@
+/**
+ * Docker runtime options shared by `docker run`, `[Isolation]` status lines
+ * and execution-record metadata: privileged mode, environment, volumes,
+ * mounts, networks (issue #150) and resource limits (issue #176).
+ */
+
+const { getDockerNetworks } = require('./docker-network-lifecycle');
+const {
+  buildResourceLimitsStatusLine,
+  normalizeResourceLimits,
+} = require('./docker-resource-limits');
+
+/**
+ * Number of kill recoveries requested at launch; a recovery command on its own
+ * implies one (issue #176).
+ * @param {object} options - Options (onKillResume, recoveryCommand)
+ * @returns {?number} Attempt limit, or null when recovery is off
+ */
+function getOnKillResume(options = {}) {
+  const count = Number(options.onKillResume) || 0;
+  if (count > 0) {
+    return count;
+  }
+  return options.recoveryCommand ? 1 : null;
+}
+
+/**
+ * Build the docker run runtime argument list contributed by configurable
+ * container options: privileged mode, environment variables, volumes/bind
+ * mounts, --mount specs, network configuration and resource limits. Returned
+ * in a stable order so they can be spliced into the `docker run` argv before
+ * the image name.
+ * @param {object} options - Options (privileged, env, volumes, mounts, network, networkAliases, resourceLimits)
+ * @returns {string[]} Docker CLI arguments
+ */
+function buildDockerRuntimeArgs(options = {}) {
+  const args = [];
+  if (options.privileged) {
+    args.push('--privileged');
+  }
+  for (const envVar of options.env || []) {
+    args.push('-e', envVar);
+  }
+  for (const volume of options.volumes || []) {
+    args.push('-v', volume);
+  }
+  for (const mount of options.mounts || []) {
+    args.push('--mount', mount);
+  }
+  const [firstNetwork] = getDockerNetworks(options);
+  if (firstNetwork) {
+    args.push('--network', firstNetwork);
+  }
+  for (const alias of options.networkAliases || []) {
+    args.push('--network-alias', alias);
+  }
+  args.push(...normalizeResourceLimits(options.resourceLimits));
+  return args;
+}
+
+/**
+ * Build the human-readable `[Isolation]` status lines for docker runtime
+ * options (volumes, mounts, env, privileged, networks, resource limits and
+ * the launch-time recovery command). Empty collections and a falsy privileged
+ * flag contribute no lines.
+ * @param {object} options - Options (volumes, mounts, env, privileged, network, networks, networkAliases, resourceLimits, onKillResume, recoveryCommand)
+ * @returns {string[]} Status lines for the start block / log header
+ */
+function buildDockerRuntimeStatusLines(options = {}) {
+  const lines = [];
+  if (options.volumes && options.volumes.length > 0) {
+    lines.push(`[Isolation] Volumes: ${options.volumes.join(', ')}`);
+  }
+  if (options.mounts && options.mounts.length > 0) {
+    lines.push(`[Isolation] Mounts: ${options.mounts.join(', ')}`);
+  }
+  if (options.env && options.env.length > 0) {
+    lines.push(`[Isolation] Env: ${options.env.join(', ')}`);
+  }
+  if (options.privileged) {
+    lines.push(`[Isolation] Privileged: true`);
+  }
+  const networks = getDockerNetworks(options);
+  if (networks.length > 0) {
+    lines.push(`[Isolation] Network: ${networks[0]}`);
+  }
+  if (networks.length > 1) {
+    lines.push(`[Isolation] Networks: ${networks.join(', ')}`);
+  }
+  if (options.networkAliases && options.networkAliases.length > 0) {
+    lines.push(
+      `[Isolation] Network aliases: ${options.networkAliases.join(', ')}`
+    );
+  }
+  const limitsLine = buildResourceLimitsStatusLine(options.resourceLimits);
+  if (limitsLine) {
+    lines.push(limitsLine);
+  }
+  const onKillResume = getOnKillResume(options);
+  if (onKillResume) {
+    const what = options.recoveryCommand || 'the original command';
+    lines.push(
+      `[Isolation] On kill: resume up to ${onKillResume} time(s) with ${what}`
+    );
+  }
+  return lines;
+}
+
+/**
+ * Build the execution-record metadata for docker runtime options, normalizing
+ * empty collections and a falsy privileged flag to `null`.
+ * @param {object} options - Options (volumes, mounts, env, privileged, network, networks, networkAliases, resourceLimits, onKillResume, recoveryCommand)
+ * @returns {object} Record metadata
+ */
+function buildDockerRuntimeMetadata(options = {}) {
+  const networks = getDockerNetworks(options);
+  const resourceLimits = normalizeResourceLimits(options.resourceLimits);
+  return {
+    volumes:
+      options.volumes && options.volumes.length > 0 ? options.volumes : null,
+    mounts: options.mounts && options.mounts.length > 0 ? options.mounts : null,
+    env: options.env && options.env.length > 0 ? options.env : null,
+    privileged: options.privileged || null,
+    network: networks[0] || null,
+    networks: networks.length > 0 ? networks : null,
+    networkAliases:
+      options.networkAliases && options.networkAliases.length > 0
+        ? options.networkAliases
+        : null,
+    resourceLimits: resourceLimits.length > 0 ? resourceLimits : null,
+    onKillResume: getOnKillResume(options),
+    recoveryCommand: options.recoveryCommand || null,
+  };
+}
+
+module.exports = {
+  buildDockerRuntimeArgs,
+  buildDockerRuntimeStatusLines,
+  buildDockerRuntimeMetadata,
+  getOnKillResume,
+};

package/src/lib/execution-control.js

@@ -268,6 +268,40 @@ function formatControlResultAsLinksNotation(result) {
   return lines.join('\n');
 }
 
+/**
+ * Record that a stop was requested, for sessions with launch-time kill
+ * recovery (issue #176).
+ * @param {object} store - Execution store
+ * @param {object} record - Execution record
+ * @returns {string|undefined} The previous marker, to restore on failure
+ */
+function markStopRequested(store, record) {
+  const options = record.options || {};
+  if (!options.onKillResume) {
+    return undefined;
+  }
+  const previous = options.stopRequestedAt;
+  record.options = { ...options, stopRequestedAt: new Date().toISOString() };
+  try {
+    store.save(record);
+  } catch {
+    // Best effort: without the marker the session may be recovered once more.
+  }
+  return previous;
+}
+
+function restoreStopRequested(store, record, previous) {
+  if (!record.options || !record.options.onKillResume) {
+    return;
+  }
+  record.options = { ...record.options, stopRequestedAt: previous };
+  try {
+    store.save(record);
+  } catch {
+    // Best effort, see markStopRequested.
+  }
+}
+
 function controlExecution(store, identifier, action, runner = runCommand) {
   if (!store) {
     return { success: false, error: 'Execution tracking is disabled.' };
@@ -286,8 +320,13 @@ function controlExecution(store, identifier, action, runner = runCommand) {
     return { success: false, error: control.error };
   }
 
+  // A deliberate stop must not be mistaken for a kill that launch-time
+  // recovery should undo (issue #176): `docker stop` escalates to SIGKILL,
+  // which exits 137 just like the OOM killer.
+  const previousStopRequestedAt = markStopRequested(store, record);
   const result = runner(control.command, control.args);
   if (!result.success) {
+    restoreStopRequested(store, record, previousStopRequestedAt);
     const detail =
       result.stderr || result.error || `exit code ${result.status}`;
     return {