dsh-autorestart 0.7.0 → 0.8.1

package/lib/scheduler-capability.js

@@ -0,0 +1,300 @@
+/**
+ * CAN THIS MACHINE CREATE A ONE-OFF SCHEDULED TASK?
+ *
+ * The automatic rollback of this plugin works through a scheduled task: the
+ * host is restarted, and a task that fires a minute later brings it back if
+ * it did not come up. On a machine where such a task cannot be created
+ * (a corporate policy, a machine without the rights, a locked-down service
+ * account) that safety net is silently missing — and the user has to be told
+ * what they lose.
+ *
+ * WHAT THIS DOES NOT DO (on purpose):
+ *
+ *   - it does NOT design a fallback chain ("use the startup folder instead",
+ *     "use a systemd timer instead", ...): the user decided against it;
+ *   - it does NOT try to bypass the policy ("maybe another way works"): if
+ *     the machine says no, the answer is no.
+ *
+ * It only DETECTS, once, and tells the truth.
+ *
+ * THE PROBE NEVER LEAVES A TASK BEHIND:
+ *
+ *   1. a task with a unique name is registered (it fires in two minutes and
+ *      does nothing: `cmd /c exit 0`);
+ *   2. it is read back and verified (the trigger is the one we asked for);
+ *   3. it is deleted;
+ *   4. it is read back AGAIN — the task must be gone.
+ *
+ * The verification is the XML of the task, not its human readable listing:
+ * the XML has no translated words, so the check does not depend on the
+ * language of the machine ("Ready" in English, "就绪" in Chinese).
+ *
+ * Everything that touches the system is injected, so a test never has to
+ * create a real task.
+ */
+
+import { execFileSync } from 'node:child_process';
+
+/** The scheduler works on this machine. */
+export const SCHEDULER_OK = 'ok';
+/** The scheduler is refused here — the automatic rollback is not available. */
+export const SCHEDULER_BLOCKED = 'blocked';
+/** Nobody checked yet. */
+export const SCHEDULER_UNKNOWN = 'unknown';
+
+/** The name of the probe task. It is unique per run, so two probes cannot collide. */
+export const PROBE_TASK_PREFIX = 'dsh-autorestart-capability-probe';
+
+/**
+ * The name of the probe task for this run.
+ *
+ * @param {number} now
+ * @param {number|string} pid
+ * @returns {string}
+ */
+export function probeTaskName(now = Date.now(), pid = 0) {
+  const stamp = Math.trunc(Number(now) || 0).toString(36);
+  const who = String(pid === 0 ? '0' : pid).replace(/[^A-Za-z0-9]/g, '');
+  return `${PROBE_TASK_PREFIX}-${who}-${stamp}`;
+}
+
+/**
+ * The trigger of the probe: two minutes from now, in the formats schtasks
+ * wants and in the format the XML reports.
+ *
+ * @param {number} now
+ * @returns {{ sd: string, st: string, iso: string }}
+ */
+export function probeTrigger(now = Date.now()) {
+  const date = new Date(Math.trunc(Number(now) || 0) + 2 * 60 * 1000);
+  const pad = (value) => String(value).padStart(2, '0');
+  const yyyy = date.getFullYear();
+  const mm = pad(date.getMonth() + 1);
+  const dd = pad(date.getDate());
+  const hh = pad(date.getHours());
+  const mi = pad(date.getMinutes());
+  return { sd: `${yyyy}/${mm}/${dd}`, st: `${hh}:${mi}`, iso: `${yyyy}-${mm}-${dd}T${hh}:${mi}` };
+}
+
+/**
+ * The default executor: run a command and report what it said.
+ *
+ * @param {string} file
+ * @param {string[]} args
+ * @returns {{ ok: boolean, stdout: string, error: string|null }}
+ */
+function defaultExec(file, args) {
+  try {
+    const stdout = execFileSync(file, args, { encoding: 'utf8', timeout: 20000, windowsHide: true });
+    return { ok: true, stdout: typeof stdout === 'string' ? stdout : '', error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: error && typeof error.stdout === 'string' ? error.stdout : '',
+      error: error && error.message ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * The trigger of the task, read out of its XML.
+ *
+ * @param {string} xml
+ * @returns {string} the ISO start boundary, or an empty string
+ */
+export function readStartBoundary(xml) {
+  const text = typeof xml === 'string' ? xml : '';
+  const match = /<StartBoundary>([^<]+)<\/StartBoundary>/i.exec(text);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * The trigger of the task, read out of its XML, compared with what we asked
+ * for (the XML writes seconds, we asked without them).
+ *
+ * @param {string} xml
+ * @param {string} expectedIso
+ * @returns {boolean}
+ */
+export function triggerMatches(xml, expectedIso) {
+  const boundary = readStartBoundary(xml);
+  if (boundary === '') return false;
+  return boundary.slice(0, 16) === String(expectedIso).slice(0, 16);
+}
+
+/**
+ * Would the task fire?
+ *
+ * The XML does NOT always carry an `<Enabled>` element: a task without one is
+ * enabled (that is the default), and only an explicit `false` disables it.
+ * (A real run on a Chinese Windows answered with a `<TimeTrigger>` that has
+ * no `<Enabled>` at all — a check that demanded `<Enabled>true</Enabled>` would
+ * have called a perfectly working machine "blocked".)
+ *
+ * @param {string} xml
+ * @returns {boolean}
+ */
+export function taskEnabled(xml) {
+  const text = typeof xml === 'string' ? xml : '';
+  return !/<Enabled>false<\/Enabled>/i.test(text);
+}
+
+/**
+ * Does the task carry an action (is it a real one-off task)?
+ *
+ * @param {string} xml
+ * @returns {boolean}
+ */
+export function taskHasAction(xml) {
+  const text = typeof xml === 'string' ? xml : '';
+  return /<Command>/i.test(text);
+}
+
+/**
+ * THE PROBE.
+ *
+ * @param {{
+ *   platform?: string,
+ *   exec?: (file: string, args: string[]) => { ok: boolean, stdout: string, error: string|null },
+ *   now?: number,
+ *   taskName?: string,
+ *   pid?: number|string,
+ * }} [options]
+ * @returns {{ scheduler: string, checkedAt: number, evidence: object }}
+ */
+export function probeSchedulerCapability({
+  platform = process.platform,
+  exec = defaultExec,
+  now = Date.now(),
+  taskName = probeTaskName(now, process.pid),
+  pid = process.pid,
+} = {}) {
+  const checkedAt = Math.trunc(Number(now) || Date.now());
+  const evidence = { platform, taskName, steps: [] };
+
+  // Only Windows uses a one-off scheduled task. Everywhere else the question
+  // does not apply (the advice for those platforms is elsewhere).
+  if (platform !== 'win32') {
+    return {
+      scheduler: SCHEDULER_OK,
+      checkedAt,
+      evidence: {
+        ...evidence,
+        applicable: false,
+        note: 'not applicable: this platform does not use a one-off scheduled task',
+      },
+    };
+  }
+
+  const trigger = probeTrigger(checkedAt);
+  const step = (kind, ok, detail) => {
+    evidence.steps.push({ kind, ok, detail: detail === undefined ? null : detail });
+    return ok;
+  };
+
+  // (0) Idempotence: a task of an earlier run (or of another instance) must
+  //     not be in the way.
+  const preClean = exec('schtasks', ['/Delete', '/TN', taskName, '/F']);
+  step('pre-clean', true, preClean.ok ? 'deleted a leftover probe task' : 'no leftover probe task');
+
+  try {
+    // (1) Register the probe task: it fires in two minutes and does nothing.
+    const created = exec('schtasks', [
+      '/Create', '/TN', taskName, '/SC', 'ONCE', '/SD', trigger.sd, '/ST', trigger.st,
+      '/TR', 'cmd /c exit 0', '/F',
+    ]);
+    if (!step('create', created.ok, created.ok ? 'the task was registered' : created.error)) {
+      return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+    }
+
+    // (2) Read it back: the trigger must be the one we asked for, and the
+    //     task must be enabled (that is what "Ready" means in the XML).
+    const query = exec('schtasks', ['/Query', '/TN', taskName, '/XML']);
+    if (!step('verify', query.ok, query.ok ? 'the task was read back' : query.error)) {
+      return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+    }
+    if (!step('trigger', triggerMatches(query.stdout, trigger.iso), 'expected ' + trigger.iso + ', got ' + readStartBoundary(query.stdout))) {
+      return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+    }
+    if (!step('enabled', taskEnabled(query.stdout), 'the task would fire')) {
+      return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+    }
+    if (!step('action', taskHasAction(query.stdout), 'the task carries an action')) {
+      return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+    }
+  } catch (error) {
+    step('error', false, error && error.message ? error.message : String(error));
+    return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+  } finally {
+    // (3) Delete it — ALWAYS, also when a step above failed. A registration
+    //     that was refused can still have left a task behind (the command may
+    //     have created it and then failed), so the cleanup is not conditional.
+    const removed = exec('schtasks', ['/Delete', '/TN', taskName, '/F']);
+    step('delete', removed.ok, removed.ok ? 'the probe task was deleted' : removed.error);
+  }
+
+  // (4) Read it back once more: it must be GONE. A task that survives the
+  //     probe is a task the user would find in his task scheduler.
+  const after = exec('schtasks', ['/Query', '/TN', taskName, '/XML']);
+  const gone = !after.ok;
+  step('gone', gone, gone ? 'the task is gone' : 'the task still exists: ' + after.error);
+  if (!gone) {
+    return { scheduler: SCHEDULER_BLOCKED, checkedAt, evidence };
+  }
+
+  return { scheduler: SCHEDULER_OK, checkedAt, evidence };
+}
+
+/**
+ * Must the user be warned now?
+ *
+ * The warning is for ONE moment: the transition into "blocked". A machine
+ * that was blocked and stays blocked does not nag, and a user who has seen it
+ * is not asked again.
+ *
+ * @param {object|null} previous the capabilities before the check
+ * @param {object|null} current the capabilities after the check
+ * @returns {boolean}
+ */
+export function shouldWarnScheduler(previous, current) {
+  if (!current || typeof current !== 'object') return false;
+  if (current.scheduler !== SCHEDULER_BLOCKED) return false;
+  if (current.warnedAt) return false;
+  const before = previous && typeof previous === 'object' ? previous.scheduler : SCHEDULER_UNKNOWN;
+  // Only the TRANSITION warns: from ok or unknown into blocked.
+  return before !== SCHEDULER_BLOCKED;
+}
+
+/**
+ * The capabilities with the warning marked as seen.
+ *
+ * @param {object} capabilities
+ * @param {number} [now]
+ * @returns {object}
+ */
+export function markSchedulerWarned(capabilities, now = Date.now()) {
+  const record = capabilities && typeof capabilities === 'object' ? capabilities : {};
+  if (record.warnedAt) return record;
+  return { ...record, warnedAt: Math.trunc(Number(now) || Date.now()) };
+}
+
+/**
+ * A capabilities record that says nothing yet.
+ *
+ * @returns {{ scheduler: string, checkedAt: number|null, evidence: object|null, warnedAt: number|null }}
+ */
+export function emptyCapabilities() {
+  return { scheduler: SCHEDULER_UNKNOWN, checkedAt: null, evidence: null, warnedAt: null };
+}
+
+/**
+ * Is the capabilities record readable?
+ *
+ * @param {unknown} raw
+ * @returns {boolean}
+ */
+export function isCapabilities(raw) {
+  if (!raw || typeof raw !== 'object') return false;
+  const scheduler = raw.scheduler;
+  return scheduler === SCHEDULER_OK || scheduler === SCHEDULER_BLOCKED || scheduler === SCHEDULER_UNKNOWN;
+}

package/lib/watchdog-arbiter.js

@@ -0,0 +1,117 @@
+/**
+ * ONE watchdog at a time.
+ *
+ * This plugin knows two watchdogs:
+ *
+ *   - **v1** (`lib/restart.js`): a detached PowerShell script. It puts the
+ *     snapshot back when the host does not come up — and it does **not** start
+ *     the host again.
+ *   - **v2** (`lib/watchdog.js` + the three tiers): it puts the snapshot back
+ *     **and** starts the host again, and it writes a report.
+ *
+ * Both take the SAME lock (`rollback.lock`). Two of them at once is worse than
+ * one: the one that loses the lock gives up, and if the loser is v2 the user
+ * gets a restored profile **and nothing running** — the rescue becomes the
+ * hole.
+ *
+ * So the rule is simple and it is decided in ONE place:
+ *
+ *   - v2 is armed → v2 is the arbiter, the old watcher is **not** started;
+ *   - v2 could not be armed (no tier, the watchdog is off, the registration
+ *     failed) → v1 is the arbiter, so the old machines still have a safety net.
+ *
+ * The v1 code stays (a way back, and the old tests still use it); it is just
+ * no longer started next to v2.
+ */
+
+/** Who is watching this restart. */
+export const ARBITERS = Object.freeze({
+  /** The new watchdog: restore + start the host again + a report. */
+  V2: 'v2',
+  /** The old watcher: restore only. */
+  V1: 'v1',
+  /** Nobody: the supervisor of the plugin restores the snapshot itself. */
+  NONE: 'none',
+});
+
+/**
+ * Decide who is the arbiter of this restart.
+ *
+ * @param {{
+ *   v2Armed?: boolean,
+ *   supervised?: boolean,
+ * }} [options]
+ * @returns {{ arbiter: string, startV1: boolean, reason: string }}
+ */
+export function planWatchdogArbiter({ v2Armed = false, supervised = false } = {}) {
+  if (supervised === true) {
+    return {
+      arbiter: ARBITERS.NONE,
+      startV1: false,
+      reason: 'the supervisor of the plugin restores the snapshot itself',
+    };
+  }
+  if (v2Armed === true) {
+    return {
+      arbiter: ARBITERS.V2,
+      startV1: false,
+      reason: 'the watchdog v2 is armed: it restores the snapshot AND starts the host again',
+    };
+  }
+  return {
+    arbiter: ARBITERS.V1,
+    startV1: true,
+    reason: 'the watchdog v2 is not available: the old watcher takes over',
+  };
+}
+
+/**
+ * Arm the watchdog — and only ONE of them.
+ *
+ * Both arms are injected, so a test can count them: when v2 is armed, the v1
+ * arm is never called, and the other way round.
+ *
+ * @param {{
+ *   v2Arm?: Function|null,
+ *   v1Arm?: Function|null,
+ *   supervised?: boolean,
+ *   log?: { warn?: Function, info?: Function }|null,
+ * }} [options]
+ * @returns {{
+ *   arbiter: string,
+ *   reason: string,
+ *   v2: object,
+ *   v1: object|null,
+ *   v1Started: boolean,
+ * }}
+ */
+export function armTheOneArbiter({
+  v2Arm = null,
+  v1Arm = null,
+  supervised = false,
+  log = null,
+} = {}) {
+  const v2 = typeof v2Arm === 'function'
+    ? v2Arm()
+    : { ok: false, tier: 'none', reason: 'the watchdog v2 was not armed' };
+  const plan = planWatchdogArbiter({ v2Armed: v2 !== null && v2.ok === true, supervised });
+  let v1 = null;
+  if (plan.startV1 === true && typeof v1Arm === 'function') {
+    v1 = v1Arm();
+  }
+  if (log !== null && typeof log === 'object' && typeof log.warn === 'function') {
+    log.warn('the watchdog arbiter is decided', {
+      arbiter: plan.arbiter,
+      reason: plan.reason,
+      v2Tier: v2 && typeof v2.tier === 'string' ? v2.tier : 'none',
+      v1Started: v1 !== null,
+    });
+  }
+  return {
+    arbiter: plan.arbiter,
+    reason: plan.reason,
+    v2: v2 === null ? { ok: false, tier: 'none', reason: 'the watchdog v2 was not armed' } : v2,
+    v1,
+    v1Started: v1 !== null,
+  };
+}