@push.rocks/smartdaemon 2.20.1 → 2.22.0

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;
 

package/ts_systemdruntime/classes.systemdnotifier.ts

@@ -0,0 +1,287 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import {
+  controlSpace,
+  descriptorsPerMessageMaximum,
+  libcConstants,
+  socketAddressLength,
+  systemdLibc,
+  writeSocketAddress,
+} from './systemdruntime.libc.js';
+import {
+  assertSystemdDescriptor,
+  assertSystemdNotifySocketAddress,
+  isSystemdDescriptorName,
+} from './systemdruntime.validation.js';
+
+/** `NOTIFY_BUFFER_MAX` (`PIPE_BUF`): systemd ignores a longer notification message. */
+export const notifyMessageMaximumBytes = 4096;
+
+export interface ISystemdEnvironmentOptions {
+  /** The environment to read; `process.env` by default. */
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface ISystemdNotifierEnvironmentOptions extends ISystemdEnvironmentOptions {
+  /** Remove `NOTIFY_SOCKET` from the environment, so no child inherits it. Default `false`. */
+  readonly take?: boolean;
+}
+
+export interface ISystemdStoreDescriptorsOptions {
+  /**
+   * Whether the manager watches the stored descriptors and drops one that reports `POLLHUP` or
+   * `POLLERR` (`FDPOLL=`). Default `true`, as in systemd; `false` sends `FDPOLL=0`, for descriptors
+   * that are not pollable or always report hang-up, such as namespace descriptors.
+   */
+  readonly poll?: boolean;
+}
+
+/**
+ * Takes `NOTIFY_SOCKET` out of the environment: the validated address, or null when it is unset or
+ * empty. An address that is set but invalid is removed as well and then refused
+ * (`notify_socket_invalid`).
+ */
+export const takeSystemdNotifySocket = (optionsArg: ISystemdEnvironmentOptions = {}): string | null => {
+  const env = optionsArg.env ?? process.env;
+  const address = env.NOTIFY_SOCKET;
+  delete env.NOTIFY_SOCKET;
+  if (address === undefined || address === '') return null;
+  assertSystemdNotifySocketAddress(address);
+  return address;
+};
+
+const fieldNamePattern = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Sends `sd_notify(3)` messages to a service manager's notification socket: one `AF_UNIX`
+ * `SOCK_DGRAM` datagram per message, descriptors attached as `SCM_RIGHTS`. Every call is synchronous
+ * and either delivers the whole message to the socket or throws a `SystemdRuntimeError`; whether
+ * the manager acts on it depends on the unit's `NotifyAccess=`. Fields and descriptor names are
+ * validated before sending, because systemd ignores a message it cannot parse without telling the
+ * sender.
+ */
+export class SystemdNotifier {
+  /**
+   * The notifier for the unit that started this process, or null when `NOTIFY_SOCKET` is unset or
+   * empty — the process was not started by a service manager that listens. The caller decides what
+   * that means; nothing is sent silently nowhere. An invalid `NOTIFY_SOCKET` throws
+   * `notify_socket_invalid`.
+   */
+  public static fromEnvironment(optionsArg: ISystemdNotifierEnvironmentOptions = {}): SystemdNotifier | null {
+    const env = optionsArg.env ?? process.env;
+    const address = optionsArg.take === true ? takeSystemdNotifySocket({ env }) : env.NOTIFY_SOCKET;
+    if (address === undefined || address === null || address === '') return null;
+    return new SystemdNotifier(address);
+  }
+
+  /** The notification socket: an absolute path, or an abstract name written `@name`. */
+  public readonly socketAddress: string;
+
+  constructor(socketAddressArg: string) {
+    assertSystemdNotifySocketAddress(socketAddressArg);
+    this.socketAddress = socketAddressArg;
+  }
+
+  /** `READY=1`, with an optional `STATUS=`. */
+  public ready(statusArg?: string): void {
+    this.send({ READY: '1', ...(statusArg === undefined ? {} : { STATUS: statusArg }) });
+  }
+
+  /** `STATUS=`: free-form text the manager shows as the unit's status. */
+  public status(textArg: string): void {
+    this.send({ STATUS: textArg });
+  }
+
+  /** `STOPPING=1`, with an optional `STATUS=`. */
+  public stopping(statusArg?: string): void {
+    this.send({ STOPPING: '1', ...(statusArg === undefined ? {} : { STATUS: statusArg }) });
+  }
+
+  /**
+   * `RELOADING=1` with `MONOTONIC_USEC=` (`CLOCK_MONOTONIC` now), with an optional `STATUS=`. The
+   * service sends `ready()` once the reload finished.
+   */
+  public reloading(statusArg?: string): void {
+    this.send({
+      RELOADING: '1',
+      MONOTONIC_USEC: String(monotonicMicroseconds()),
+      ...(statusArg === undefined ? {} : { STATUS: statusArg }),
+    });
+  }
+
+  /** `WATCHDOG=1`: keeps a `WatchdogSec=` unit alive. */
+  public watchdog(): void {
+    this.send({ WATCHDOG: '1' });
+  }
+
+  /**
+   * `EXTEND_TIMEOUT_USEC=`: asks the manager to wait `microsecondsArg` longer for the current start,
+   * runtime-start, stop or watchdog deadline, with an optional `STATUS=`.
+   */
+  public extendTimeout(microsecondsArg: number, statusArg?: string): void {
+    if (!Number.isSafeInteger(microsecondsArg) || microsecondsArg <= 0) {
+      throw new SystemdRuntimeError('notify_field_invalid', 'EXTEND_TIMEOUT_USEC must be a positive integer.');
+    }
+    this.send({
+      EXTEND_TIMEOUT_USEC: String(microsecondsArg),
+      ...(statusArg === undefined ? {} : { STATUS: statusArg }),
+    });
+  }
+
+  /**
+   * `FDSTORE=1` with `FDNAME=`: the manager keeps duplicates of `descriptorsArg` (1–253) under
+   * `nameArg` in the unit's descriptor store (`FileDescriptorStoreMax=`) and passes them to the
+   * next main process through `LISTEN_FDS`. Storing does not replace descriptors already stored
+   * under the name; `replaceDescriptors()` does.
+   */
+  public storeDescriptors(
+    nameArg: string,
+    descriptorsArg: readonly number[],
+    optionsArg: ISystemdStoreDescriptorsOptions = {},
+  ): void {
+    assertDescriptorName(nameArg);
+    assertStoredDescriptors(descriptorsArg);
+    this.send(
+      { FDSTORE: '1', FDNAME: nameArg, ...(optionsArg.poll === false ? { FDPOLL: '0' } : {}) },
+      descriptorsArg,
+    );
+  }
+
+  /** `FDSTOREREMOVE=1` with `FDNAME=`: the manager closes every descriptor stored under `nameArg`. */
+  public removeDescriptors(nameArg: string): void {
+    assertDescriptorName(nameArg);
+    this.send({ FDSTOREREMOVE: '1', FDNAME: nameArg });
+  }
+
+  /**
+   * Removes the descriptors stored under `nameArg`, then stores `descriptorsArg` under it: two
+   * messages, handled by the manager in order. Between them the store holds nothing under the name.
+   */
+  public replaceDescriptors(
+    nameArg: string,
+    descriptorsArg: readonly number[],
+    optionsArg: ISystemdStoreDescriptorsOptions = {},
+  ): void {
+    assertDescriptorName(nameArg);
+    assertStoredDescriptors(descriptorsArg);
+    this.removeDescriptors(nameArg);
+    this.storeDescriptors(nameArg, descriptorsArg, optionsArg);
+  }
+
+  /**
+   * Sends one message: `NAME=value` fields in insertion order, joined by newlines, and up to 253
+   * descriptors. Names are upper-case (`A–Z`, digits, `_`); values carry no newline or NUL; the
+   * message is at most 4096 bytes.
+   */
+  public send(fieldsArg: Readonly<Record<string, string>>, descriptorsArg: readonly number[] = []): void {
+    const entries = Object.entries(fieldsArg);
+    if (entries.length === 0) {
+      throw new SystemdRuntimeError('notify_field_invalid', 'A notification needs at least one field.');
+    }
+    for (const [name, value] of entries) {
+      if (!fieldNamePattern.test(name)) {
+        throw new SystemdRuntimeError('notify_field_invalid', `${JSON.stringify(name)} is not a notification field name.`);
+      }
+      if (typeof value !== 'string' || /[\n\0]/.test(value)) {
+        throw new SystemdRuntimeError('notify_field_invalid', `The ${name} value must be a string without newline or NUL.`);
+      }
+    }
+    assertDescriptorList(descriptorsArg);
+    const payload = Buffer.from(entries.map(([name, value]) => `${name}=${value}`).join('\n'), 'utf8');
+    if (payload.length > notifyMessageMaximumBytes) {
+      throw new SystemdRuntimeError(
+        'notify_field_invalid',
+        `The message is ${payload.length} bytes; systemd reads at most ${notifyMessageMaximumBytes}.`,
+      );
+    }
+    sendDatagram(this.socketAddress, payload, descriptorsArg);
+  }
+}
+
+const assertDescriptorName = (nameArg: string): void => {
+  if (!isSystemdDescriptorName(nameArg, true)) {
+    throw new SystemdRuntimeError(
+      'descriptor_name_invalid',
+      'A descriptor name is 1–255 printable ASCII characters without ":".',
+    );
+  }
+};
+
+/** At most 253 valid descriptor numbers. */
+const assertDescriptorList = (descriptorsArg: readonly number[]): void => {
+  if (descriptorsArg.length > descriptorsPerMessageMaximum) {
+    throw new SystemdRuntimeError(
+      'descriptor_invalid',
+      `One message carries at most ${descriptorsPerMessageMaximum} descriptors.`,
+    );
+  }
+  descriptorsArg.forEach(assertSystemdDescriptor);
+};
+
+/** 1–253 valid descriptor numbers, as `FDSTORE=1` needs. */
+const assertStoredDescriptors = (descriptorsArg: readonly number[]): void => {
+  if (descriptorsArg.length === 0) {
+    throw new SystemdRuntimeError('descriptor_invalid', 'FDSTORE=1 needs at least one descriptor.');
+  }
+  assertDescriptorList(descriptorsArg);
+};
+
+/** `CLOCK_MONOTONIC` in microseconds, as `MONOTONIC_USEC=` expects. */
+const monotonicMicroseconds = (): bigint => {
+  const libc = systemdLibc();
+  const timespec = Buffer.alloc(16);
+  if (libc.functions.clock_gettime(libcConstants.CLOCK_MONOTONIC, timespec) !== 0) {
+    throw new SystemdRuntimeError('notify_failed', 'clock_gettime(CLOCK_MONOTONIC) failed.', { errno: libc.errno() });
+  }
+  return timespec.readBigInt64LE(0) * 1_000_000n + timespec.readBigInt64LE(8) / 1_000n;
+};
+
+// One block holds the whole message, so every pointer inside it stays valid while the block is
+// borrowed by the call: msghdr, iovec, sockaddr_un, control data, payload.
+const iovecOffset = 56;
+const addressOffset = 72;
+const controlOffset = 184;
+
+const sendDatagram = (addressArg: string, payloadArg: Buffer, descriptorsArg: readonly number[]): void => {
+  const libc = systemdLibc();
+  const space = descriptorsArg.length === 0 ? 0 : controlSpace(descriptorsArg.length);
+  const payloadOffset = controlOffset + space;
+  const block = Buffer.alloc(payloadOffset + payloadArg.length);
+  const base = libc.ffi.getRawPointer(block);
+  writeSocketAddress(block, addressOffset, addressArg);
+  payloadArg.copy(block, payloadOffset);
+  block.writeBigUInt64LE(base + BigInt(addressOffset), 0);
+  block.writeUInt32LE(socketAddressLength(addressArg), 8);
+  block.writeBigUInt64LE(base + BigInt(iovecOffset), 16);
+  block.writeBigUInt64LE(1n, 24);
+  block.writeBigUInt64LE(base + BigInt(payloadOffset), iovecOffset);
+  block.writeBigUInt64LE(BigInt(payloadArg.length), iovecOffset + 8);
+  if (space > 0) {
+    block.writeBigUInt64LE(base + BigInt(controlOffset), 32);
+    block.writeBigUInt64LE(BigInt(space), 40);
+    block.writeBigUInt64LE(BigInt(16 + 4 * descriptorsArg.length), controlOffset);
+    block.writeInt32LE(libcConstants.SOL_SOCKET, controlOffset + 8);
+    block.writeInt32LE(libcConstants.SCM_RIGHTS, controlOffset + 12);
+    descriptorsArg.forEach((descriptor, index) => block.writeInt32LE(descriptor, controlOffset + 16 + 4 * index));
+  }
+  const socket = libc.functions.socket(libcConstants.AF_UNIX, libcConstants.SOCK_DGRAM | libcConstants.SOCK_CLOEXEC, 0);
+  if (socket < 0) {
+    throw new SystemdRuntimeError('notify_failed', 'socket(AF_UNIX, SOCK_DGRAM) failed.', { errno: libc.errno() });
+  }
+  try {
+    let sent = libc.functions.sendmsg(socket, block, libcConstants.MSG_NOSIGNAL);
+    let errno = sent < 0n ? libc.errno() : 0;
+    while (sent < 0n && errno === libcConstants.EINTR) {
+      sent = libc.functions.sendmsg(socket, block, libcConstants.MSG_NOSIGNAL);
+      errno = sent < 0n ? libc.errno() : 0;
+    }
+    if (sent < 0n) {
+      throw new SystemdRuntimeError('notify_failed', `sendmsg to ${addressArg} failed.`, { errno });
+    }
+    if (sent !== BigInt(payloadArg.length)) {
+      throw new SystemdRuntimeError('notify_failed', `sendmsg to ${addressArg} sent ${sent} of ${payloadArg.length} bytes.`);
+    }
+  } finally {
+    // Linux releases the descriptor whatever close(2) reports; the socket is this call's alone.
+    libc.functions.close(socket);
+  }
+};

package/ts_systemdruntime/classes.systemdruntimeerror.ts

@@ -0,0 +1,53 @@
+/**
+ * Why a systemd runtime operation refused or failed:
+ *
+ * - `runtime_unsupported`: the runtime cannot make the call: Node.js older than 26, a platform
+ *   other than Linux on x64 or arm64, a C library other than glibc (`libc.so.6`), `node:ffi`
+ *   disabled (`--no-experimental-ffi`) or denied by the permission model (no `--allow-ffi`).
+ * - `notify_socket_invalid`: `NOTIFY_SOCKET` is not an `AF_UNIX` path or abstract name this
+ *   module can address (`vsock:` addresses included).
+ * - `notify_field_invalid`: a notification field name or value systemd would not parse, or a
+ *   message larger than systemd reads (4096 bytes).
+ * - `notify_failed`: the message could not be sent (`errno` names why).
+ * - `descriptor_name_invalid`: an `FDNAME=` systemd would refuse.
+ * - `descriptor_invalid`: a descriptor number that cannot exist, or a count outside 1–253.
+ * - `listen_environment_invalid`: `LISTEN_PID`, `LISTEN_FDS` or `LISTEN_FDNAMES` is malformed,
+ *   `LISTEN_FDS` names a descriptor at or above the process's hard `RLIMIT_NOFILE`, or
+ *   `getrlimit(RLIMIT_NOFILE)` failed, so the count cannot be bounded (`errno` names why).
+ * - `watchdog_environment_invalid`: `WATCHDOG_USEC` or `WATCHDOG_PID` is malformed.
+ * - `close_on_exec_failed`: a descriptor could not be marked close-on-exec (`errno` names why).
+ */
+export type TSystemdRuntimeErrorCode =
+  | 'runtime_unsupported'
+  | 'notify_socket_invalid'
+  | 'notify_field_invalid'
+  | 'notify_failed'
+  | 'descriptor_name_invalid'
+  | 'descriptor_invalid'
+  | 'listen_environment_invalid'
+  | 'watchdog_environment_invalid'
+  | 'close_on_exec_failed';
+
+export interface ISystemdRuntimeErrorOptions {
+  /** The C library's `errno` after the failed call, when a call failed. */
+  readonly errno?: number;
+  readonly cause?: unknown;
+}
+
+export class SystemdRuntimeError extends Error {
+  /** The C library's `errno` after the failed call, or null when no call failed. */
+  public readonly errno: number | null;
+
+  constructor(
+    public readonly code: TSystemdRuntimeErrorCode,
+    messageArg: string,
+    optionsArg: ISystemdRuntimeErrorOptions = {},
+  ) {
+    super(
+      `${messageArg}${optionsArg.errno === undefined ? '' : ` (errno ${optionsArg.errno})`}`,
+      optionsArg.cause === undefined ? undefined : { cause: optionsArg.cause },
+    );
+    this.name = 'SystemdRuntimeError';
+    this.errno = optionsArg.errno ?? null;
+  }
+}

package/ts_systemdruntime/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@push.rocks/smartdaemon/systemd-runtime`: the service side of systemd for a Node.js main
+ * process — `sd_notify(3)` messages with descriptors, `LISTEN_FDS` adoption with close-on-exec, and
+ * the watchdog interval — through glibc calls made with `node:ffi`. Requires Node.js 26 or later:
+ * importing it on an older Node.js throws `SystemdRuntimeError` `runtime_unsupported`.
+ */
+import { assertSystemdRuntimeNode } from './systemdruntime.libc.js';
+
+export * from './classes.systemdruntimeerror.js';
+export * from './classes.systemdnotifier.js';
+export {
+  type ISystemdListenDescriptor,
+  type ISystemdProcessEnvironmentOptions,
+  setCloseOnExec,
+  systemdListenDescriptorsStart,
+  takeSystemdListenDescriptors,
+  watchdogIntervalUsec,
+} from './systemdruntime.listen.js';
+export { systemdRuntimeNodeMajor } from './systemdruntime.libc.js';
+export { isSystemdDescriptorName, isSystemdNotifySocketAddress } from './systemdruntime.validation.js';
+
+assertSystemdRuntimeNode();