start-command 0.37.9 → 0.39.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-control.js

@@ -11,6 +11,7 @@ const {
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
 const { getDockerCommand, getDockerSpawnOptions } = require('./docker-cleanup');
+const { prefetchedInspect } = require('./docker-inspect-batch');
 
 const ControlAction = {
   STOP: 'stop',
@@ -148,14 +149,15 @@ function collectProcessIds(record, runner = runCommand) {
       ),
     ];
     addIfPresent(processIds, 'commandPids', commandPids);
+  } else if (isolated === 'docker' && record.containerState === 'removed') {
+    // The container is gone, so there is nothing to ask Docker (#243).
+    addIfPresent(processIds, 'containerId', opts.containerId);
   } else if (isolated === 'docker') {
     addIfPresent(processIds, 'containerId', opts.containerId);
-    const result = runner(getDockerCommand(), [
-      'inspect',
-      '-f',
-      '{{.Id}} {{.State.Pid}}',
-      sessionName,
-    ]);
+    const format = '{{.Id}} {{.State.Pid}}';
+    const result =
+      prefetchedInspect(format, sessionName) ||
+      runner(getDockerCommand(), ['inspect', '-f', format, sessionName]);
     if (result.success && result.stdout.trim()) {
       const [containerId, pidValue] = result.stdout.trim().split(/\s+/);
       addIfPresent(processIds, 'containerId', containerId);

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,
+};

package/src/lib/execution-recovery.js

@@ -336,6 +336,7 @@ function recoverKilledExecution(params = {}) {
   record.options.exitEvidence = {
     mainOom: terminalOom,
     daemonRestart: logged.daemonRestart,
+    ...evidence.sourceOf(logged),
   };
   let recoveryLimits = null;
   if (opts.onKillResumeMemory && terminalOom) {
@@ -379,6 +380,23 @@ function recoverKilledExecution(params = {}) {
     }
   }
 
+  if (opts.commandHandoff && record.uuid) {
+    // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+    try {
+      require('./docker-command-handoff').writeExecutionEnvHandoff(
+        containerName,
+        require('./execution-env').buildExecutionEnv({
+          executionId: record.uuid,
+          sessionName: containerName,
+          attempt: require('./execution-attempt').nextAttemptNumber(record),
+        }),
+        runner
+      );
+    } catch {
+      // Non-fatal: the command still runs, with the previous START_ATTEMPT.
+    }
+  }
+
   const since = now().toISOString();
   const {
     appendLifecycle,
@@ -473,7 +491,9 @@ function recoverKilledExecution(params = {}) {
     const updated = runner(getDockerCommand(), [
       'update',
       ...resourceLimits.filter((s) =>
-        /^--(?:memory|memory-swap|cpus|cpu-quota|cpu-period)=/.test(s)
+        /^--(?:memory|memory-swap|memory-reservation|cpus|cpu-quota|cpu-period)=/.test(
+          s
+        )
       ),
       containerName,
     ]);

package/src/lib/execution-resume.js

@@ -34,6 +34,7 @@ const {
   appendLifecycle,
   archiveAttempt,
   createAttempt,
+  nextAttemptNumber,
   patchAttempt,
 } = require('./execution-attempt');
 const { runCommand } = require('./execution-control');
@@ -46,6 +47,7 @@ const { SessionState, probeSession } = require('./session-probe');
 const { getDockerNetworks } = require('./docker-network-lifecycle');
 const {
   writeCommandHandoff,
+  writeExecutionEnvHandoff,
   buildCommandHandoffArgs,
   commandHandoffPath,
 } = require('./docker-command-handoff');
@@ -110,6 +112,8 @@ function buildLaunchOptions(record) {
     rootSession:
       opts.rootSession || opts.sessionNameHistory?.[0] || opts.sessionName,
     resumeCount: (Number(opts.resumeCount) || 0) + 1,
+    // START_ATTEMPT of the relaunched command (issue #230).
+    attemptNumber: nextAttemptNumber(record),
     image: opts.image || null,
     session: opts.sessionName,
     detached: true,
@@ -123,6 +127,7 @@ function buildLaunchOptions(record) {
     useCommandStream: opts.useCommandStream || false,
     shell: opts.shell || 'auto',
     privileged: opts.privileged || false,
+    init: opts.init || false,
     env: opts.env || [],
     volumes: opts.volumes || [],
     mounts: opts.mounts || [],
@@ -289,6 +294,7 @@ function buildResumePlan(
               session: newSessionName,
               containerName: newSessionName,
               sessionId: record.uuid,
+              attemptNumber: nextAttemptNumber(record),
               rootSession:
                 opts.rootSession || opts.sessionNameHistory?.[0] || sessionName,
               resumeCount: attempt,
@@ -530,7 +536,9 @@ async function resumeExecution(store, identifier, deps = {}) {
         args: [
           'update',
           ...resources.resourceLimits.filter((s) =>
-            /^--(?:memory|memory-swap|cpus|cpu-quota|cpu-period)=/.test(s)
+            /^--(?:memory|memory-swap|memory-reservation|cpus|cpu-quota|cpu-period)=/.test(
+              s
+            )
           ),
           plan.sessionName,
         ],
@@ -657,6 +665,18 @@ async function resumeExecution(store, identifier, deps = {}) {
           );
         }
       }
+      if (plan.mode === ResumeMode.DOCKER_START && opts.commandHandoff) {
+        // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+        writeExecutionEnvHandoff(
+          plan.sessionName,
+          require('./execution-env').buildExecutionEnv({
+            executionId: record.uuid,
+            sessionName: plan.sessionName,
+            attempt: attempt.number,
+          }),
+          runner
+        );
+      }
       for (const step of plan.steps) {
         let result;
         try {