@push.rocks/smartdaemon 2.21.0 → 2.22.0

package/dist_ts_systemdruntime/systemdruntime.listen.js

@@ -0,0 +1,136 @@
+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;
+/**
+ * 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) => {
+    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, errnoArg) => 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 = () => {
+    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 === 0xffffffffffffffffn ? 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 = {}) => {
+    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 = [];
+    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 = {}) => {
+    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);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUubGlzdGVuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfc3lzdGVtZHJ1bnRpbWUvc3lzdGVtZHJ1bnRpbWUubGlzdGVuLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGtDQUFrQyxDQUFDO0FBQ3ZFLE9BQU8sRUFBRSxhQUFhLEVBQUUsV0FBVyxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDdEUsT0FBTyxFQUFFLHVCQUF1QixFQUFFLHVCQUF1QixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFFbEcsNEVBQTRFO0FBQzVFLE1BQU0sQ0FBQyxNQUFNLDZCQUE2QixHQUFHLENBQUMsQ0FBQztBQWdCL0M7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLGNBQWMsR0FBRyxDQUFDLGFBQXFCLEVBQVEsRUFBRTtJQUM1RCx1QkFBdUIsQ0FBQyxhQUFhLENBQUMsQ0FBQztJQUN2QyxNQUFNLElBQUksR0FBRyxXQUFXLEVBQUUsQ0FBQztJQUMzQixNQUFNLEVBQUUsS0FBSyxFQUFFLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQztJQUNqQyxNQUFNLEtBQUssR0FBRyxLQUFLLENBQUMsYUFBYSxFQUFFLGFBQWEsQ0FBQyxPQUFPLEVBQUUsQ0FBQyxDQUFDLENBQUM7SUFDN0QsSUFBSSxLQUFLLEdBQUcsQ0FBQyxFQUFFLENBQUM7UUFDZCxNQUFNLElBQUksbUJBQW1CLENBQUMsc0JBQXNCLEVBQUUsY0FBYyxhQUFhLGtCQUFrQixFQUFFO1lBQ25HLEtBQUssRUFBRSxJQUFJLENBQUMsS0FBSyxFQUFFO1NBQ3BCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFDRCxJQUFJLEtBQUssQ0FBQyxhQUFhLEVBQUUsYUFBYSxDQUFDLE9BQU8sRUFBRSxLQUFLLEdBQUcsYUFBYSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDO1FBQ3RGLE1BQU0sSUFBSSxtQkFBbUIs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

package/dist_ts_systemdruntime/systemdruntime.validation.d.ts

@@ -0,0 +1,13 @@
+/** `FDNAME_MAX`: the longest descriptor name systemd accepts. */
+export declare 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 declare const isSystemdDescriptorName: (nameArg: unknown, nonEmptyArg: boolean) => nameArg is string;
+/** An `AF_UNIX` notification address: an absolute path or an abstract name written `@name`. */
+export declare const isSystemdNotifySocketAddress: (addressArg: unknown) => addressArg is string;
+export declare const assertSystemdNotifySocketAddress: (addressArg: string) => void;
+export declare const isSystemdDescriptor: (descriptorArg: unknown) => descriptorArg is number;
+export declare const assertSystemdDescriptor: (descriptorArg: number) => void;

package/dist_ts_systemdruntime/systemdruntime.validation.js

