@push.rocks/smartdaemon 3.0.0 → 3.2.0

package/dist_ts_systemdruntime/systemdruntime.libc.d.ts

@@ -1,6 +1,13 @@
 import type * as ffi from 'node:ffi';
 /** The first Node.js major with `node:ffi`, which this module calls libc through. */
 export declare const systemdRuntimeNodeMajor = 26;
+/**
+ * Internal: builds the `runtime_unsupported` error of a subpath that calls libc through this
+ * loader (`systemd-runtime`, `file-lock`), so each subpath refuses with its own error class.
+ */
+export type TLibcUnsupportedError = (messageArg: string, causeArg?: unknown) => Error;
+/** Internal: refuses a Node.js older than `systemdRuntimeNodeMajor`; each libc subpath runs it on import. */
+export declare const assertLibcNode: (subpathArg: string, unsupportedArg: TLibcUnsupportedError, versionArg?: string) => void;
 /** Internal: refuses a Node.js older than `systemdRuntimeNodeMajor`; the subpath runs it on import. */
 export declare const assertSystemdRuntimeNode: (versionArg?: string) => void;
 /**
@@ -15,6 +22,8 @@ export declare const assertSystemdRuntimeNode: (versionArg?: string) => void;
  *   `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.
+ *
+ * `EWOULDBLOCK` is `EAGAIN` (11) on both.
  */
 export declare const libcConstants: {
     readonly AF_UNIX: 1;
@@ -28,7 +37,11 @@ export declare const libcConstants: {
     readonly FD_CLOEXEC: 1;
     readonly CLOCK_MONOTONIC: 1;
     readonly EINTR: 4;
+    readonly EWOULDBLOCK: 11;
     readonly RLIMIT_NOFILE: 7;
+    readonly LOCK_EX: 2;
+    readonly LOCK_NB: 4;
+    readonly LOCK_UN: 8;
 };
 /** `sun_path` is 108 bytes; an address of up to 107 bytes keeps a path's terminating NUL. */
 export declare const socketAddressMaximumBytes = 107;
@@ -59,6 +72,10 @@ declare const libcFunctions: {
         readonly arguments: readonly ["int32", "pointer"];
         readonly return: 'int32';
     };
+    readonly flock: {
+        readonly arguments: readonly ["int32", "int32"];
+        readonly return: 'int32';
+    };
     readonly __errno_location: {
         readonly arguments: readonly [];
         readonly return: 'pointer';
@@ -74,10 +91,12 @@ export interface ISystemdLibc {
     errno(): number;
 }
 /**
- * glibc, opened through `node:ffi` on first use and kept for the process lifetime. Loading
- * `node:ffi` emits Node's ExperimentalWarning once.
+ * glibc, opened through `node:ffi` on first use and kept for the process lifetime: the one libc
+ * loader of the package, shared by the `systemd-runtime` and `file-lock` subpaths. A refusal is
+ * built by `unsupportedArg`, the calling subpath's `runtime_unsupported` error. Loading `node:ffi`
+ * emits Node's ExperimentalWarning once.
  */
-export declare const systemdLibc: () => ISystemdLibc;
+export declare const systemdLibc: (unsupportedArg?: TLibcUnsupportedError) => ISystemdLibc;
 /** The `msg_namelen` of an `AF_UNIX` address: a path keeps its NUL; an abstract name has none. */
 export declare const socketAddressLength: (addressArg: string) => number;
 /** Writes a `sockaddr_un` at `offsetArg`; an abstract name's leading `@` becomes its NUL. */

package/dist_ts_systemdruntime/systemdruntime.libc.js

@@ -1,13 +1,16 @@
 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 = process.versions.node) => {
+const systemdRuntimeUnsupported = (messageArg, causeArg) => new SystemdRuntimeError('runtime_unsupported', messageArg, causeArg === undefined ? {} : { cause: causeArg });
+/** Internal: refuses a Node.js older than `systemdRuntimeNodeMajor`; each libc subpath runs it on import. */
+export const assertLibcNode = (subpathArg, unsupportedArg, versionArg = process.versions.node) => {
     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}.`);
+        throw unsupportedArg(`@push.rocks/smartdaemon/${subpathArg} requires Node.js ${systemdRuntimeNodeMajor} or later; this is Node.js ${versionArg}.`);
     }
 };
+/** Internal: refuses a Node.js older than `systemdRuntimeNodeMajor`; the subpath runs it on import. */
+export const assertSystemdRuntimeNode = (versionArg = process.versions.node) => assertLibcNode('systemd-runtime', systemdRuntimeUnsupported, 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:
@@ -20,6 +23,8 @@ export const assertSystemdRuntimeNode = (versionArg = process.versions.node) =>
  *   `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.
+ *
+ * `EWOULDBLOCK` is `EAGAIN` (11) on both.
  */
 export const libcConstants = {
     AF_UNIX: 1,
@@ -33,7 +38,11 @@ export const libcConstants = {
     FD_CLOEXEC: 1,
     CLOCK_MONOTONIC: 1,
     EINTR: 4,
+    EWOULDBLOCK: 11,
     RLIMIT_NOFILE: 7,
+    LOCK_EX: 2,
+    LOCK_NB: 4,
+    LOCK_UN: 8,
 };
 /** `sun_path` is 108 bytes; an address of up to 107 bytes keeps a path's terminating NUL. */
 export const socketAddressMaximumBytes = 107;
@@ -47,29 +56,32 @@ const libcFunctions = {
     fcntl: { arguments: ['int32', 'int32', 'int32'], return: 'int32' },
     clock_gettime: { arguments: ['int32', 'pointer'], return: 'int32' },
     getrlimit: { arguments: ['int32', 'pointer'], return: 'int32' },
+    flock: { arguments: ['int32', 'int32'], return: 'int32' },
     __errno_location: { arguments: [], return: 'pointer' },
 };
 let loaded = null;
 /**
- * glibc, opened through `node:ffi` on first use and kept for the process lifetime. Loading
- * `node:ffi` emits Node's ExperimentalWarning once.
+ * glibc, opened through `node:ffi` on first use and kept for the process lifetime: the one libc
+ * loader of the package, shared by the `systemd-runtime` and `file-lock` subpaths. A refusal is
+ * built by `unsupportedArg`, the calling subpath's `runtime_unsupported` error. Loading `node:ffi`
+ * emits Node's ExperimentalWarning once.
  */
-export const systemdLibc = () => {
+export const systemdLibc = (unsupportedArg = systemdRuntimeUnsupported) => {
     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}.`);
+        throw unsupportedArg(`glibc calls through node:ffi support Linux on x64 and arm64; this is ${process.platform} on ${process.arch}.`);
     }
     const ffiModule = process.getBuiltinModule('node:ffi');
     if (ffiModule === undefined) {
-        throw new SystemdRuntimeError('runtime_unsupported', 'node:ffi is not available (disabled by --no-experimental-ffi?).');
+        throw unsupportedArg('node:ffi is not available (disabled by --no-experimental-ffi?).');
     }
     let functions;
     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 });
+        throw unsupportedArg('glibc (libc.so.6) could not be opened through node:ffi; under the permission model pass --allow-ffi.', error);
     }
     loaded = Object.freeze({
         functions,
@@ -89,4 +101,4 @@ export const writeSocketAddress = (bufferArg, offsetArg, addressArg) => {
 };
 /** `CMSG_SPACE` for `countArg` descriptors. */
 export const controlSpace = (countArg) => 16 + ((4 * countArg + 7) & ~7);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUubGliYy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3N5c3RlbWRydW50aW1lL3N5c3RlbWRydW50aW1lLmxpYmMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFFdkUscUZBQXFGO0FBQ3JGLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLEVBQUUsQ0FBQztBQUUxQyx1R0FBdUc7QUFDdkcsTUFBTSxDQUFDLE1BQU0sd0JBQXdCLEdBQUcsQ0FBQyxVQUFVLEdBQVcsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQVEsRUFBRTtJQUMzRixNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDdkQsSUFBSSxDQUFDLENBQUMsS0FBSyxJQUFJLHVCQUF1QixDQUFDLEVBQUUsQ0FBQztRQUN4QyxNQUFNLElBQUksbUJBQW1CLENBQzNCLHFCQUFxQixFQUNyQiw0REFBNEQsdUJBQXVCLDhCQUE4QixVQUFVLEdBQUcsQ0FDL0gsQ0FBQztJQUNKLENBQUM7QUFDSCxDQUFDLENBQUM7QUFFRjs7Ozs7Ozs7Ozs7O0dBWUc7QUFDSCxNQUFNLENBQUMsTUFBTSxhQUFhLEdBQUc7SUFDM0IsT0FBTyxFQUFFLENBQUM7SUFDVixVQUFVLEVBQUUsQ0FBQztJQUNiLFlBQVksRUFBRSxTQUFTO0lBQ3ZCLFVBQVUsRUFBRSxDQUFDO0lBQ2IsVUFBVSxFQUFFLENBQUM7SUFDYixZQUFZLEVBQUUsTUFBTTtJQUNwQixPQUFPLEVBQUUsQ0FBQztJQUNWLE9BQU8sRUFBRSxDQUFDO0lBQ1YsVUFBVSxFQUFFLENBQUM7SUFDYixlQUFlLEVBQUUsQ0FBQztJQUNsQixLQUFLLEVBQUUsQ0FBQztJQUNSLGFBQWEsRUFBRSxDQUFDO0NBQ1IsQ0FBQztBQUVY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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUubGliYy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3N5c3RlbWRydW50aW1lL3N5c3RlbWRydW50aW1lLmxpYmMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFFdkUscUZBQXFGO0FBQ3JGLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLEVBQUUsQ0FBQztBQVExQyxNQUFNLHlCQUF5QixHQUEwQixDQUFDLFVBQVUsRUFBRSxRQUFRLEVBQUUsRUFBRSxDQUNoRixJQUFJLG1CQUFtQixDQUFDLHFCQUFxQixFQUFFLFVBQVUsRUFBRSxRQUFRLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7QUFFaEgsNkdBQTZHO0FBQzdHLE1BQU0sQ0FBQyxNQUFNLGNBQWMsR0FBRyxDQUM1QixVQUFrQixFQUNsQixjQUFxQyxFQUNyQyxVQUFVLEdBQVcsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQ3BDLEVBQUU7SUFDUixNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDdkQsSUFBSSxDQUFDLENBQUMsS0FBSyxJQUFJLHVCQUF1QixDQUFDLEVBQUUsQ0FBQztRQUN4QyxNQUFNLGNBQWMsQ0FDbEIsMkJBQTJCLFVBQVUscUJBQXFCLHVCQUF1Qiw4QkFBOEIsVUFBVSxHQUFHLENBQzdILENBQUM7SUFDSixDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBRUYsdUdBQXVHO0FBQ3ZHLE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLENBQUMsVUFBVSxHQUFXLE9BQU8sQ0FBQyxRQUFRLENBQUMsSUFBSSxFQUFRLEVBQUUsQ0FDM0YsY0FBYyxDQUFD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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdaemon",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "private": false,
   "description": "Start scripts as long running daemons and manage them.",
   "main": "dist_ts/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist_ts_systemdruntime/index.d.ts",
       "default": "./dist_ts_systemdruntime/index.js"
     },
+    "./file-lock": {
+      "types": "./dist_ts_filelock/index.d.ts",
+      "default": "./dist_ts_filelock/index.js"
+    },
     "./package.json": "./package.json"
   },
   "type": "module",
@@ -37,10 +41,8 @@
   },
   "homepage": "https://code.foss.global/push.rocks/smartdaemon",
   "devDependencies": {
-    "@git.zone/tsbuild": "^6.0.2",
-    "@git.zone/tsrun": "^3.0.3",
-    "@git.zone/tstest": "^8.0.0",
-    "@types/node": "^26.6.4"
+    "@git.zone/tsrepo": "^2.1.0",
+    "@types/node": "^26.6.6"
   },
   "dependencies": {
     "@push.rocks/lik": "^6.4.4",
@@ -52,6 +54,7 @@
   "files": [
     "ts/**/*",
     "ts_systemdruntime/**/*",
+    "ts_filelock/**/*",
     "ts_web/**/*",
     "dist/**/*",
     "dist_*/**/*",
@@ -68,9 +71,9 @@
     "last 1 chrome versions"
   ],
   "scripts": {
-    "test": "tstest test/ --verbose --timeout 60",
-    "build": "tsbuild tsfolders --web",
+    "test": "tsrepo test test/ --verbose --timeout 60",
+    "build": "tsrepo build tsfolders --web",
     "format": "gitzone format",
-    "buildDocs": "tsdoc"
+    "buildDocs": "tsrepo docs"
   }
 }

package/readme.md

@@ -293,6 +293,49 @@ store needs systemd 254 or later: the call reads the manager's version first and
 manager with `SystemdUnitManagerTooOldError` (`manager_too_old`), an unreadable version with
 `version_unknown` and an unanswered read with `command_failed`, each without running the clean.
 
+`kill(signal?, options?)` ends a unit's processes without a stop job: it sends `SIGKILL` (the
+default) or `SIGTERM` to every process of the unit at once, its main and control process and every
+other process in its control group (`systemctl kill --signal=<signal> --kill-whom=all`), then reads
+the unit every 100 ms until it is at rest or about to restart, for at most `timeoutMs` (integer
+milliseconds from 1 to 600000, default 30000). Use it where a `stop()` would wait out the unit's
+`TimeoutStopSec=`, such as a unit whose stop already failed or overran; it does not run `ExecStop=`,
+does not cancel or await a pending job, and never starts, enables, unmasks or resets the unit. It
+resolves a frozen `{ outcome, state }`, where `state` is the snapshot that decided the outcome (for
+`timeout`, the last one read):
+
+| `outcome` | Meaning |
+| --- | --- |
+| `'stopped'`, `'failed'` | `systemdUnitQuiescence()`'s `rest`: no main or control process and no control group. A unit whose main process is gone while its control group still holds processes resolves only once the group is gone. A unit already at rest is signalled all the same (nothing receives it) and resolves at the first read |
+| `'auto-restart'` | SubState `auto-restart`, or `auto-restart-queued` (systemd 254), without a main or control process: the unit waits for its `Restart=` timer or its queued restart. Its control group is not read here: with `RestartMode=direct` the manager keeps the emptied group |
+| `'restarted'` | the manager began a new invocation (`InvocationID`) before a read saw the unit at rest: a restart delay shorter than the poll interval, or another client's start |
+| `'timeout'` | none of these within `timeoutMs`; a read begun before the deadline is still awaited, each bounded by `commandTimeoutMs` |
+
+A unit whose `LoadState` is not `loaded` in the read before the signal (`not-found`, `masked`,
+`bad-setting`, `error`, ...) is refused with `command_failed` before any signal: that read makes the
+manager load the unit object, and the manager may signal an improperly loaded unit, so such a unit
+would otherwise resolve `stopped`. A refused signal and a `systemctl kill` that exceeded
+`commandTimeoutMs` reject with `command_failed` too; after a timed-out call the signal may have been
+sent, so inspect the unit. Once the manager accepted the signal, a failed read rejects with
+`signalled_uninspected` and that read's error as `cause`. `signalled_uninspected` is a new member of
+`SystemdUnitError['code']`: a consumer with an exhaustive `never` switch over the code must add a
+case for it. `kill()` needs systemd 252 or later, the first whose `systemctl` takes
+`--kill-whom=`: it reads the manager's version first and refuses an older manager with
+`SystemdUnitManagerTooOldError`, an unreadable version with `version_unknown` and an unanswered read
+with `command_failed`, each before any signal. A signal other than `'SIGKILL'` or `'SIGTERM'` and an
+option other than `timeoutMs` reject with `invalid_options` before any command runs.
+
+```typescript
+const killed = await unit.kill('SIGKILL', { timeoutMs: 30_000 });
+if (killed.outcome === 'timeout') {
+  console.log('still running', killed.state.activeState, killed.state.controlGroup);
+} else if (killed.outcome !== 'restarted') {
+  await unit.start();
+}
+```
+
+After an `auto-restart` outcome the start job stays queued until the unit's `RestartSec=` elapses,
+so `start()` waits for it; a long `RestartSec=` can exceed `commandTimeoutMs`.
+
 `inspectConfiguration()` reports the selected `fragmentPath`, opaque `dropInPaths`
 list and `needsReload` flag. `reloadConfiguration()` explicitly reloads the manager's
 unit definitions globally and returns a fresh configuration snapshot. Neither
@@ -1112,6 +1155,70 @@ verifies the flag on every passed descriptor, as `sd_listen_fds(3)` does.
 caller's user manager (`systemd-run --user`), and skips with the reason without Node.js 26 or a
 user manager.
 
+### An exclusive file lock on an open descriptor (`/file-lock`, Node.js 26)
+
+Node.js has no file lock. The `@push.rocks/smartdaemon/file-lock` subpath takes the kernel's
+`flock(2)` lock on a descriptor the caller opened, through the same glibc loader as
+`/systemd-runtime`, and nothing more: no path, no open, no class, no wait, no shared lock.
+
+```typescript
+import * as fs from 'node:fs';
+import { FileLockError, tryLockFile, unlockFile } from '@push.rocks/smartdaemon/file-lock';
+
+// The caller opens (and checks) the file itself; the lock belongs to this open file description.
+const descriptor = fs.openSync('/var/lib/example/.owner.lock', 'r+');
+if (!tryLockFile(descriptor)) throw new Error('another process owns /var/lib/example');
+try {
+  // ... work only the owner may do ...
+} finally {
+  unlockFile(descriptor); // or close the descriptor, or exit
+  fs.closeSync(descriptor);
+}
+```
+
+| Call | Does |
+| --- | --- |
+| `tryLockFile(fd)` | `flock(fd, LOCK_EX \| LOCK_NB)`: true when granted (also when this description already holds it), false only when another holds a conflicting lock (`EWOULDBLOCK`) |
+| `unlockFile(fd)` | `flock(fd, LOCK_UN)`; releasing a description that holds no lock succeeds |
+
+Both are synchronous and either complete or throw `FileLockError` (`code`, and `errno` when the
+libc call failed): `lock_failed` and `unlock_failed` carry the errno (`EBADF` for a descriptor that
+is not open), and a number that cannot be a descriptor (not an integer from 0 to `INT_MAX`) is
+`descriptor_invalid` before any call.
+
+What the lock is:
+
+- **Advisory and exclusive.** It excludes only other `flock(2)` locks; a process that does not ask
+  is not stopped from reading or writing the file. `/proc/locks` shows it as `FLOCK ADVISORY WRITE`.
+- **Held by the open file description**, not by the process or the descriptor number. A `dup` of
+  the descriptor shares it, and so does a descriptor a child inherits (through `stdio`, for
+  example): the child keeps the lock after the parent closed its copy or died. A second `open` of
+  the same file, even in the same process, is a new description and conflicts.
+- **Released** by `unlockFile`, or when the last descriptor of the description is closed, which a
+  process exit (`SIGKILL` included) does.
+- **Not an `fcntl` lock.** On a local Linux filesystem `fcntl(2)` record locks (`F_SETLK`,
+  `F_OFD_SETLK`) and `flock(2)` locks do not conflict with each other, so a peer that uses `fcntl` is
+  not excluded.
+- Any other program taking `flock(2)` on the same file, util-linux `flock(1)` for example, excludes
+  and is excluded by it.
+
+It requires **Node.js 26 or later** on Linux x64 or arm64 with glibc, like `/systemd-runtime`:
+importing it on an older Node.js throws `FileLockError` `runtime_unsupported`, and the first call
+throws the same code on another platform or with `node:ffi` unavailable or denied (pass
+`--allow-ffi` under the permission model).
+
+There is **no blocking lock**, on purpose. `node:ffi` has no off-thread call mode, so a blocking
+`flock(fd, LOCK_EX)` on the main thread stops the event loop for the whole wait: signal handlers,
+timers and `sd_notify` messages all stall. Moving it into a worker does not help: a worker blocked
+in `flock` cannot be terminated, and `process.exit()` waits until the lock is granted, which is
+never while another process holds it. A caller that must wait polls `tryLockFile` on a timer:
+
+```typescript
+const lockWhenFree = async (fd: number, intervalMs = 100): Promise<void> => {
+  while (!tryLockFile(fd)) await new Promise((resolve) => setTimeout(resolve, intervalMs));
+};
+```
+
 ### Starting a program in its own transient scope
 
 A service that launches a long-lived program keeps that program in its own
@@ -1368,8 +1475,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
+- **Node.js 26 or later** for the `@push.rocks/smartdaemon/systemd-runtime` and
+  `@push.rocks/smartdaemon/file-lock` subpaths (`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: '3.0.0',
+  version: '3.2.0',
   description: 'Start scripts as long running daemons and manage them.'
 }

package/ts/classes.systemdunit.ts

@@ -12,6 +12,7 @@ import {
   type ISystemdManagerVersion,
   fileDescriptorStoreCleanMajor,
   fileDescriptorStorePreserveMajor,
+  killWhomMajor,
   managerVersionArguments,
   parseManagerVersion,
 } from './systemd.managerversion.js';
@@ -127,6 +128,49 @@ export interface ISystemdUnitJobOptions {
   wait?: boolean;
 }
 
+/** The signals `SystemdUnit.kill()` sends. */
+export type TSystemdUnitKillSignal = 'SIGKILL' | 'SIGTERM';
+
+/** `SystemdUnit.kill()` options. */
+export interface ISystemdUnitKillOptions {
+  /**
+   * How long to wait, after the manager accepted the signal, for the unit to come to rest: integer
+   * milliseconds from 1 to 600000. Defaults to 30000. A read begun before the deadline is still
+   * awaited; each read is bounded by `commandTimeoutMs`.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * How the unit stood when `SystemdUnit.kill()` stopped waiting. `stopped` and `failed` are
+ * `systemdUnitQuiescence()`'s `rest`: no main or control process and no control group.
+ * `auto-restart`: SubState `auto-restart` or `auto-restart-queued` (systemd 254) without a main or
+ * control process, waiting for its `Restart=` timer or its queued restart job. `restarted`: the
+ * manager started a new invocation of the unit (a restart delay shorter than the poll interval, or
+ * another client's start) before a read saw it at rest. `timeout`: none of these within `timeoutMs`.
+ */
+export type TSystemdUnitKillOutcome = 'stopped' | 'failed' | 'auto-restart' | 'restarted' | 'timeout';
+
+export interface ISystemdUnitKillResult {
+  readonly outcome: TSystemdUnitKillOutcome;
+  /** The snapshot that decided `outcome`; for `timeout`, the last one read before the deadline. */
+  readonly state: ISystemdUnitState;
+}
+
+/** Interval between the snapshots `kill()` reads while it waits. */
+const killPollIntervalMs = 100;
+
+/** Reads the outcome a kill has reached from one snapshot, or null while it has reached none. */
+const killOutcome = (state: ISystemdUnitState, newInvocation: boolean): TSystemdUnitKillOutcome | null => {
+  const { rest } = systemdUnitQuiescence(state);
+  if (rest !== null) return rest;
+  // In auto-restart the manager may keep the unit's (empty) control group: with RestartMode=direct
+  // the unit never passes the inactive state that releases it, so ControlGroup is not read here.
+  if (state.mainPid === 0 && state.controlPid === 0 &&
+    (state.subState === 'auto-restart' || state.subState === 'auto-restart-queued')) return 'auto-restart';
+  return newInvocation ? 'restarted' : null;
+};
+
 export interface ISystemdUnitConfigurationState {
   readonly unitName: string;
   readonly fragmentPath: string;
@@ -232,12 +276,15 @@ export class SystemdUnitError extends Error {
      * `version_unknown`: the manager answered, but its `Version` property is not one this package
      * reads, so a call that needs a minimum manager version refuses.
      * `manager_too_old`: always a `SystemdUnitManagerTooOldError`, naming both versions.
+     * `signalled_uninspected`: only `kill()`. The manager accepted the signal, and a snapshot read
+     * while waiting failed; `cause` is that inspection's error.
      */
     public readonly code:
       | 'invalid_options'
       | 'command_failed'
       | 'invalid_state'
       | 'released_uninspected'
+      | 'signalled_uninspected'
       | 'version_unknown'
       | 'manager_too_old',
     options?: ErrorOptions,
@@ -480,10 +527,18 @@ export class SystemdUnit {
 
   /** Snapshot only. Callers own application-specific admission and restart policy. */
   public async inspect(): Promise<ISystemdUnitState> {
+    return (await this.readState(properties)).state;
+  }
+
+  /**
+   * Reads one snapshot with `keys`: the snapshot properties, optionally followed by `InvocationID`,
+   * which is empty for a unit never started and otherwise 32 lowercase hex digits.
+   */
+  private async readState(keys: readonly string[]): Promise<{ state: ISystemdUnitState; invocationId: string }> {
     const stdout = await this.command([
       'show',
       this.unitName,
-      `--property=${properties.join(',')}`,
+      `--property=${keys.join(',')}`,
       '--all',
     ]);
     const fields = new Map<string, string>();
@@ -491,13 +546,14 @@ export class SystemdUnit {
     for (const line of (stdout.endsWith('\n') ? stdout.slice(0, -1) : stdout).split('\n')) {
       const separator = line.indexOf('=');
       const key = line.slice(0, separator);
-      if (separator < 1 || !(properties as readonly string[]).includes(key) || fields.has(key)) {
+      if (separator < 1 || !keys.includes(key) || fields.has(key)) {
         throw new SystemdUnitError('invalid_state');
       }
       fields.set(key, line.slice(separator + 1));
     }
     if (
-      fields.size !== properties.length || fields.get('Id') !== this.unitName ||
+      fields.size !== keys.length || fields.get('Id') !== this.unitName ||
+      (keys.includes('InvocationID') && !/^(?:[0-9a-f]{32})?$/.test(fields.get('InvocationID') ?? '')) ||
       ['LoadState', 'ActiveState', 'SubState'].some((key) => !fields.get(key)) ||
       !/^[a-z][a-z-]{0,31}$/.test(fields.get('Result')!) ||
       ['MainPID', 'ControlPID', 'NFileDescriptorStore'].some((key) =>
@@ -506,7 +562,7 @@ export class SystemdUnit {
       // systemd prints the store's unsigned 32-bit count in decimal.
       Number(fields.get('NFileDescriptorStore')) > 4294967295
     ) throw new SystemdUnitError('invalid_state');
-    return Object.freeze({
+    const state: ISystemdUnitState = Object.freeze({
       unitName: this.unitName,
       loadState: fields.get('LoadState')!,
       activeState: fields.get('ActiveState')!,
@@ -521,6 +577,7 @@ export class SystemdUnit {
       result: fields.get('Result')!,
       fileDescriptorStoreCount: Number(fields.get('NFileDescriptorStore')),
     });
+    return { state, invocationId: fields.get('InvocationID') ?? '' };
   }
 
   /**
@@ -585,6 +642,65 @@ export class SystemdUnit {
     return this.inspect();
   }
 
+  /**
+   * Sends `signal` (default `SIGKILL`) to every process of the unit at once, its main and control
+   * process and every other process in its control group (`systemctl kill --signal=<signal>
+   * --kill-whom=all`), then waits, bounded by `timeoutMs`, until the unit is at rest or about to
+   * restart, and resolves with the outcome and the snapshot that decided it. It does not queue a
+   * stop job and does not wait out `TimeoutStopSec=`; a pending job is neither cancelled nor
+   * awaited. It never starts, enables, unmasks or resets the unit.
+   *
+   * A unit already at rest is signalled all the same (nothing receives it) and resolves at the first
+   * read. A unit whose main process is gone while its control group still holds processes resolves
+   * only once the group is gone. A unit whose `LoadState` in the read before the signal is not
+   * `loaded` (`not-found`, `masked`, `bad-setting`, `error`, ...) is refused with `command_failed`
+   * before any signal, as are a refused signal and a `systemctl` call that exceeded
+   * `commandTimeoutMs`; after a timed-out call the signal may have been sent, so inspect the unit. Once the manager accepted the signal, a failed read
+   * rejects with `signalled_uninspected` and that read's error as `cause`.
+   *
+   * Needs systemd 252 or later, the first whose `systemctl` takes `--kill-whom=`: the manager's
+   * version is read first, and an older manager is refused with `SystemdUnitManagerTooOldError`, an
+   * unreadable version with `version_unknown` and an unanswered read with `command_failed`, each
+   * before any signal. A malformed signal or option rejects with `invalid_options` before any command.
+   */
+  public async kill(
+    signalArg: TSystemdUnitKillSignal = 'SIGKILL',
+    optionsArg?: ISystemdUnitKillOptions,
+  ): Promise<ISystemdUnitKillResult> {
+    if (
+      (signalArg !== 'SIGKILL' && signalArg !== 'SIGTERM') ||
+      (optionsArg !== undefined && (
+        typeof optionsArg !== 'object' || optionsArg === null ||
+        Object.keys(optionsArg).some((key) => key !== 'timeoutMs') ||
+        (optionsArg.timeoutMs !== undefined && (!Number.isSafeInteger(optionsArg.timeoutMs) ||
+          optionsArg.timeoutMs < 1 || optionsArg.timeoutMs > 600000))
+      ))
+    ) throw new SystemdUnitError('invalid_options');
+    const timeoutMs = optionsArg?.timeoutMs ?? 30000;
+    await this.requireManagerVersion(killWhomMajor);
+    const killKeys = [...properties, 'InvocationID'];
+    // The invocation before the signal, so a restart the wait could not observe at rest is reported.
+    const { state: before, invocationId } = await this.readState(killKeys);
+    // That read makes the manager load the unit object, and the manager may signal a unit it could
+    // not load properly; such a unit has no processes of its own to end, so it is refused here.
+    if (before.loadState !== 'loaded') throw new SystemdUnitError('command_failed');
+    await this.command(['kill', `--signal=${signalArg}`, '--kill-whom=all', this.unitName]);
+    const deadline = performance.now() + timeoutMs;
+    for (;;) {
+      let read: { state: ISystemdUnitState; invocationId: string };
+      try {
+        read = await this.readState(killKeys);
+      } catch (error) {
+        throw new SystemdUnitError('signalled_uninspected', { cause: error });
+      }
+      const outcome = killOutcome(read.state, read.invocationId !== invocationId);
+      if (outcome !== null) return Object.freeze({ outcome, state: read.state });
+      const remaining = deadline - performance.now();
+      if (remaining <= 0) return Object.freeze({ outcome: 'timeout', state: read.state });
+      await plugins.timers.setTimeout(Math.min(killPollIntervalMs, remaining));
+    }
+  }
+
   /** Reports the manager's selected definition without reading or changing its contents. */
   public async inspectConfiguration(): Promise<ISystemdUnitConfigurationState> {
     const keys = ['Id', 'FragmentPath', 'DropInPaths', 'NeedDaemonReload'];

package/ts/smartdaemon.plugins.ts

@@ -6,9 +6,10 @@ import { constants as fsConstants } from 'node:fs';
 import * as crypto from 'node:crypto';
 import * as util from 'node:util';
 import * as os from 'node:os';
+import * as timers from 'node:timers/promises';
 export type { Stats } from 'node:fs';
 
-export { path, childProcess, fs, fsConstants, crypto, util, os };
+export { path, childProcess, fs, fsConstants, crypto, util, os, timers };
 
 // @pushrocks scope
 import * as lik from '@push.rocks/lik';

package/ts/systemd.managerversion.ts

@@ -19,6 +19,9 @@ export const outputAppendMajor = 240;
 /** Internal: the systemd major whose `systemctl clean` first releases a file descriptor store (`--what=fdstore`). */
 export const fileDescriptorStoreCleanMajor = 254;
 
+/** Internal: the systemd major whose `systemctl kill` first takes `--kill-whom=` (formerly `--kill-who=`). */
+export const killWhomMajor = 252;
+
 /**
  * Internal: the systemd major whose `systemd-run` first takes `--expand-environment` and reports a
  * started scope as `runInTransientScope()` reads it.

package/ts_filelock/filelock.classes.filelockerror.ts

@@ -0,0 +1,37 @@
+/**
+ * Why a file lock operation refused or failed:
+ *
+ * - `runtime_unsupported`: the lock cannot be called: 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`).
+ * - `descriptor_invalid`: a descriptor number that cannot exist (not an integer from 0 to
+ *   `INT_MAX`); refused before any call.
+ * - `lock_failed`: `flock(LOCK_EX | LOCK_NB)` failed for a reason other than a conflicting lock
+ *   (`errno` names why: `EBADF` for a descriptor that is not open, for example).
+ * - `unlock_failed`: `flock(LOCK_UN)` failed (`errno` names why).
+ */
+export type TFileLockErrorCode = 'runtime_unsupported' | 'descriptor_invalid' | 'lock_failed' | 'unlock_failed';
+
+export interface IFileLockErrorOptions {
+  /** The C library's `errno` after the failed call, when a call failed. */
+  readonly errno?: number;
+  readonly cause?: unknown;
+}
+
+export class FileLockError 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: TFileLockErrorCode,
+    messageArg: string,
+    optionsArg: IFileLockErrorOptions = {},
+  ) {
+    super(
+      `${messageArg}${optionsArg.errno === undefined ? '' : ` (errno ${optionsArg.errno})`}`,
+      optionsArg.cause === undefined ? undefined : { cause: optionsArg.cause },
+    );
+    this.name = 'FileLockError';
+    this.errno = optionsArg.errno ?? null;
+  }
+}