@push.rocks/smartdaemon 2.21.0 → 2.22.0

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();

package/ts_systemdruntime/systemdruntime.libc.ts

@@ -0,0 +1,121 @@
+import type * as ffi from 'node:ffi';
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+
+/** The first Node.js major with `node:ffi`, which this module calls libc through. */
+export const systemdRuntimeNodeMajor = 26;
+
+/** Internal: refuses a Node.js older than `systemdRuntimeNodeMajor`; the subpath runs it on import. */
+export const assertSystemdRuntimeNode = (versionArg: string = process.versions.node): void => {
+  const major = Number(/^(\d+)\./.exec(versionArg)?.[1]);
+  if (!(major >= systemdRuntimeNodeMajor)) {
+    throw new SystemdRuntimeError(
+      'runtime_unsupported',
+      `@push.rocks/smartdaemon/systemd-runtime requires Node.js ${systemdRuntimeNodeMajor} or later; this is Node.js ${versionArg}.`,
+    );
+  }
+};
+
+/**
+ * The generic Linux values both qualified targets (x86_64 and aarch64, glibc) use. The structure
+ * layouts below are the LP64 glibc ones, identical on both:
+ *
+ * - `sockaddr_un`: `sa_family_t` (u16) at 0, `sun_path[108]` at 2.
+ * - `iovec` (16 bytes): `iov_base` at 0, `iov_len` at 8.
+ * - `msghdr` (56 bytes): `msg_name` at 0, `msg_namelen` (u32) at 8, `msg_iov` at 16, `msg_iovlen`
+ *   at 24, `msg_control` at 32, `msg_controllen` at 40, `msg_flags` at 48.
+ * - `cmsghdr`: `cmsg_len` (size_t) at 0, `cmsg_level` at 8, `cmsg_type` at 12, data at 16;
+ *   `CMSG_LEN(n)` is 16 + n and `CMSG_SPACE(n)` 16 + n rounded up to 8.
+ * - `timespec` (16 bytes): `tv_sec` at 0, `tv_nsec` at 8.
+ * - `rlimit` (16 bytes): `rlim_cur` (u64) at 0, `rlim_max` (u64) at 8; `RLIM_INFINITY` is all ones.
+ */
+export const libcConstants = {
+  AF_UNIX: 1,
+  SOCK_DGRAM: 2,
+  SOCK_CLOEXEC: 0o2000000,
+  SOL_SOCKET: 1,
+  SCM_RIGHTS: 1,
+  MSG_NOSIGNAL: 0x4000,
+  F_GETFD: 1,
+  F_SETFD: 2,
+  FD_CLOEXEC: 1,
+  CLOCK_MONOTONIC: 1,
+  EINTR: 4,
+  RLIMIT_NOFILE: 7,
+} as const;
+
+/** `sun_path` is 108 bytes; an address of up to 107 bytes keeps a path's terminating NUL. */
+export const socketAddressMaximumBytes = 107;
+
+/** The kernel's `SCM_MAX_FD`: the most descriptors one `SCM_RIGHTS` message carries. */
+export const descriptorsPerMessageMaximum = 253;
+
+const libcFunctions = {
+  socket: { arguments: ['int32', 'int32', 'int32'], return: 'int32' },
+  sendmsg: { arguments: ['int32', 'pointer', 'int32'], return: 'int64' },
+  close: { arguments: ['int32'], return: 'int32' },
+  // fcntl(2) is variadic; its third argument is an int for F_GETFD and F_SETFD.
+  fcntl: { arguments: ['int32', 'int32', 'int32'], return: 'int32' },
+  clock_gettime: { arguments: ['int32', 'pointer'], return: 'int32' },
+  getrlimit: { arguments: ['int32', 'pointer'], return: 'int32' },
+  __errno_location: { arguments: [], return: 'pointer' },
+} as const satisfies ffi.FunctionDefinitions;
+
+export interface ISystemdLibc {
+  readonly functions: ffi.WrappedFunctionsFromDefinitions<typeof libcFunctions>;
+  readonly ffi: typeof ffi;
+  /**
+   * The calling thread's `errno`, read through glibc's `__errno_location()`. `node:ffi` has no errno
+   * API; read it immediately after the failed call, before anything else runs on the thread.
+   */
+  errno(): number;
+}
+
+let loaded: ISystemdLibc | null = null;
+
+/**
+ * glibc, opened through `node:ffi` on first use and kept for the process lifetime. Loading
+ * `node:ffi` emits Node's ExperimentalWarning once.
+ */
+export const systemdLibc = (): ISystemdLibc => {
+  if (loaded !== null) return loaded;
+  if (process.platform !== 'linux' || (process.arch !== 'x64' && process.arch !== 'arm64')) {
+    throw new SystemdRuntimeError(
+      'runtime_unsupported',
+      `The systemd runtime supports Linux on x64 and arm64; this is ${process.platform} on ${process.arch}.`,
+    );
+  }
+  const ffiModule: typeof ffi | undefined = process.getBuiltinModule('node:ffi');
+  if (ffiModule === undefined) {
+    throw new SystemdRuntimeError('runtime_unsupported', 'node:ffi is not available (disabled by --no-experimental-ffi?).');
+  }
+  let functions: ffi.WrappedFunctionsFromDefinitions<typeof libcFunctions>;
+  try {
+    functions = ffiModule.dlopen('libc.so.6', libcFunctions).functions;
+  } catch (error) {
+    throw new SystemdRuntimeError(
+      'runtime_unsupported',
+      'glibc (libc.so.6) could not be opened through node:ffi; under the permission model pass --allow-ffi.',
+      { cause: error },
+    );
+  }
+  loaded = Object.freeze({
+    functions,
+    ffi: ffiModule,
+    errno: () => ffiModule.getInt32(functions.__errno_location(), 0),
+  });
+  return loaded;
+};
+
+/** The `msg_namelen` of an `AF_UNIX` address: a path keeps its NUL; an abstract name has none. */
+export const socketAddressLength = (addressArg: string): number =>
+  2 + Buffer.byteLength(addressArg, 'utf8') + (addressArg.startsWith('/') ? 1 : 0);
+
+/** Writes a `sockaddr_un` at `offsetArg`; an abstract name's leading `@` becomes its NUL. */
+export const writeSocketAddress = (bufferArg: Buffer, offsetArg: number, addressArg: string): void => {
+  bufferArg.writeUInt16LE(libcConstants.AF_UNIX, offsetArg);
+  bufferArg.write(addressArg, offsetArg + 2, 'utf8');
+  if (addressArg.startsWith('@')) bufferArg[offsetArg + 2] = 0;
+};
+
+/** `CMSG_SPACE` for `countArg` descriptors. */
+export const controlSpace = (countArg: number): number => 16 + ((4 * countArg + 7) & ~7);