@@ -0,0 +1,29 @@
+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, nonEmptyArg) => 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) => typeof addressArg === 'string' && /^[/@]./s.test(addressArg) && !addressArg.includes('\0') &&
+    Buffer.byteLength(addressArg, 'utf8') <= socketAddressMaximumBytes;
+export const assertSystemdNotifySocketAddress = (addressArg) => {
+    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) => typeof descriptorArg === 'number' && Number.isSafeInteger(descriptorArg) && descriptorArg >= 0 &&
+    descriptorArg <= descriptorMaximum;
+export const assertSystemdDescriptor = (descriptorArg) => {
+    if (!isSystemdDescriptor(descriptorArg)) {
+        throw new SystemdRuntimeError('descriptor_invalid', `${String(descriptorArg)} is not a descriptor number.`);
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUudmFsaWRhdGlvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3N5c3RlbWRydW50aW1lL3N5c3RlbWRydW50aW1lLnZhbGlkYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFDdkUsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFFckUsaUVBQWlFO0FBQ2pFLE1BQU0sQ0FBQyxNQUFNLDJCQUEyQixHQUFHLEdBQUcsQ0FBQztBQUUvQzs7OztHQUlHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsQ0FBQyxPQUFnQixFQUFFLFdBQW9CLEVBQXFCLEVBQUUsQ0FDbkcsT0FBTyxPQUFPLEtBQUssUUFBUSxJQUFJLE9BQU8sQ0FBQyxNQUFNLElBQUksMkJBQTJCO0lBQzVFLENBQUMsQ0FBQyxXQUFXLElBQUksT0FBTyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUMsSUFBSSx5QkFBeUIsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLENBQUM7QUFFbEYsK0ZBQStGO0FBQy9GLE1BQU0sQ0FBQyxNQUFNLDRCQUE0QixHQUFHLENBQUMsVUFBbUIsRUFBd0IsRUFBRSxDQUN4RixPQUFPLFVBQVUsS0FBSyxRQUFRLElBQUksU0FBUyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsSUFBSSxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDO0lBQzFGLE1BQU0sQ0FBQyxVQUFVLENBQUMsVUFBVSxFQUFFLE1BQU0sQ0FBQyxJQUFJLHlCQUF5QixDQUFDO0FBRXJFLE1BQU0sQ0FBQyxNQUFNLGdDQUFnQyxHQUFHLENBQUMsVUFBa0IsRUFBUSxFQUFFO0lBQzNFLElBQUksQ0FBQyw0QkFBNEIsQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDO1FBQzlDLE1BQU0sSUFBSSxtQkFBbUIsQ0FDM0IsdUJBQXVCLEVBQ3ZCLDhHQUE4RyxDQUMvRyxDQUFDO0lBQ0osQ0FBQztBQUNILENBQUMsQ0FBQztBQUVGLHlFQUF5RTtBQUN6RSxNQUFNLGlCQUFpQixHQUFHLGFBQWEsQ0FBQztBQUV4QyxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxDQUFDLGFBQXNCLEVBQTJCLEVBQUUsQ0FDckYsT0FBTyxhQUFhLEtBQUssUUFBUSxJQUFJLE1BQU0sQ0FBQyxhQUFhLENBQUMsYUFBYSxDQUFDLElBQUksYUFBYSxJQUFJLENBQUM7SUFDOUYsYUFBYSxJQUFJLGlCQUFpQixDQUFDO0FBRXJDLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLENBQUMsYUFBcUIsRUFBUSxFQUFFO0lBQ3JFLElBQUksQ0FBQyxtQkFBbUIsQ0FBQyxhQUFhLENBQUMsRUFBRSxDQUFDO1FBQ3hDLE1BQU0sSUFBSSxtQkFBbUIsQ0FBQyxvQkFBb0IsRUFBRSxHQUFHLE1BQU0sQ0FBQyxhQUFhLENBQUMsOEJBQThCLENBQUMsQ0FBQztJQUM5RyxDQUFDO0FBQ0gsQ0FBQyxDQUFDIn0=

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "@push.rocks/smartdaemon",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "private": false,
   "description": "Start scripts as long running daemons and manage them.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist_ts/index.d.ts",
+      "default": "./dist_ts/index.js"
+    },
+    "./systemd-runtime": {
+      "types": "./dist_ts_systemdruntime/index.d.ts",
+      "default": "./dist_ts_systemdruntime/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "type": "module",
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
@@ -26,10 +37,10 @@
   },
   "homepage": "https://code.foss.global/push.rocks/smartdaemon",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.1.2",
-    "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^7.1.0",
-    "@types/node": "^26.6.3"
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsrun": "^3.0.3",
+    "@git.zone/tstest": "^7.2.1",
+    "@types/node": "^26.6.4"
   },
   "dependencies": {
     "@push.rocks/lik": "^6.4.4",
@@ -41,6 +52,7 @@
   },
   "files": [
     "ts/**/*",
+    "ts_systemdruntime/**/*",
     "ts_web/**/*",
     "dist/**/*",
     "dist_*/**/*",
@@ -58,7 +70,7 @@
   ],
   "scripts": {
     "test": "tstest test/ --verbose --timeout 60",
-    "build": "tsbuild --web",
+    "build": "tsbuild tsfolders --web",
     "format": "gitzone format",
     "buildDocs": "tsdoc"
   }

