@push.rocks/smartdaemon 2.20.1 → 2.21.0

package/ts/classes.systemdservicedefinition.ts

@@ -1,11 +1,12 @@
 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';
+  type ISystemdServiceCredential, type TSystemdCapability, type TSystemdAddressFamily,
+  type TSystemdServiceOutput } from './systemd.definition.js';
+import { fileDescriptorStorePreserveMajor, outputAppendMajor } from './systemd.managerversion.js';
 export type { ISystemdServiceStartup, ISystemdServiceNotifyStartup, TSystemdServiceStartup,
   ISystemdServiceDependencies, ISystemdServiceInstallTargets, ISystemdServiceCredential, TSystemdCapability,
-  TSystemdAddressFamily } from './systemd.definition.js';
+  TSystemdAddressFamily, TSystemdServiceOutput } from './systemd.definition.js';
 export { systemdCapabilities, systemdAddressFamilies } from './systemd.definition.js';
 
 interface ISystemdServiceDefinitionBaseOptions {
@@ -78,6 +79,17 @@ interface ISystemdServiceDefinitionBaseOptions {
    * 64 variables and 8192 UTF-8 bytes of `NAME=value` in total. They are taken literally: `%` is escaped, and `Environment=` never expands `$`.
    */
   environment?: Readonly<Record<string, string>>;
+  /**
+   * Where the service's standard output goes (`StandardOutput=`): `'journal'` (the default),
+   * `'null'`, or `{ append: path }`, an absolute normalized path without a backslash, surrounding
+   * whitespace or trailing slash, whose file systemd appends to (`append:`, systemd 240 and later).
+   * An `append` output sets `requiredManagerMajor` to at least 240, so `SystemdUnitFile.install()`
+   * refuses an older manager, which would ignore the line. Omitted, the unit renders
+   * `StandardOutput=journal` as before.
+   */
+  standardOutput?: TSystemdServiceOutput;
+  /** Where the service's standard error goes (`StandardError=`), as `standardOutput`; omitted, `journal`. */
+  standardError?: TSystemdServiceOutput;
   /**
    * System scope only. Runs the service as a transient user and group allocated at start
    * (`DynamicUser=`), named by `user` and `group`, which then must not be `root` and have at most
@@ -177,8 +189,9 @@ export class SystemdServiceDefinition {
   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.
+   * renders one an older manager would ignore: the highest of 254 with `fileDescriptorStorePreserve`
+   * and 240 with an `append` output; otherwise null. `SystemdUnitFile.install()` refuses a
+   * definition on an older manager.
    */
   public readonly requiredManagerMajor: number | null;
 
@@ -217,7 +230,8 @@ export class SystemdServiceDefinition {
     const optionalKeys: TSystemdServiceDefinitionOption[] = ['scope', 'startup', 'dependencies', 'install',
       'restartSeconds', 'restartPreventExitStatus', 'successExitStatus', 'startLimitIntervalSeconds',
       'startLimitBurst', 'delegate', 'limitNoFile', 'tasksMax', 'oomScoreAdjust', 'notifyAccess',
-      'fileDescriptorStoreMax', 'fileDescriptorStorePreserve', 'environment', ...systemOnlyOptions];
+      'fileDescriptorStoreMax', 'fileDescriptorStorePreserve', 'environment', 'standardOutput', 'standardError',
+      ...systemOnlyOptions];
     // Every own key is a known option held by an enumerable data property, so no accessor or trap runs.
     for (const key of Reflect.ownKeys(options)) {
       requireValue(typeof key === 'string' && [...keys, ...optionalKeys, 'user', 'group'].includes(key as never), 'options');
@@ -334,6 +348,25 @@ export class SystemdServiceDefinition {
       service.push(...[...assignments.keys()].sort()
         .map((name) => `Environment=${quote(assignments.get(name)!)}`));
     }
+    /**
+     * An output stream's directive value, read once through the object's own data descriptor. An
+     * `append:` path is taken raw after specifier expansion, so only `%` is escaped.
+     */
+    const output = (value: unknown, option: 'standardOutput' | 'standardError'): string => {
+      if (value === undefined || value === 'journal') return 'journal';
+      if (value === 'null') return 'null';
+      plainObject(value, option);
+      const entryKeys = Reflect.ownKeys(value as object);
+      const descriptor = Object.getOwnPropertyDescriptor(value, 'append');
+      requireValue(entryKeys.length === 1 && entryKeys[0] === 'append' && descriptor?.enumerable &&
+        'value' in descriptor, option);
+      const file: unknown = descriptor!.value;
+      requireValue(absolute(file) && !file.endsWith('/') && file.trim() === file &&
+        !file.includes('\\'), option);
+      return `append:${(file as string).replaceAll('%', '%%')}`;
+    };
+    const standardOutput = output(options.standardOutput, 'standardOutput');
+    const standardError = output(options.standardError, 'standardError');
     // Every system-only option is refused by name in a user manager's service.
     for (const option of systemOnlyOptions) {
       requireValue(scope === 'system' || options[option] === undefined, option);
@@ -508,8 +541,8 @@ export class SystemdServiceDefinition {
       `TimeoutStopSec=${options.timeoutStopSeconds}s`,
       ...service,
       'StandardInput=null',
-      'StandardOutput=journal',
-      'StandardError=journal',
+      `StandardOutput=${standardOutput}`,
+      `StandardError=${standardError}`,
       '',
       '[Install]',
       ...relations.install,
@@ -517,8 +550,12 @@ 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;
+    // An older manager ignores a directive it does not read, so the newest one any line needs counts.
+    const requiredMajors = [
+      ...(options.fileDescriptorStorePreserve !== undefined ? [fileDescriptorStorePreserveMajor] : []),
+      ...([standardOutput, standardError].some((value) => value.startsWith('append:')) ? [outputAppendMajor] : []),
+    ];
+    this.requiredManagerMajor = requiredMajors.length > 0 ? Math.max(...requiredMajors) : null;
     Object.freeze(this);
   }
 }

package/ts/classes.systemdunit.ts

@@ -539,6 +539,17 @@ export class SystemdUnit {
     return this.inspect();
   }
 
+  /**
+   * Persistently disables the unit: removes the enablement links its `[Install]` section names
+   * (`systemctl disable`, which reloads the manager), then inspects. Never stops, masks, unmasks or
+   * removes the definition; a running unit keeps running. A failed or timed out command can leave
+   * partial enablement: inspect and retry the exact operation.
+   */
+  public async disable(): Promise<ISystemdUnitState> {
+    await this.command(['disable', this.unitName]);
+    return this.inspect();
+  }
+
   /** Loaded manager graph, including reverse edges. Enablement alone does not prove every required link. */
   public async inspectRelationships(): Promise<ISystemdUnitRelationships> {
     const keys = ['Id', 'Before', 'After', 'Requires', 'Wants', 'Conflicts', 'RequiredBy', 'WantedBy'];

package/ts/classes.systemdunitfile.ts

@@ -157,15 +157,27 @@ const admittedFileStates: Readonly<Record<string, readonly string[]>> = {
   masked: ['masked', 'masked-runtime'],
   'not-found': [''],
 };
-/** Admits a quiet unit whose load and unit-file states installation may write behind. */
-const requireAdmittedState = (state: ISystemdUnitState): void => {
+/**
+ * The unit-file states removal admits: a loaded unit only when disabled, so no enablement link is
+ * left naming a definition that no longer exists.
+ */
+const removableFileStates: Readonly<Record<string, readonly string[]>> = {
+  loaded: ['disabled'],
+  masked: ['masked', 'masked-runtime'],
+  'not-found': [''],
+};
+/** Admits a quiet unit whose load and unit-file states the operation may write behind. */
+const requireAdmittedState = (
+  state: ISystemdUnitState,
+  fileStates: Readonly<Record<string, readonly string[]>>,
+): void => {
   const reason: TSystemdUnitFileUnsafeUnitReason | null = !idle(state)
     ? 'active'
     : state.job !== ''
     ? 'job_pending'
-    : !Object.hasOwn(admittedFileStates, state.loadState)
+    : !Object.hasOwn(fileStates, state.loadState)
     ? 'unexpected_load_state'
-    : !admittedFileStates[state.loadState].includes(state.unitFileState)
+    : !fileStates[state.loadState].includes(state.unitFileState)
     ? 'unexpected_file_state'
     : null;
   if (reason) throw new SystemdUnitFileUnsafeUnitError(reason, state, null);
@@ -310,7 +322,7 @@ export class SystemdUnitFile {
     let temporaryInfo: plugins.Stats | undefined;
     try {
       const before = await this.unit.inspect();
-      const beforeConfiguration = await this.admit(before, maskDirectories);
+      const beforeConfiguration = await this.admit(before, maskDirectories, admittedFileStates);
       await this.directories(true);
       const parent = await plugins.fs.lstat(this.directory);
       const previous = await this.read(this.path);
@@ -345,7 +357,7 @@ export class SystemdUnitFile {
         );
         const rechecked = await this.unit.inspect();
         requireValue(JSON.stringify(rechecked) === JSON.stringify(before), 'changed');
-        const recheckedConfiguration = await this.admit(rechecked, maskDirectories);
+        const recheckedConfiguration = await this.admit(rechecked, maskDirectories, admittedFileStates);
         requireValue(
           recheckedConfiguration.fragmentPath === beforeConfiguration.fragmentPath,
           'changed',
@@ -395,11 +407,116 @@ export class SystemdUnitFile {
     }
   }
 
+  /**
+   * Removes the definition `install()` wrote and the previous definitions it retained beside it
+   * (`<unit>.previous-<sha256>`), then reloads the manager. The expected SHA-256 of the installed
+   * definition is mandatory, so only the bytes the caller installed are removed; an absent unit
+   * file with no retained definition is idempotent (`removed: false`) and reloads nothing.
+   *
+   * Admits only a unit at rest with no job queued, no pending reload and no drop-ins, whose
+   * manager view still selects this file: a loaded unit must be disabled first
+   * (`SystemdUnit.disable()`), so no enablement link outlives its definition; a masked unit keeps
+   * its mask; a unit the manager does not find is admitted. Refusals are the `unsafe_unit` reasons
+   * of `install()`, `unexpected_file_state` for an enabled unit among them. Every file is checked
+   * like the installed one (regular, single link, mode 0644, owned by the expected uid) and each
+   * retained definition must hold the bytes its name digests, or nothing is removed (`changed`).
+   * After removal the manager must report the unit not found (or still masked) and at rest;
+   * otherwise `reload_failed`, with the files already removed. Never stops, disables or unmasks.
+   */
+  public async uninstall(
+    expectedSha256: string,
+  ): Promise<Readonly<{ removed: boolean; masked: boolean; removedPaths: readonly string[] }>> {
+    requireValue(typeof expectedSha256 === 'string' && /^[a-f0-9]{64}$/.test(expectedSha256),
+      'invalid_options');
+    const maskDirectories = this.maskDirectories();
+    if (maskDirectories === null) throw new SystemdUnitFileError('invalid_options');
+    requireValue(!this.busy, 'busy');
+    this.busy = true;
+    try {
+      const before = await this.unit.inspect();
+      const beforeConfiguration = await this.admit(before, maskDirectories, removableFileStates);
+      const unchanged = Object.freeze({ removed: false, masked: masked(before), removedPaths: Object.freeze([]) });
+      // A loaded unit selects this file, so its absence is drift, not an earlier removal.
+      if (!await this.directories(false)) {
+        requireValue(before.loadState !== 'loaded', 'changed');
+        return unchanged;
+      }
+      const parent = await plugins.fs.lstat(this.directory);
+      const current = await this.read(this.path);
+      if (current) requireValue(digest(current.bytes) === expectedSha256, 'changed');
+      else requireValue(before.loadState !== 'loaded', 'changed');
+      const targets = [
+        ...(current ? [{ path: this.path, info: current.info }] : []),
+        ...await this.retainedDefinitions(),
+      ];
+      if (targets.length === 0) return unchanged;
+      const rechecked = await this.unit.inspect();
+      requireValue(JSON.stringify(rechecked) === JSON.stringify(before), 'changed');
+      const recheckedConfiguration = await this.admit(rechecked, maskDirectories, removableFileStates);
+      requireValue(recheckedConfiguration.fragmentPath === beforeConfiguration.fragmentPath, 'changed');
+      requireSafePath(sameFile(parent, await plugins.fs.lstat(this.directory)), this.directory, 'replaced');
+      // Every name must still hold the file that was checked before the first is removed, so a
+      // refusal never leaves a partial removal.
+      for (const target of targets) {
+        requireValue(sameFile(target.info, await plugins.fs.lstat(target.path)), 'changed');
+      }
+      for (const target of targets) await plugins.fs.unlink(target.path);
+      await this.flushDirectory(parent);
+      const removedPaths = Object.freeze(targets.map((target) => target.path));
+      try {
+        const reloadedConfiguration = await this.unit.reloadConfiguration();
+        const after = await this.unit.inspect();
+        requireValue(
+          quiet(after) &&
+            (masked(before)
+              ? masked(after) && after.unitFileState === before.unitFileState
+              : after.loadState === 'not-found' && after.unitFileState === ''),
+          'changed',
+        );
+        const configuration = await this.unit.inspectConfiguration();
+        const expectedFragment = masked(after) ? beforeConfiguration.fragmentPath : '';
+        for (const snapshot of [reloadedConfiguration, configuration]) {
+          requireAdmittedConfiguration(after, snapshot, snapshot.fragmentPath === expectedFragment);
+        }
+        requireValue(await this.read(this.path) === null, 'changed');
+        return Object.freeze({ removed: current !== null, masked: masked(after), removedPaths });
+      } catch (error) {
+        // The files are already removed; the cause says why the reload was not accepted.
+        throw new SystemdUnitFileError('reload_failed', { cause: error });
+      }
+    } catch (error) {
+      if (error instanceof SystemdUnitFileError) throw error;
+      throw new SystemdUnitFileError('write_failed');
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  /**
+   * The previous definitions `install()` retained beside the unit, each checked like the unit file
+   * and holding exactly the bytes its name digests.
+   */
+  private async retainedDefinitions(): Promise<Array<{ path: string; info: plugins.Stats }>> {
+    const prefix = `${this.name}.previous-`;
+    const retained: Array<{ path: string; info: plugins.Stats }> = [];
+    for (const entry of (await plugins.fs.readdir(this.directory)).sort()) {
+      if (!entry.startsWith(prefix)) continue;
+      const sha256 = entry.slice(prefix.length);
+      if (!/^[a-f0-9]{64}$/.test(sha256)) continue;
+      const path = plugins.path.join(this.directory, entry);
+      const file = await this.read(path);
+      requireValue(file !== null && digest(file.bytes) === sha256, 'changed');
+      retained.push({ path, info: file!.info });
+    }
+    return retained;
+  }
+
   private async admit(
     state: ISystemdUnitState,
     maskDirectories: IMaskDirectories,
+    fileStates: Readonly<Record<string, readonly string[]>>,
   ): Promise<ISystemdUnitConfigurationState> {
-    requireAdmittedState(state);
+    requireAdmittedState(state, fileStates);
     const configuration = await this.unit.inspectConfiguration();
     const maskPaths = (state.unitFileState === 'masked-runtime'
       ? maskDirectories.runtime : maskDirectories.persistent)

package/ts/systemd.definition.ts

@@ -28,6 +28,18 @@ export interface ISystemdServiceDependencies {
   conflicts: readonly string[];
 }
 
+/**
+ * Where one of the service's output streams goes (`StandardOutput=`, `StandardError=`): the
+ * journal, nowhere (`null`), or appended to a file (`append:`, systemd 240 and later). The
+ * service manager opens an `append` file with `O_APPEND` before it invokes the executable and
+ * before it drops to the service's `User=`, so with the manager's own privileges: root for the
+ * system manager, the user for a user manager. It creates a missing file owned by that user
+ * with mode 0666 masked by the unit's umask (0644 under the usual umask 0022); its directory must
+ * exist. A caller that needs another owner or a private mode creates the file first: an existing
+ * file keeps its owner and mode.
+ */
+export type TSystemdServiceOutput = 'journal' | 'null' | { readonly append: string };
+
 /** Install metadata only; rendering and file installation do not enable these links. */
 export interface ISystemdServiceInstallTargets {
   wantedBy: readonly string[];

package/ts/systemd.managerversion.ts

@@ -13,6 +13,9 @@ export interface ISystemdManagerVersion {
 /** Internal: the systemd major that first reads `FileDescriptorStorePreserve=` and reports it. */
 export const fileDescriptorStorePreserveMajor = 254;
 
+/** Internal: the systemd major that first reads `append:` in `StandardOutput=` and `StandardError=`. */
+export const outputAppendMajor = 240;
+
 /** Internal: the systemd major whose `systemctl clean` first releases a file descriptor store (`--what=fdstore`). */
 export const fileDescriptorStoreCleanMajor = 254;