start-command 0.37.8 → 0.38.0

package/src/lib/execution-chain.js

@@ -0,0 +1,182 @@
+/**
+ * Continuation chains (issue #231): a launch with `--continues <id>` stores
+ * the UUID it continues, so a supervisor that relaunches fresh instead of
+ * `--resume`-ing in place can still treat every execution of one task as a
+ * whole. `--status` prints the chain and `--upload-log` uploads one file with
+ * every execution of it, oldest first.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { executionAliases, hasUserNames } = require('./execution-identity');
+
+/**
+ * UUIDs of the chain `record` belongs to, oldest first. Backward links come
+ * from `continues`; forward, the most recently started record that continues
+ * the current one is followed. Cycles stop the walk.
+ * @param {object[]} records - Stored records
+ * @param {object} record - Any member of the chain
+ * @returns {object[]} Records of the chain, oldest first
+ */
+function buildChain(records, record) {
+  const seen = new Set([record.uuid]);
+  const chain = [record];
+  for (let cur = record; cur.continues; ) {
+    const prev = records.find((r) => r.uuid === cur.continues);
+    if (!prev || seen.has(prev.uuid)) {
+      break;
+    }
+    seen.add(prev.uuid);
+    chain.unshift(prev);
+    cur = prev;
+  }
+  for (let cur = record; ; ) {
+    const next = records
+      .filter((r) => r.continues === cur.uuid && !seen.has(r.uuid))
+      .sort((a, b) => Date.parse(b.startTime) - Date.parse(a.startTime))[0];
+    if (!next) {
+      break;
+    }
+    seen.add(next.uuid);
+    chain.push(next);
+    cur = next;
+  }
+  return chain;
+}
+
+/**
+ * Resolve `--continues <id>` for a new launch to the UUID it stores.
+ * @param {object|null} store - ExecutionStore
+ * @param {string} identifier - Any name of the earlier execution
+ * @param {string} sessionId - UUID of the new launch
+ * @returns {string} UUID of the continued execution
+ * @throws {Error} When it cannot be resolved
+ */
+function resolveContinues(store, identifier, sessionId) {
+  if (!store) {
+    throw new Error('--continues requires execution tracking.');
+  }
+  const target = store.get(identifier);
+  if (!target) {
+    throw new Error(
+      `No execution found with UUID or session name: ${identifier}`
+    );
+  }
+  if (target.uuid === sessionId) {
+    throw new Error(`Execution ${sessionId} cannot continue itself`);
+  }
+  return target.uuid;
+}
+
+/**
+ * Wrap a status record so `toObject()` also reports the names it answers to
+ * (`aliases`, once `--alias`/`--rename` gave it one) and its continuation
+ * `chain`, right after `uuid`.
+ * @param {object} record - Record-like object with toObject()
+ * @param {object|null} store - ExecutionStore
+ * @returns {object} The record, or a wrapper with the extra fields
+ */
+function attachIdentity(record, store) {
+  const aliases = hasUserNames(record) ? executionAliases(record) : null;
+  const chain =
+    store &&
+    (record.continues ||
+      store.getAll().some((r) => r.continues === record.uuid))
+      ? buildChain(store.getAll(), record).map((r) => r.uuid)
+      : null;
+  if (!aliases && !(chain && chain.length > 1)) {
+    return record;
+  }
+  const wrapped = Object.create(Object.getPrototypeOf(record));
+  Object.assign(wrapped, record);
+  const source = record.toObject.bind(record);
+  wrapped.toObject = function () {
+    const ordered = {};
+    for (const [key, value] of Object.entries(source())) {
+      ordered[key] = value;
+      if (key === 'uuid') {
+        if (aliases) {
+          ordered.aliases = aliases;
+        }
+        if (chain && chain.length > 1) {
+          ordered.chain = chain;
+        }
+      }
+    }
+    return ordered;
+  };
+  return wrapped;
+}
+
+/**
+ * Text-format lines for the identity fields of a status object.
+ * @param {object} obj - Output of toObject()
+ * @returns {string[]} Lines
+ */
+function identityTextLines(obj) {
+  return [
+    ...(obj.aliases ? [`Aliases:           ${obj.aliases.join(', ')}`] : []),
+    ...(obj.continues ? [`Continues:         ${obj.continues}`] : []),
+    ...(obj.chain ? [`Chain:             ${obj.chain.join(' -> ')}`] : []),
+  ];
+}
+
+/**
+ * Concatenate the logs of a chain into one temporary file, oldest first,
+ * each preceded by a lifecycle header in the format `--resume` writes.
+ * @param {object[]} chain - Records, oldest first
+ * @returns {{path: string, cleanup: Function}} Combined log
+ */
+function writeChainLog(chain) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-chain-log-'));
+  const file = path.join(dir, `${chain[chain.length - 1].uuid}.chain.log`);
+  chain.forEach((record, index) => {
+    const header = {
+      event: 'continuation',
+      uuid: record.uuid,
+      chainIndex: index + 1,
+      chainLength: chain.length,
+      continues: record.continues || null,
+      command: record.command,
+      startTime: record.startTime,
+      logPath: record.logPath || null,
+    };
+    fs.appendFileSync(
+      file,
+      `\n[Start Command Lifecycle] ${JSON.stringify(header)}\n`
+    );
+    if (record.logPath && fs.existsSync(record.logPath)) {
+      fs.appendFileSync(file, fs.readFileSync(record.logPath));
+    } else {
+      fs.appendFileSync(file, `Log file not found: ${record.logPath}\n`);
+    }
+  });
+  return {
+    path: file,
+    cleanup: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * Log path `--upload-log` should upload for `record`: its own log, or a
+ * combined log when it belongs to a chain of more than one execution.
+ * @param {object} store - ExecutionStore
+ * @param {object} record - Resolved record
+ * @returns {{path: string, cleanup: Function}} Log to upload
+ */
+function prepareUploadLog(store, record) {
+  const chain = buildChain(store.getAll(), record);
+  if (chain.length < 2) {
+    return { path: record.logPath, cleanup: () => {} };
+  }
+  return writeChainLog(chain);
+}
+
+module.exports = {
+  attachIdentity,
+  buildChain,
+  identityTextLines,
+  prepareUploadLog,
+  resolveContinues,
+  writeChainLog,
+};

package/src/lib/execution-cleanup.js

@@ -0,0 +1,193 @@
+/**
+ * `$ --cleanup <uuid-or-session-name>` (issue #224): remove the Docker
+ * containers of one execution and the snapshot images they were derived from.
+ *
+ * For callers that remove containers themselves: start-command's completion
+ * watcher removes a snapshot image only when it removes the container. Nothing
+ * here is forced, so Docker keeps any container that is still running and any
+ * image that something else still uses; those are reported as retained.
+ *
+ * The containers are the current one and every earlier container of a
+ * `--resume` chain (`sessionNameHistory`). The images are the
+ * `start-command-resume/*` images named by the `start-command.snapshot-image`
+ * label of those containers, by the record, and by the `-resume-N` names of
+ * the chain, removed newest first.
+ */
+const { getDockerCommand } = require('./docker-cleanup');
+const { runCommand } = require('./execution-control');
+const { SNAPSHOT_IMAGE_LABEL } = require('./docker-snapshot-safety');
+
+const SNAPSHOT_IMAGE_PATTERN = /^start-command-resume\/[a-z0-9._-]+:\d+$/;
+const NOT_FOUND_PATTERN = /no such (container|image|object)/i;
+
+/** Docker image name for snapshot attempt `attempt` of `sessionName`. */
+function snapshotImageName(sessionName, attempt) {
+  const { buildSnapshotImageName } = require('./execution-resume');
+  return buildSnapshotImageName(sessionName, attempt);
+}
+
+/** Snapshot images implied by a `<name>-resume-<N>` chain, newest first. */
+function chainImages(containerName) {
+  const images = [];
+  let current = String(containerName || '');
+  for (
+    let match = /^(.+)-resume-(\d+)$/.exec(current);
+    match;
+    match = /^(.+)-resume-(\d+)$/.exec(current)
+  ) {
+    images.push(snapshotImageName(match[1], match[2]));
+    current = match[1];
+  }
+  return images;
+}
+
+function attemptOf(image) {
+  return Number(/:(\d+)$/.exec(image)?.[1] || 0);
+}
+
+function errorText(result) {
+  return (
+    String(result?.stderr || '').trim() ||
+    result?.error ||
+    `exit code ${result?.status}`
+  );
+}
+
+/**
+ * The containers and images `--cleanup <execution>` would remove.
+ * @param {object} record - Execution record
+ * @param {Function} runner - Sync command runner
+ * @returns {{containers: string[], images: string[]}}
+ */
+function planExecutionCleanup(record, runner) {
+  const options = record.options || {};
+  const current = options.sessionName || options.containerId || null;
+  const containers = [
+    ...new Set(
+      [current, ...[...(options.sessionNameHistory || [])].reverse()].filter(
+        Boolean
+      )
+    ),
+  ];
+  const images = [options.snapshotImage];
+  for (const container of containers) {
+    const labelled = runner(getDockerCommand(), [
+      'inspect',
+      '-f',
+      `{{index .Config.Labels "${SNAPSHOT_IMAGE_LABEL}"}}`,
+      container,
+    ]);
+    if (labelled.success) {
+      images.push(String(labelled.stdout || '').trim());
+    }
+    images.push(...chainImages(container));
+  }
+  return {
+    containers,
+    images: [...new Set(images)]
+      .filter((image) => SNAPSHOT_IMAGE_PATTERN.test(image || ''))
+      .sort((a, b) => attemptOf(b) - attemptOf(a)),
+  };
+}
+
+/**
+ * Remove (or, with `dryRun`, list) one object without force.
+ * @returns {{name: string, kind: string, state: string, detail?: string}}
+ *   `state` is removed, absent, retained or present (dry run)
+ */
+function removeObject(kind, name, runner, dryRun) {
+  const docker = getDockerCommand();
+  const args = dryRun
+    ? kind === 'image'
+      ? ['image', 'inspect', '--format', '{{.Id}}', name]
+      : ['container', 'inspect', '--format', '{{.Id}}', name]
+    : kind === 'image'
+      ? ['rmi', name]
+      : ['rm', name];
+  const result = runner(docker, args);
+  if (result.success) {
+    return { kind, name, state: dryRun ? 'present' : 'removed' };
+  }
+  const detail = errorText(result);
+  if (!result.error && NOT_FOUND_PATTERN.test(detail)) {
+    return { kind, name, state: 'absent' };
+  }
+  return { kind, name, state: 'retained', detail };
+}
+
+const LABELS = {
+  removed: 'Removed',
+  absent: 'Already gone:',
+  retained: 'Retained',
+  present: 'Would remove',
+};
+
+function formatOutcome(outcome) {
+  const line = `${LABELS[outcome.state]} ${outcome.kind} ${outcome.name}`;
+  return outcome.detail ? `${line} (${outcome.detail})` : line;
+}
+
+/**
+ * Remove one execution's containers, then its snapshot images.
+ * @param {?object} store - Execution store
+ * @param {string} identifier - UUID or session name
+ * @param {object} [deps] - {dryRun, runner}
+ * @returns {{success: boolean, output?: string, error?: string}}
+ */
+function cleanupExecution(store, identifier, deps = {}) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+  const record = store.get(identifier);
+  if (!record) {
+    return {
+      success: false,
+      error: `No execution found with UUID or session name: ${identifier}`,
+    };
+  }
+  if (record.options?.isolated !== 'docker') {
+    return {
+      success: false,
+      error: `--cleanup <execution> only removes Docker containers and images; ${identifier} is not a Docker execution.`,
+    };
+  }
+  const runner = deps.runner || runCommand;
+  const dryRun = deps.dryRun === true;
+  const plan = planExecutionCleanup(record, runner);
+  const outcomes = plan.containers.map((name) =>
+    removeObject('container', name, runner, dryRun)
+  );
+  // Images go only after their containers; Docker refuses a used image.
+  for (const image of plan.images) {
+    outcomes.push(removeObject('image', image, runner, dryRun));
+  }
+  const current = outcomes[0];
+  if (
+    !dryRun &&
+    current &&
+    ['removed', 'absent'].includes(current.state) &&
+    typeof store.markContainerRemoved === 'function'
+  ) {
+    store.markContainerRemoved(record.uuid, new Date().toISOString());
+  }
+  const retained = outcomes.filter((outcome) => outcome.state === 'retained');
+  const lines = outcomes.length
+    ? outcomes.map(formatOutcome)
+    : ['No containers or snapshot images recorded for this execution.'];
+  const output = lines.join('\n');
+  if (retained.length > 0) {
+    return {
+      success: false,
+      output,
+      error: `${retained.length} Docker object(s) retained; nothing was forced.`,
+    };
+  }
+  return { success: true, output };
+}
+
+module.exports = {
+  SNAPSHOT_IMAGE_PATTERN,
+  chainImages,
+  cleanupExecution,
+  planExecutionCleanup,
+};