package/readme.md

@@ -998,6 +998,106 @@ other process in the unit survives, so the main process must own their shutdown
 deliberate retention (as with `Delegate=yes` workloads). A successful systemd start still requires application readiness
 verification, and a completed stop alone does not prove database drain.
 
+### The service side: notifications and passed descriptors (`/systemd-runtime`, Node.js 26)
+
+The definitions above tell the manager what to expect; a Node.js main process answers it through
+the `@push.rocks/smartdaemon/systemd-runtime` subpath: `sd_notify(3)` messages (with descriptors
+for the store) and the descriptors the manager passes (`LISTEN_FDS`). Node.js has no `AF_UNIX`
+datagram socket and no `fcntl(2)`, so the subpath calls glibc through `node:ffi`:
+
+- It requires **Node.js 26 or later**. Importing it on an older Node.js throws
+  `SystemdRuntimeError` with code `runtime_unsupported`; the main entry is unaffected and keeps
+  its Node.js range. The package is ES modules: CommonJS can `require()` either entry only on a
+  Node.js that loads ES modules through `require()` by default (20.19+, 22.12+, 23+), where the
+  subpath throws the same `runtime_unsupported` below 26; an older Node.js throws `ERR_REQUIRE_ESM`.
+- It runs on Linux x64 and arm64 with glibc (`libc.so.6`). Elsewhere, and with `node:ffi`
+  unavailable (`--no-experimental-ffi`) or denied by the permission model, the first call that
+  needs libc throws `runtime_unsupported`. Under the permission model pass `--allow-ffi`.
+- `node:ffi` is experimental: loading it prints one `ExperimentalWarning`. A single executable
+  application suppresses it through its `execArgv` (`--disable-warning=ExperimentalWarning`).
+- libc is opened on first use. Outside systemd nothing is loaded: without `NOTIFY_SOCKET`
+  `SystemdNotifier.fromEnvironment()` returns null, and without `LISTEN_*` variables
+  `takeSystemdListenDescriptors()` returns an empty list.
+
+```typescript
+import {
+  SystemdNotifier,
+  takeSystemdListenDescriptors,
+  watchdogIntervalUsec,
+} from '@push.rocks/smartdaemon/systemd-runtime';
+
+// Descriptors passed for this process, numbered from 3, already close-on-exec.
+const passed = takeSystemdListenDescriptors(); // [{ descriptor: 3, name: 'pallet-router' }]
+const namespaceDescriptor = passed.find(({ name }) => name === 'pallet-router')?.descriptor ?? createNamespace();
+
+// null when no service manager listens; the caller decides what that means.
+const notifier = SystemdNotifier.fromEnvironment({ take: true });
+if (notifier) {
+  notifier.extendTimeout(60_000_000, 'replaying journal');
+  notifier.replaceDescriptors('pallet-router', [namespaceDescriptor], { poll: false });
+  notifier.ready('serving');
+  const interval = watchdogIntervalUsec();
+  if (interval !== null) setInterval(() => notifier.watchdog(), interval / 2000);
+}
+```
+
+| Call | Sends or does |
+| --- | --- |
+| `ready(status?)` | `READY=1` (and `STATUS=`) |
+| `status(text)` | `STATUS=` |
+| `stopping(status?)` | `STOPPING=1` |
+| `reloading(status?)` | `RELOADING=1` with `MONOTONIC_USEC=` (`CLOCK_MONOTONIC`); send `ready()` when done |
+| `watchdog()` | `WATCHDOG=1` |
+| `extendTimeout(usec, status?)` | `EXTEND_TIMEOUT_USEC=` |
+| `storeDescriptors(name, fds, { poll? })` | `FDSTORE=1`, `FDNAME=`, `FDPOLL=0` for `poll: false`; descriptors as `SCM_RIGHTS` |
+| `removeDescriptors(name)` | `FDSTOREREMOVE=1`, `FDNAME=` |
+| `replaceDescriptors(name, fds, { poll? })` | remove, then store: two messages, handled in order |
+| `send(fields, fds?)` | any `NAME=value` fields in insertion order |
+| `takeSystemdNotifySocket()` | removes `NOTIFY_SOCKET` from the environment and returns it validated, or null |
+| `takeSystemdListenDescriptors()` | removes `LISTEN_PID`/`LISTEN_FDS`/`LISTEN_FDNAMES`; for this process marks every passed descriptor close-on-exec and returns it with its name (`unknown` without names) |
+| `setCloseOnExec(fd)` | `fcntl(F_SETFD, FD_CLOEXEC)`, verified |
+| `watchdogIntervalUsec()` | `WATCHDOG_USEC` for this process (`WATCHDOG_PID`), or null |
+
+Every call is synchronous and either completes or throws `SystemdRuntimeError` (`code`, and
+`errno` when a libc call failed); nothing is dropped silently. systemd ignores a message it cannot
+parse without telling the sender, so the notifier refuses it first: field names are upper-case,
+values carry no newline or NUL, a message is at most 4096 bytes (`notify_field_invalid`); a
+descriptor name is 1–255 printable ASCII characters without `:` (`descriptor_name_invalid`); one
+message carries 1–253 descriptors (`descriptor_invalid`). `NOTIFY_SOCKET` must be an absolute
+path or an abstract name (`@name`) of at most 107 bytes; anything else, `vsock:` addresses
+included, is `notify_socket_invalid`. A send the kernel refuses is `notify_failed` with its errno
+(`ENOENT` for a missing path, `ECONNREFUSED` for an abstract name nobody holds). `LISTEN_*`
+variables naming another process are removed and nothing else is touched; a partial or malformed
+set (`LISTEN_FDS` not a positive integer, a names list of another length) is
+`listen_environment_invalid` before any descriptor is touched, and a passed descriptor that is not
+open is `close_on_exec_failed`.
+
+`LISTEN_FDS` is also bounded by the process's hard `RLIMIT_NOFILE` before any descriptor is touched:
+a count whose last descriptor (`2 + count`) is at or above that limit is
+`listen_environment_invalid`. No descriptor systemd passed can lie at or above the hard limit,
+because it moves them into place with `fcntl(F_DUPFD)` (which refuses a number at or above the soft
+limit) after applying the unit's limits; a wrapper that lowers its hard limit below a passed
+descriptor before starting Node.js is refused. The hard limit can be as large as `fs.nr_open`
+(`LimitNOFILE=infinity`), so nothing is allocated per counted descriptor up front: like
+`sd_listen_fds(3)`, the descriptors are marked one by one from 3, the first that is not open throws
+`close_on_exec_failed` (the ones before it keep the flag), and the list grows only with open
+descriptors.
+
+Sends are blocking `sendmsg(2)` calls on a fresh `AF_UNIX` datagram socket, the same as
+`sd_notify(3)`: when the manager's receive queue is full, the call waits for room and the event loop
+stalls for that time.
+
+`node:ffi` has no errno API: the subpath reads glibc's thread-local `errno` through
+`__errno_location()` immediately after the failed call. Node.js itself calls libuv's
+`uv_disable_stdio_inheritance()` at startup (`InitializeNodeWithArgsInternal()` in `src/node.cc`;
+`deps/uv/src/unix/core.c`, Node.js 25.9.0 and 26.11.1), which marks descriptors 0–15 close-on-exec
+and continues past 15 until the first descriptor that is not open. The subpath still sets and
+verifies the flag on every passed descriptor, as `sd_listen_fds(3)` does.
+
+`test/test.systemdruntimeunit.node.ts` proves the subpath under a real `Type=notify` unit of the
+caller's user manager (`systemd-run --user`), and skips with the reason without Node.js 26 or a
+user manager.
+
 ### Starting a program in its own transient scope
 
 A service that launches a long-lived program keeps that program in its own
@@ -1254,6 +1354,8 @@ console.log(template); // View generated systemd unit file
 - **systemd 240 or later** for installing a definition with an `append` output (`standardOutput` or
   `standardError`), refused the same way
 - **Node.js**: Version 14.x or higher
+- **Node.js 26 or later** for the `@push.rocks/smartdaemon/systemd-runtime` subpath (`node:ffi`), on Linux
+  x64 or arm64 with glibc
 - **Permissions**: Either root access or properly configured sudo
 
 ## ⚙️ Generated Systemd Service Files

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartdaemon',
-  version: '2.21.0',
+  version: '2.22.0',
   description: 'Start scripts as long running daemons and manage them.'
 }

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);
+  }
+};