@push.rocks/smartdaemon 2.17.0 → 2.19.0

package/ts/classes.systemdservicedefinition.ts

@@ -2,6 +2,7 @@ import * as plugins from './smartdaemon.plugins.js';
 import { environmentByteLimit, environmentVariableLimit, isCleanText, renderServiceRelations, systemdAddressFamilies,
   systemdCapabilities, type TSystemdServiceStartup, type ISystemdServiceDependencies, type ISystemdServiceInstallTargets,
   type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily } from './systemd.definition.js';
+import { fileDescriptorStorePreserveMajor } from './systemd.managerversion.js';
 export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
   ISystemdServiceDependencies, ISystemdServiceInstallTargets, ISystemdServiceCredential, TSystemdCapability,
   TSystemdAddressFamily } from './systemd.definition.js';
@@ -65,7 +66,9 @@ interface ISystemdServiceDefinitionBaseOptions {
    * When the manager releases the store (`FileDescriptorStorePreserve=`, systemd 254 or later):
    * `'no'` when the service stops, `'restart'` (systemd's default) once it is neither active nor
    * about to restart, `'yes'` only when the unit leaves the manager's memory or is cleaned with
-   * `SystemdUnit.cleanFileDescriptorStore()`. Requires `fileDescriptorStoreMax`.
+   * `SystemdUnit.cleanFileDescriptorStore()`. Requires `fileDescriptorStoreMax`. Sets
+   * `requiredManagerMajor` to 254, so `SystemdUnitFile.install()` refuses an older manager, which
+   * would ignore the line.
    */
   fileDescriptorStorePreserve?: 'no' | 'yes' | 'restart';
   /**
@@ -172,6 +175,12 @@ export class SystemdServiceDefinition {
   public readonly scope: 'system' | 'user';
   public readonly content: string;
   public readonly sha256: string;
+  /**
+   * The oldest systemd major whose manager reads every directive this definition renders, when it
+   * renders one an older manager would ignore: 254 with `fileDescriptorStorePreserve`; otherwise
+   * null. `SystemdUnitFile.install()` refuses a definition on an older manager.
+   */
+  public readonly requiredManagerMajor: number | null;
 
   constructor(options: ISystemdServiceDefinitionOptions) {
     const fail = (option: TSystemdServiceDefinitionOption): never => {
@@ -508,6 +517,8 @@ export class SystemdServiceDefinition {
     ].join('\n');
     requireValue(Buffer.byteLength(this.content) <= 16384, 'options');
     this.sha256 = plugins.crypto.createHash('sha256').update(this.content).digest('hex');
+    this.requiredManagerMajor = options.fileDescriptorStorePreserve !== undefined
+      ? fileDescriptorStorePreserveMajor : null;
     Object.freeze(this);
   }
 }

package/ts/classes.systemdtransientscope.ts

@@ -1,6 +1,12 @@
 import * as plugins from './smartdaemon.plugins.js';
 import { isCleanText } from './systemd.definition.js';
 import { captureUserEnvironment, inspectRuntimeDirectory, isSafeDirectory } from './systemd.userenvironment.js';
+import {
+  type ISystemdManagerVersion,
+  managerVersionArguments,
+  parseManagerVersion,
+  transientScopeMajor,
+} from './systemd.managerversion.js';
 
 export interface ISystemdTransientScopeOptions {
   /** The calling user's manager; the only manager a transient scope is started in. */
@@ -51,8 +57,16 @@ export type TSystemdTransientScopeErrorCode =
   | 'invalid_options'
   /** The process is not running on Linux. */
   | 'unsupported_platform'
-  /** No runtime directory is set or it does not exist, or the manager does not answer systemctl. */
+  /**
+   * No runtime directory is set or it does not exist, or the manager does not answer systemctl
+   * with a version it reports as systemd does (`SystemdUnit.inspectManagerVersion()`).
+   */
   | 'user_manager_unavailable'
+  /**
+   * The user manager is older than systemd 254, whose systemd-run this call needs; always a
+   * `SystemdTransientScopeManagerTooOldError`. Nothing was started.
+   */
+  | 'manager_too_old'
   /** systemd-run exited without reporting the scope running; the program has not run. */
   | 'scope_start_failed'
   /** The manager probe or the program did not finish, and close its output, in time. */
@@ -74,6 +88,24 @@ export class SystemdTransientScopeError extends Error {
   }
 }
 
+/** Every `manager_too_old` refusal: names the user manager's version and the one required. */
+export class SystemdTransientScopeManagerTooOldError extends SystemdTransientScopeError {
+  declare public readonly code: 'manager_too_old';
+
+  constructor(
+    unitName: string,
+    /** The user manager's version the probe read. */
+    public readonly managerVersion: ISystemdManagerVersion,
+    /** The oldest systemd major the call needs. */
+    public readonly requiredMajor: number,
+  ) {
+    super('manager_too_old', unitName, '');
+    this.message = `Systemd transient scope failed: manager_too_old (${unitName}: systemd ` +
+      `${managerVersion.major} running, ${requiredMajor} required).`;
+    this.name = 'SystemdTransientScopeManagerTooOldError';
+  }
+}
+
 const outputLimit = 1048576;
 const reservedName = (name: string) =>
   name === 'XDG_RUNTIME_DIR' || name === 'INVOCATION_ID' || name.startsWith('SYSTEMD_') || name.startsWith('DBUS_');
@@ -227,7 +259,9 @@ const programStderr = (stderr: string, unitName: string): string | undefined =>
  * must not keep the program's stdout or stderr open, or the call runs into its timeout.
  *
  * On `timed_out` and `output_limit` the direct process is killed; processes it started stay in
- * the scope. A program that exits with a failure status is a result, not an error.
+ * the scope. A program that exits with a failure status is a result, not an error. A user manager
+ * older than systemd 254 is refused with `SystemdTransientScopeManagerTooOldError` before
+ * systemd-run is started.
  */
 export const runInTransientScope = async (
   options: ISystemdTransientScopeOptions,
@@ -247,13 +281,19 @@ export const runInTransientScope = async (
   if (admission !== 'private') fail('invalid_options');
 
   const probe = await runProcess(validated.systemctlPath,
-    ['--user', '--no-ask-password', '--no-pager', 'show', '--property=Version'],
+    ['--user', '--no-ask-password', '--no-pager', ...managerVersionArguments],
     { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C', XDG_RUNTIME_DIR: runtimeDirectory! }, validated.timeoutMs);
   if (probe.kind === 'timed_out') fail('timed_out', probe.stderr);
-  if (probe.kind !== 'exited' || probe.code !== 0 || !probe.stdout.startsWith('Version=')) {
-    fail('user_manager_unavailable', probe.kind === 'spawn_failed' ? '' : probe.stderr,
+  const managerVersion = probe.kind === 'exited' && probe.code === 0 ? parseManagerVersion(probe.stdout) : undefined;
+  if (managerVersion === undefined) {
+    return fail('user_manager_unavailable', probe.kind === 'spawn_failed' ? '' : probe.stderr,
       probe.kind === 'spawn_failed' ? probe.error : undefined);
   }
+  // systemd-run before 254 knows no --expand-environment; the running user manager's version is the
+  // one this call can read before starting anything, so it stands for the installation's.
+  if (managerVersion.major < transientScopeMajor) {
+    throw new SystemdTransientScopeManagerTooOldError(unitName, managerVersion, transientScopeMajor);
+  }
 
   // systemd-run registers its own process as the scope, then executes the program in place with
   // its environment, so that environment is the program's own plus INVOCATION_ID.

package/ts/classes.systemdunit.ts

@@ -8,6 +8,14 @@ import {
   isUserManagerEnvironment,
 } from './systemd.userenvironment.js';
 import { environmentByteLimit, environmentVariableLimit, isCleanText } from './systemd.definition.js';
+import {
+  type ISystemdManagerVersion,
+  fileDescriptorStoreCleanMajor,
+  fileDescriptorStorePreserveMajor,
+  managerVersionArguments,
+  parseManagerVersion,
+} from './systemd.managerversion.js';
+export type { ISystemdManagerVersion } from './systemd.managerversion.js';
 
 export interface ISystemdUnitOptions {
   unitName: string;
@@ -167,12 +175,45 @@ export interface ISystemdServiceSettings {
 }
 
 export class SystemdUnitError extends Error {
-  constructor(public readonly code: 'invalid_options' | 'command_failed' | 'invalid_state') {
-    super(`Systemd unit operation failed: ${code}.`);
+  constructor(
+    /**
+     * `released_uninspected`: only `cleanFileDescriptorStore()`. The manager released the store, and
+     * the snapshot read afterwards failed; `cause` is that inspection's error.
+     * `version_unknown`: the manager answered, but its `Version` property is not one this package
+     * reads, so a call that needs a minimum manager version refuses.
+     * `manager_too_old`: always a `SystemdUnitManagerTooOldError`, naming both versions.
+     */
+    public readonly code:
+      | 'invalid_options'
+      | 'command_failed'
+      | 'invalid_state'
+      | 'released_uninspected'
+      | 'version_unknown'
+      | 'manager_too_old',
+    options?: ErrorOptions,
+  ) {
+    super(`Systemd unit operation failed: ${code}.`, options);
     this.name = 'SystemdUnitError';
   }
 }
 
+/** Every `manager_too_old` refusal: the running manager is older than the call needs. */
+export class SystemdUnitManagerTooOldError extends SystemdUnitError {
+  declare public readonly code: 'manager_too_old';
+
+  constructor(
+    /** The running manager's version the refusal read. */
+    public readonly managerVersion: ISystemdManagerVersion,
+    /** The oldest systemd major the refused call needs. */
+    public readonly requiredMajor: number,
+  ) {
+    super('manager_too_old');
+    this.message = `Systemd unit operation failed: manager_too_old (systemd ${managerVersion.major} ` +
+      `running, ${requiredMajor} required).`;
+    this.name = 'SystemdUnitManagerTooOldError';
+  }
+}
+
 // systemd's format_timespan() units, largest first; a year and a month are 365.25 and 30.44 days.
 const timespanUnits = new Map<string, bigint>([
   ['y', 31557600000000n], ['month', 2629800000000n], ['w', 604800000000n], ['d', 86400000000n],
@@ -507,11 +548,42 @@ export class SystemdUnit {
     });
   }
 
+  /**
+   * Reads the running manager's version (`systemctl show --property=Version`) through the unit's
+   * scope: the system manager, or the calling user's manager for user scope. A manager that does
+   * not answer rejects with `command_failed`; an answer this package cannot read, with
+   * `version_unknown`.
+   */
+  public async inspectManagerVersion(): Promise<ISystemdManagerVersion> {
+    const version = parseManagerVersion(await this.command([...managerVersionArguments]));
+    if (version === undefined) throw new SystemdUnitError('version_unknown');
+    return version;
+  }
+
+  /**
+   * Resolves with the running manager's version when its major is at least `requiredMajor`, an
+   * integer from 1 to 9999; otherwise rejects with a `SystemdUnitManagerTooOldError`. Fails closed:
+   * an unreadable version rejects with `version_unknown`, an unanswered read with
+   * `command_failed`, and a malformed `requiredMajor` with `invalid_options` before any command.
+   */
+  public async requireManagerVersion(requiredMajor: number): Promise<ISystemdManagerVersion> {
+    if (!Number.isSafeInteger(requiredMajor) || requiredMajor < 1 || requiredMajor > 9999) {
+      throw new SystemdUnitError('invalid_options');
+    }
+    const version = await this.inspectManagerVersion();
+    if (version.major < requiredMajor) throw new SystemdUnitManagerTooOldError(version, requiredMajor);
+    return version;
+  }
+
   /**
    * Reports the loaded service settings that a definition renders, so an owner can verify an
    * installed unit carries them. Reads only; the manager must have reloaded changed files first.
+   * Needs systemd 254 or later, which first reports `FileDescriptorStorePreserve`: an older manager
+   * is refused with `SystemdUnitManagerTooOldError` before the unit is read, and so is a manager
+   * whose version is unreadable, with `version_unknown`.
    */
   public async inspectServiceSettings(): Promise<ISystemdServiceSettings> {
+    await this.requireManagerVersion(fileDescriptorStorePreserveMajor);
     const keys = ['Id', 'Type', 'NotifyAccess', 'Restart', 'RestartUSec', 'KillMode', 'TimeoutStopUSec',
       'TimeoutStartUSec', 'RestartPreventExitStatus', 'SuccessExitStatus', 'StartLimitIntervalUSec', 'StartLimitBurst',
       'Delegate', 'LimitNOFILE', 'LimitNOFILESoft', 'TasksMax', 'OOMScoreAdjust', 'FileDescriptorStoreMax',
@@ -523,7 +595,7 @@ export class SystemdUnit {
       if (separator < 1 || !keys.includes(key) || fields.has(key)) throw new SystemdUnitError('invalid_state');
       fields.set(key, line.slice(separator + 1));
     }
-    // An older manager omits a property it does not know; the count check refuses that snapshot.
+    // A manager that omits a requested property it should know fails this count check.
     if (fields.size !== keys.length || fields.get('Id') !== this.unitName) throw new SystemdUnitError('invalid_state');
     const mode = (key: string, empty = false): string => {
       const value = fields.get(key)!;
@@ -581,10 +653,27 @@ export class SystemdUnit {
    * `command_failed`, unless the unit is loaded, inactive (not failed) and without a pending job,
    * and its loaded `FileDescriptorStoreMax` is above zero or the store still holds a descriptor.
    * Nothing else of the unit is cleaned.
+   *
+   * Every outcome after the manager accepted the clean states that the store was released: the
+   * call resolves with the snapshot read afterwards, which reports the unit as it is then (a start
+   * after the release may already have stored descriptors again), or rejects with
+   * `released_uninspected` and that inspection's error as `cause`. A clean the manager refused
+   * or that could not be run rejects with `command_failed`; so does one whose `systemctl` call
+   * exceeded `commandTimeoutMs`, whose outcome is then unknown, so after `command_failed` a caller
+   * must `inspect()` the unit before treating the store as kept.
+   *
+   * Needs systemd 254 or later, the first that cleans a store: the manager's version is read first,
+   * and an older manager is refused with `SystemdUnitManagerTooOldError`, an unreadable version with
+   * `version_unknown` and an unanswered read with `command_failed`, each before any clean is run.
    */
   public async cleanFileDescriptorStore(): Promise<ISystemdUnitState> {
+    await this.requireManagerVersion(fileDescriptorStoreCleanMajor);
     await this.command(['clean', '--what=fdstore', this.unitName]);
-    return this.inspect();
+    try {
+      return await this.inspect();
+    } catch (error) {
+      throw new SystemdUnitError('released_uninspected', { cause: error });
+    }
   }
 
   /** Reloads unit definitions globally; does not enable, unmask, start or stop a unit. */

package/ts/classes.systemdunitfile.ts

@@ -270,6 +270,11 @@ export class SystemdUnitFile {
   /**
    * Expected previous digest is mandatory; null admits an absent file. Exact desired bytes are idempotent.
    * Retains changed definitions beside the unit before replacement. A failed reload never rolls code back.
+   *
+   * A definition with a `requiredManagerMajor` is admitted only on a manager at least that new,
+   * read before any directory, file or other systemctl effect: an older manager rejects with
+   * the unit's `SystemdUnitManagerTooOldError` (`manager_too_old`), an unreadable version with
+   * `SystemdUnitError` `version_unknown` and a failed read with `SystemdUnitError` `command_failed`.
    */
   public async install(
     definition: SystemdServiceDefinition,
@@ -288,6 +293,10 @@ export class SystemdUnitFile {
     // instead of a wrapped write_failed.
     const maskDirectories = this.maskDirectories();
     if (maskDirectories === null) throw new SystemdUnitFileError('invalid_options');
+    // A manager older than the definition needs would load the unit without the newer directives.
+    if (definition.requiredManagerMajor !== null) {
+      await this.unit.requireManagerVersion(definition.requiredManagerMajor);
+    }
     requireValue(!this.busy, 'busy');
     this.busy = true;
     let temporary: string | undefined;

package/ts/systemd.managerversion.ts

@@ -0,0 +1,38 @@
+/** The version of a running systemd manager, as the manager itself reports it. */
+export interface ISystemdManagerVersion {
+  /** systemd's major version: the leading number of `version`, `255` for `255.4-1ubuntu8.17`. */
+  readonly major: number;
+  /**
+   * The manager's `Version` property verbatim, as its build names it: `255.4-1ubuntu8.17`,
+   * `253.5-1`, `256~rc3` or `257.1-1.fc41`. It is the running manager's version, which differs
+   * from `systemctl --version` after an upgrade until the manager re-executes.
+   */
+  readonly version: string;
+}
+
+/** Internal: the systemd major that first reads `FileDescriptorStorePreserve=` and reports it. */
+export const fileDescriptorStorePreserveMajor = 254;
+
+/** Internal: the systemd major whose `systemctl clean` first releases a file descriptor store (`--what=fdstore`). */
+export const fileDescriptorStoreCleanMajor = 254;
+
+/**
+ * Internal: the systemd major whose `systemd-run` first takes `--expand-environment` and reports a
+ * started scope as `runInTransientScope()` reads it.
+ */
+export const transientScopeMajor = 254;
+
+/** Internal: the `systemctl` verb and argument that print the manager's `Version` property. */
+export const managerVersionArguments: readonly string[] = ['show', '--property=Version'];
+
+/**
+ * Internal: parses the output of `systemctl show --property=Version`, exactly one
+ * `Version=<version>` line. The version is a major of 1–4 digits without a leading zero,
+ * optionally followed by a separator (`.`, `~`, `-`, `+`, `^` or `_`) and printable ASCII, at
+ * most 256 characters in all. Anything else, `systemctl --version`'s `systemd 255 (255.4-1)`
+ * format included, is refused with undefined.
+ */
+export const parseManagerVersion = (stdout: string): ISystemdManagerVersion | undefined => {
+  const match = /^Version=(([1-9][0-9]{0,3})(?:[.~+^_-][\x21-\x7e]{0,251})?)\n$/.exec(stdout);
+  return match ? Object.freeze({ major: Number(match[2]), version: match[1] }) : undefined;
+};