package/src/lib/execution-control.js

@@ -17,10 +17,11 @@ const ControlAction = {
   TERMINATE: 'terminate',
 };
 
-function runCommand(command, args) {
+function runCommand(command, args, extra = {}) {
   const options = {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
+    ...(extra.timeout ? { timeout: extra.timeout } : {}),
   };
   const result = spawnSync(
     command,

package/src/lib/execution-env.js

@@ -0,0 +1,120 @@
+/**
+ * START_* variables that tell a launched command which execution it belongs
+ * to (issue #230). Every backend exports the same three variables, next to
+ * the kill-recovery `START_COMMAND_RECOVERY_ATTEMPT`:
+ *
+ * - START_EXECUTION_ID: the execution UUID (`--session-id`)
+ * - START_SESSION_NAME: the isolation session/container name (`--session`);
+ *   empty for direct runs, which have no session
+ * - START_ATTEMPT: 1 for the first run, n for the n-th attempt (`--resume`,
+ *   kill recovery or `--append-attempt`), the same number `--status` shows
+ */
+const { shellQuote } = require('./isolation-log-utils');
+
+const EXECUTION_ID_ENV = 'START_EXECUTION_ID';
+const SESSION_NAME_ENV = 'START_SESSION_NAME';
+const ATTEMPT_ENV = 'START_ATTEMPT';
+
+/**
+ * Build the START_* variables for one attempt.
+ * @param {object} params - {executionId, sessionName, attempt}
+ * @returns {object} Variables in a stable order, or {} without an execution id
+ */
+function buildExecutionEnv({ executionId, sessionName, attempt } = {}) {
+  if (!executionId) {
+    return {};
+  }
+  const number = Number(attempt);
+  return {
+    [EXECUTION_ID_ENV]: String(executionId),
+    [SESSION_NAME_ENV]: sessionName ? String(sessionName) : '',
+    [ATTEMPT_ENV]: String(
+      Number.isSafeInteger(number) && number > 0 ? number : 1
+    ),
+  };
+}
+
+/**
+ * Build the variables from isolation options (`runIsolated`, `docker run`).
+ * @param {object} options - {sessionId|executionId, containerName|session, attemptNumber}
+ * @returns {object} Variables, or {}
+ */
+function executionEnvFromOptions(options = {}) {
+  return buildExecutionEnv({
+    executionId: options.sessionId || options.executionId,
+    sessionName: options.containerName || options.session,
+    attempt: options.attemptNumber,
+  });
+}
+
+/**
+ * `KEY=value` assignments, e.g. for `docker run -e`.
+ * @param {object} env - Variables
+ * @returns {string[]} Assignments
+ */
+function executionEnvAssignments(env = {}) {
+  return Object.entries(env).map(([key, value]) => `${key}=${value}`);
+}
+
+/**
+ * POSIX `export` statement for the variables, without a trailing separator.
+ * @param {object} env - Variables
+ * @returns {string} Statement, or '' when there is nothing to export
+ */
+function buildExecutionEnvExport(env = {}) {
+  const entries = Object.entries(env);
+  if (!entries.length) {
+    return '';
+  }
+  return `export ${entries
+    .map(([key, value]) => `${key}=${shellQuote(value)}`)
+    .join(' ')}`;
+}
+
+/**
+ * Prefix a shell command with the export statement. Used by the backends
+ * whose command runs through a shell that does not inherit our environment:
+ * a running tmux server, ssh, and `sudo` (which resets the environment).
+ * @param {string} command - Shell command
+ * @param {object} env - Variables
+ * @returns {string} Prefixed command
+ */
+function prefixWithExecutionEnv(command, env = {}) {
+  const statement = buildExecutionEnvExport(env);
+  return statement ? `${statement}; ${command}` : command;
+}
+
+/**
+ * Child-process environment with the variables applied.
+ * @param {object} env - Variables
+ * @param {object} [base] - Base environment (defaults to process.env)
+ * @returns {object} Environment
+ */
+function withExecutionEnv(env = {}, base = process.env) {
+  return { ...base, ...env };
+}
+
+/**
+ * True when this process was itself started by execution `executionId`, i.e.
+ * it is the next level of a stacked isolation that passes `--session-id`
+ * down (see command-builder.js).
+ * @param {string} executionId - Execution UUID
+ * @param {object} [env] - Environment to inspect
+ * @returns {boolean}
+ */
+function isNestedLaunchOf(executionId, env = process.env) {
+  return Boolean(executionId) && env[EXECUTION_ID_ENV] === executionId;
+}
+
+module.exports = {
+  EXECUTION_ID_ENV,
+  SESSION_NAME_ENV,
+  ATTEMPT_ENV,
+  buildExecutionEnv,
+  executionEnvFromOptions,
+  executionEnvAssignments,
+  buildExecutionEnvExport,
+  prefixWithExecutionEnv,
+  withExecutionEnv,
+  isNestedLaunchOf,
+};

package/src/lib/execution-identity.js

@@ -0,0 +1,180 @@
+/**
+ * Names an execution answers to (issue #231).
+ *
+ * An execution is found by its UUID, its backend session name, the session
+ * names it used before a resume (`options.sessionNameHistory`, #162), its
+ * display name (`options.name`, set by `--rename`) and its aliases
+ * (`options.aliases`, added by `--alias` and `--rename`). Aliases are kept
+ * apart from `sessionNameHistory` because that list names real backend
+ * sessions: `--cleanup` removes those containers and `--resume` derives the
+ * root session from it.
+ */
+
+function hasName(record, identifier) {
+  const options = record.options || {};
+  return (
+    options.name === identifier ||
+    (Array.isArray(options.aliases) && options.aliases.includes(identifier))
+  );
+}
+
+/**
+ * Resolve an identifier among stored records: UUID, then current session
+ * name, then earlier session names, then display name and aliases.
+ * @param {object[]} records - Stored records
+ * @param {string} identifier - Any name of the execution
+ * @returns {object|null} The record, or null
+ */
+function findRecord(records, identifier) {
+  if (identifier === null || identifier === undefined || identifier === '') {
+    return null;
+  }
+  return (
+    records.find((r) => r.uuid === identifier) ||
+    records.find((r) => r.options && r.options.sessionName === identifier) ||
+    records.find(
+      (r) =>
+        r.options &&
+        Array.isArray(r.options.sessionNameHistory) &&
+        r.options.sessionNameHistory.includes(identifier)
+    ) ||
+    records.find((r) => hasName(r, identifier)) ||
+    null
+  );
+}
+
+/**
+ * Every name the record answers to, UUID first, without duplicates.
+ * @param {object} record - Execution record
+ * @returns {string[]} Names
+ */
+function executionAliases(record) {
+  const options = record.options || {};
+  const names = [
+    record.uuid,
+    ...(options.sessionNameHistory || []),
+    options.sessionName,
+    ...(options.aliases || []),
+    options.name,
+  ].filter((name) => typeof name === 'string' && name);
+  return [...new Set(names)];
+}
+
+/** True once the record has a caller-given name (`--alias`/`--rename`). */
+function hasUserNames(record) {
+  const options = record.options || {};
+  return Boolean(options.name) || (options.aliases || []).length > 0;
+}
+
+/**
+ * Run `mutate(records)` under the store's database lock and persist the
+ * records it returns as changed.
+ * @param {object} store - ExecutionStore
+ * @param {Function} mutate - (records) => changed record, or null for none
+ * @returns {*} What `mutate` returned
+ */
+function withStoreLock(store, mutate) {
+  const { LockManager } = require('./execution-store');
+  const lock = new LockManager(store.lockFilePath);
+  if (!lock.acquire()) {
+    throw new Error('Failed to acquire lock for database write');
+  }
+  try {
+    const records = store.readLinoRecords();
+    const changed = mutate(records);
+    if (changed) {
+      store.writeLinoRecords(records);
+      if (store.useLinks) {
+        store.writeLinksRecord(changed);
+      }
+    }
+    return changed;
+  } finally {
+    lock.release();
+  }
+}
+
+function validateName(name) {
+  if (typeof name !== 'string' || !name.trim()) {
+    throw new Error('The new name must not be empty');
+  }
+  if (name.startsWith('-')) {
+    throw new Error(`Invalid name "${name}": names cannot start with "-"`);
+  }
+}
+
+/**
+ * Add a name to an execution (`$ --alias <id> <name>`) or rename it
+ * (`$ --rename <id> <name>`, which keeps the previous display name as an
+ * alias). The backend session/container keeps its name; only lookup and the
+ * displayed name change.
+ * @param {object} store - ExecutionStore
+ * @param {string} identifier - Any current name of the execution
+ * @param {string} name - Name to add
+ * @param {object} [options] - {rename: boolean}
+ * @returns {{success: boolean, output?: string, error?: string}}
+ */
+function nameExecution(store, identifier, name, options = {}) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+  try {
+    validateName(name);
+    let unchanged = false;
+    const record = withStoreLock(store, (records) => {
+      const target = findRecord(records, identifier);
+      if (!target) {
+        throw new Error(
+          `No execution found with UUID or session name: ${identifier}`
+        );
+      }
+      const owner = findRecord(records, name);
+      if (owner && owner.uuid !== target.uuid) {
+        throw new Error(
+          `Name "${name}" already refers to execution ${owner.uuid}`
+        );
+      }
+      const opts = (target.options = target.options || {});
+      const aliases = [...(opts.aliases || [])];
+      if (options.rename) {
+        const previous = opts.name || opts.sessionName || target.uuid;
+        if (previous === name) {
+          unchanged = true;
+          return null;
+        }
+        // A session name or UUID still resolves on its own; an earlier
+        // display name has to become an alias to keep resolving.
+        if (opts.name) {
+          aliases.push(previous);
+        }
+        opts.name = name;
+      } else if (owner) {
+        unchanged = true;
+        return null;
+      } else {
+        aliases.push(name);
+      }
+      opts.aliases = [...new Set(aliases)].filter((a) => a !== opts.name);
+      if (opts.aliases.length === 0) {
+        delete opts.aliases;
+      }
+      return target;
+    });
+    const current = record || store.get(identifier);
+    const action = options.rename ? 'Renamed' : 'Aliased';
+    return {
+      success: true,
+      output: `${unchanged ? 'Unchanged' : action} execution ${current.uuid}\naliases: [${executionAliases(current).join(', ')}]`,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+module.exports = {
+  executionAliases,
+  findRecord,
+  hasUserNames,
+  nameExecution,
+  withStoreLock,
+};