package/ts_systemdruntime/systemdruntime.listen.ts

@@ -0,0 +1,153 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import { libcConstants, systemdLibc } from './systemdruntime.libc.js';
+import { assertSystemdDescriptor, isSystemdDescriptorName } from './systemdruntime.validation.js';
+
+/** sd_listen_fds(3): `SD_LISTEN_FDS_START`, the first passed descriptor. */
+export const systemdListenDescriptorsStart = 3;
+
+export interface ISystemdProcessEnvironmentOptions {
+  /** The environment to read; `process.env` by default. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** The process the variables must name; `process.pid` by default. */
+  readonly pid?: number;
+}
+
+/** One descriptor the service manager passed: its number and its `LISTEN_FDNAMES` entry. */
+export interface ISystemdListenDescriptor {
+  readonly descriptor: number;
+  /** The `FDNAME=` it was stored under, the socket unit's `FileDescriptorName=`, or `unknown`. */
+  readonly name: string;
+}
+
+/**
+ * Marks one open descriptor close-on-exec (`fcntl(F_SETFD, FD_CLOEXEC)`) and verifies the flag,
+ * so no child process inherits it. Throws `close_on_exec_failed` with `errno` when the descriptor
+ * is not open or the flag does not hold.
+ */
+export const setCloseOnExec = (descriptorArg: number): void => {
+  assertSystemdDescriptor(descriptorArg);
+  const libc = systemdLibc();
+  const { fcntl } = libc.functions;
+  const flags = fcntl(descriptorArg, libcConstants.F_GETFD, 0);
+  if (flags < 0) {
+    throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} cannot be read.`, {
+      errno: libc.errno(),
+    });
+  }
+  if (fcntl(descriptorArg, libcConstants.F_SETFD, flags | libcConstants.FD_CLOEXEC) < 0) {
+    throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} cannot be marked close-on-exec.`, {
+      errno: libc.errno(),
+    });
+  }
+  if ((fcntl(descriptorArg, libcConstants.F_GETFD, 0) & libcConstants.FD_CLOEXEC) === 0) {
+    throw new SystemdRuntimeError('close_on_exec_failed', `Descriptor ${descriptorArg} did not keep close-on-exec.`);
+  }
+};
+
+const positiveIntegerPattern = /^[1-9][0-9]*$/;
+/** sd_listen_fds(3) refuses a count above `INT_MAX - SD_LISTEN_FDS_START`. */
+const listenDescriptorsMaximum = 2_147_483_647 - systemdListenDescriptorsStart;
+
+const invalidListen = (messageArg: string, errnoArg?: number) =>
+  new SystemdRuntimeError('listen_environment_invalid', messageArg, errnoArg === undefined ? {} : { errno: errnoArg });
+
+/**
+ * The process's hard `RLIMIT_NOFILE` (`getrlimit(2)`), or null for `RLIM_INFINITY`. No descriptor
+ * the manager passed can lie at or above it: systemd moves passed descriptors into place with
+ * `fcntl(F_DUPFD)` after applying the unit's limits (`shift_fds()` after `setrlimit_closest_all()` in
+ * v255 `src/core/exec-invoke.c`), `F_DUPFD` refuses a number at or above the soft limit, the soft
+ * limit never exceeds the hard one, and an unprivileged process cannot raise the hard one.
+ */
+const descriptorHardLimit = (): bigint | null => {
+  const libc = systemdLibc();
+  const rlimit = Buffer.alloc(16);
+  if (libc.functions.getrlimit(libcConstants.RLIMIT_NOFILE, rlimit) !== 0) {
+    throw invalidListen('getrlimit(RLIMIT_NOFILE) failed, so LISTEN_FDS cannot be bounded.', libc.errno());
+  }
+  const hard = rlimit.readBigUInt64LE(8);
+  return hard === 0xffff_ffff_ffff_ffffn ? null : hard;
+};
+
+/**
+ * Takes the descriptors the service manager passed this process (sd_listen_fds_with_names(3)):
+ * socket-activation sockets and descriptor-store entries, numbered from 3.
+ *
+ * `LISTEN_PID`, `LISTEN_FDS` and `LISTEN_FDNAMES` always leave the environment, so no child sees
+ * them. Without them, or with `LISTEN_PID` naming another process (variables inherited from a
+ * parent), it returns an empty list and touches no descriptor. For this process every passed
+ * descriptor is marked close-on-exec before the list returns. Without `LISTEN_FDNAMES` each name is
+ * `unknown`, as in systemd.
+ *
+ * Throws `listen_environment_invalid` before touching any descriptor for a partial or malformed set
+ * (a count that is not a positive integer, a count whose last descriptor, `2 + count`, is at or
+ * above the process's hard `RLIMIT_NOFILE`, a names list whose length differs from the count, an
+ * invalid name), and with `errno` when `getrlimit(2)` fails. Descriptors are then marked one by one
+ * from 3, and memory grows only with descriptors proven open: the first passed descriptor that is
+ * not open throws `close_on_exec_failed`, as `sd_listen_fds(3)` fails on it; descriptors before it
+ * keep the flag.
+ */
+export const takeSystemdListenDescriptors = (
+  optionsArg: ISystemdProcessEnvironmentOptions = {},
+): readonly ISystemdListenDescriptor[] => {
+  const env = optionsArg.env ?? process.env;
+  const pid = optionsArg.pid ?? process.pid;
+  const listenPid = env.LISTEN_PID;
+  const listenFds = env.LISTEN_FDS;
+  const listenFdNames = env.LISTEN_FDNAMES;
+  delete env.LISTEN_PID;
+  delete env.LISTEN_FDS;
+  delete env.LISTEN_FDNAMES;
+  if (listenPid === undefined && listenFds === undefined && listenFdNames === undefined) return Object.freeze([]);
+  if (listenPid === undefined || !positiveIntegerPattern.test(listenPid)) {
+    throw invalidListen('LISTEN_PID must name a process.');
+  }
+  if (listenPid !== String(pid)) return Object.freeze([]);
+  if (listenFds === undefined || !positiveIntegerPattern.test(listenFds) || Number(listenFds) > listenDescriptorsMaximum) {
+    throw invalidListen('LISTEN_FDS must be a positive descriptor count.');
+  }
+  const count = Number(listenFds);
+  // The cheap early bound: the last passed descriptor is 2 + count.
+  const hardLimit = descriptorHardLimit();
+  if (hardLimit !== null && BigInt(systemdListenDescriptorsStart + count) > hardLimit) {
+    throw invalidListen(`LISTEN_FDS passes ${count} descriptors; descriptor ${systemdListenDescriptorsStart + count - 1} is at or above this process's hard RLIMIT_NOFILE (${hardLimit}).`);
+  }
+  // Names, when given, are checked before any descriptor; the list is bounded by the variable's length.
+  const names = listenFdNames === undefined ? null : listenFdNames.split(':');
+  if (names !== null) {
+    if (names.length !== count) throw invalidListen(`LISTEN_FDNAMES names ${names.length} descriptors; LISTEN_FDS passes ${count}.`);
+    if (!names.every((name) => isSystemdDescriptorName(name, false))) throw invalidListen('LISTEN_FDNAMES holds an invalid name.');
+  }
+  // Nothing scales with the count before a descriptor is proven open: as in sd_listen_fds(3), the
+  // first descriptor that is not open ends the walk with close_on_exec_failed.
+  const descriptors: ISystemdListenDescriptor[] = [];
+  for (let index = 0; index < count; index++) {
+    const descriptor = systemdListenDescriptorsStart + index;
+    setCloseOnExec(descriptor);
+    descriptors.push(Object.freeze({ descriptor, name: names === null ? 'unknown' : names[index] }));
+  }
+  return Object.freeze(descriptors);
+};
+
+/**
+ * The watchdog interval the manager expects `WATCHDOG=1` within (`WATCHDOG_USEC`, sd_watchdog_enabled(3)),
+ * in microseconds; null when the unit has no watchdog or `WATCHDOG_PID` names another process.
+ * Reads the environment without changing it. Throws `watchdog_environment_invalid` for a malformed
+ * value.
+ */
+export const watchdogIntervalUsec = (optionsArg: ISystemdProcessEnvironmentOptions = {}): number | null => {
+  const env = optionsArg.env ?? process.env;
+  const pid = optionsArg.pid ?? process.pid;
+  const usec = env.WATCHDOG_USEC;
+  const watchdogPid = env.WATCHDOG_PID;
+  if (usec === undefined) return null;
+  if (!positiveIntegerPattern.test(usec) || !Number.isSafeInteger(Number(usec))) {
+    throw new SystemdRuntimeError('watchdog_environment_invalid', 'WATCHDOG_USEC must be a positive integer.');
+  }
+  if (watchdogPid !== undefined) {
+    if (!positiveIntegerPattern.test(watchdogPid)) {
+      throw new SystemdRuntimeError('watchdog_environment_invalid', 'WATCHDOG_PID must name a process.');
+    }
+    if (watchdogPid !== String(pid)) return null;
+  }
+  return Number(usec);
+};

package/ts_systemdruntime/systemdruntime.validation.ts

@@ -0,0 +1,41 @@
+import { SystemdRuntimeError } from './classes.systemdruntimeerror.js';
+import { socketAddressMaximumBytes } from './systemdruntime.libc.js';
+
+/** `FDNAME_MAX`: the longest descriptor name systemd accepts. */
+export const descriptorNameMaximumLength = 255;
+
+/**
+ * systemd's `fdname_is_valid()` (src/basic/fd-util.c, v255): printable ASCII except `:`, at most
+ * 255 characters. systemd also admits the empty name; `nonEmptyArg` refuses it where a name has to
+ * identify a descriptor.
+ */
+export const isSystemdDescriptorName = (nameArg: unknown, nonEmptyArg: boolean): nameArg is string =>
+  typeof nameArg === 'string' && nameArg.length <= descriptorNameMaximumLength &&
+  (!nonEmptyArg || nameArg.length > 0) && /^[\x20-\x39\x3b-\x7e]*$/.test(nameArg);
+
+/** An `AF_UNIX` notification address: an absolute path or an abstract name written `@name`. */
+export const isSystemdNotifySocketAddress = (addressArg: unknown): addressArg is string =>
+  typeof addressArg === 'string' && /^[/@]./s.test(addressArg) && !addressArg.includes('\0') &&
+  Buffer.byteLength(addressArg, 'utf8') <= socketAddressMaximumBytes;
+
+export const assertSystemdNotifySocketAddress = (addressArg: string): void => {
+  if (!isSystemdNotifySocketAddress(addressArg)) {
+    throw new SystemdRuntimeError(
+      'notify_socket_invalid',
+      'NOTIFY_SOCKET must be an absolute AF_UNIX path or an abstract name (@name) of at most 107 bytes without NUL.',
+    );
+  }
+};
+
+/** The largest descriptor number the kernel can hand out (`INT_MAX`). */
+const descriptorMaximum = 2_147_483_647;
+
+export const isSystemdDescriptor = (descriptorArg: unknown): descriptorArg is number =>
+  typeof descriptorArg === 'number' && Number.isSafeInteger(descriptorArg) && descriptorArg >= 0 &&
+  descriptorArg <= descriptorMaximum;
+
+export const assertSystemdDescriptor = (descriptorArg: number): void => {
+  if (!isSystemdDescriptor(descriptorArg)) {
+    throw new SystemdRuntimeError('descriptor_invalid', `${String(descriptorArg)} is not a descriptor number.`);
+  }
+};