@push.rocks/smartdaemon 3.1.0 → 3.2.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@push.rocks/smartdaemon',
-    version: '3.1.0',
+    version: '3.2.0',
     description: 'Start scripts as long running daemons and manage them.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHdEQUF3RDtDQUN0RSxDQUFBIn0=

package/dist_ts_filelock/filelock.classes.filelockerror.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare class FileLockError extends Error {
+    readonly code: TFileLockErrorCode;
+    /** The C library's `errno` after the failed call, or null when no call failed. */
+    readonly errno: number | null;
+    constructor(code: TFileLockErrorCode, messageArg: string, optionsArg?: IFileLockErrorOptions);
+}

package/dist_ts_filelock/filelock.classes.filelockerror.js

@@ -0,0 +1,9 @@
+export class FileLockError extends Error {
+    constructor(code, messageArg, optionsArg = {}) {
+        super(`${messageArg}${optionsArg.errno === undefined ? '' : ` (errno ${optionsArg.errno})`}`, optionsArg.cause === undefined ? undefined : { cause: optionsArg.cause });
+        this.code = code;
+        this.name = 'FileLockError';
+        this.errno = optionsArg.errno ?? null;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZWxvY2suY2xhc3Nlcy5maWxlbG9ja2Vycm9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfZmlsZWxvY2svZmlsZWxvY2suY2xhc3Nlcy5maWxlbG9ja2Vycm9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW9CQSxNQUFNLE9BQU8sYUFBYyxTQUFRLEtBQUs7SUFJdEMsWUFDa0IsSUFBd0IsRUFDeEMsVUFBa0IsRUFDbEIsVUFBVSxHQUEwQixFQUFFO1FBRXRDLEtBQUssQ0FDSCxHQUFHLFVBQVUsR0FBRyxVQUFVLENBQUMsS0FBSyxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxXQUFXLFVBQVUsQ0FBQyxLQUFLLEdBQUcsRUFBRSxFQUN0RixVQUFVLENBQUMsS0FBSyxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLEtBQUssRUFBRSxVQUFVLENBQUMsS0FBSyxFQUFFLENBQ3pFLENBQUM7b0JBUGMsSUFBSTtRQVFwQixJQUFJLENBQUMsSUFBSSxHQUFHLGVBQWUsQ0FBQztRQUM1QixJQUFJLENBQUMsS0FBSyxHQUFHLFVBQVUsQ0FBQyxLQUFLLElBQUksSUFBSSxDQUFDO0lBQ3hDLENBQUM7Q0FDRiJ9

package/dist_ts_filelock/filelock.flock.d.ts

@@ -0,0 +1,14 @@
+/** Internal: refuses a Node.js older than 26; the subpath runs it on import. */
+export declare const assertFileLockNode: (versionArg?: string) => void;
+/**
+ * Takes the exclusive `flock(2)` lock on the open file description behind `descriptorArg`
+ * (`LOCK_EX | LOCK_NB`), without waiting. Returns true when the lock is granted, also when this
+ * open file description already holds it, and false only when another open file description holds
+ * a conflicting lock (`EWOULDBLOCK`). Throws `FileLockError` for every other failure.
+ */
+export declare const tryLockFile: (descriptorArg: number) => boolean;
+/**
+ * Releases the `flock(2)` lock of the open file description behind `descriptorArg` (`LOCK_UN`).
+ * Releasing a description that holds no lock succeeds. Throws `FileLockError` on failure.
+ */
+export declare const unlockFile: (descriptorArg: number) => void;

package/dist_ts_filelock/filelock.flock.js

@@ -0,0 +1,38 @@
+import { assertLibcNode, libcConstants, systemdLibc, } from '../dist_ts_systemdruntime/systemdruntime.libc.js';
+import { isSystemdDescriptor } from '../dist_ts_systemdruntime/systemdruntime.validation.js';
+import { FileLockError } from './filelock.classes.filelockerror.js';
+const fileLockUnsupported = (messageArg, causeArg) => new FileLockError('runtime_unsupported', messageArg, causeArg === undefined ? {} : { cause: causeArg });
+/** Internal: refuses a Node.js older than 26; the subpath runs it on import. */
+export const assertFileLockNode = (versionArg = process.versions.node) => assertLibcNode('file-lock', fileLockUnsupported, versionArg);
+const fileLockLibc = (descriptorArg) => {
+    if (!isSystemdDescriptor(descriptorArg)) {
+        throw new FileLockError('descriptor_invalid', `${String(descriptorArg)} is not a descriptor number.`);
+    }
+    return systemdLibc(fileLockUnsupported);
+};
+/**
+ * Takes the exclusive `flock(2)` lock on the open file description behind `descriptorArg`
+ * (`LOCK_EX | LOCK_NB`), without waiting. Returns true when the lock is granted, also when this
+ * open file description already holds it, and false only when another open file description holds
+ * a conflicting lock (`EWOULDBLOCK`). Throws `FileLockError` for every other failure.
+ */
+export const tryLockFile = (descriptorArg) => {
+    const libc = fileLockLibc(descriptorArg);
+    if (libc.functions.flock(descriptorArg, libcConstants.LOCK_EX | libcConstants.LOCK_NB) === 0)
+        return true;
+    const errno = libc.errno();
+    if (errno === libcConstants.EWOULDBLOCK)
+        return false;
+    throw new FileLockError('lock_failed', `Descriptor ${descriptorArg} cannot be locked.`, { errno });
+};
+/**
+ * Releases the `flock(2)` lock of the open file description behind `descriptorArg` (`LOCK_UN`).
+ * Releasing a description that holds no lock succeeds. Throws `FileLockError` on failure.
+ */
+export const unlockFile = (descriptorArg) => {
+    const libc = fileLockLibc(descriptorArg);
+    if (libc.functions.flock(descriptorArg, libcConstants.LOCK_UN) !== 0) {
+        throw new FileLockError('unlock_failed', `Descriptor ${descriptorArg} cannot be unlocked.`, { errno: libc.errno() });
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmlsZWxvY2suZmxvY2suanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19maWxlbG9jay9maWxlbG9jay5mbG9jay50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsY0FBYyxFQUNkLGFBQWEsRUFDYixXQUFXLEdBR1osTUFBTSw2Q0FBNkMsQ0FBQztBQUNyRCxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxtREFBbUQsQ0FBQztBQUN4RixPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0scUNBQXFDLENBQUM7QUFFcEUsTUFBTSxtQkFBbUIsR0FBMEIsQ0FBQyxVQUFVLEVBQUUsUUFBUSxFQUFFLEVBQUUsQ0FDMUUsSUFBSSxhQUFhLENBQUMscUJBQXFCLEVBQUUsVUFBVSxFQUFFLFFBQVEsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLENBQUMsQ0FBQztBQUUxRyxnRkFBZ0Y7QUFDaEYsTUFBTSxDQUFDLE1BQU0sa0JBQWtCLEdBQUcsQ0FBQyxVQUFVLEdBQVcsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQVEsRUFBRSxDQUNyRixjQUFjLENBQUMsV0FBVyxFQUFFLG1CQUFtQixFQUFFLFVBQVUsQ0FBQyxDQUFDO0FBRS9ELE1BQU0sWUFBWSxHQUFHLENBQUMsYUFBcUIsRUFBZ0IsRUFBRTtJQUMzRCxJQUFJLENBQUMsbUJBQW1CLENBQUMsYUFBYSxDQUFDLEVBQUUsQ0FBQztRQUN4QyxNQUFNLElBQUksYUFBYSxDQUFDLG9CQUFvQixFQUFFLEdBQUcsTUFBTSxDQUFDLGFBQWEsQ0FBQyw4QkFBOEIsQ0FBQyxDQUFDO0lBQ3hHLENBQUM7SUFDRCxPQUFPLFdBQVcsQ0FBQyxtQkFBbUIsQ0FBQyxDQUFDO0FBQzFDLENBQUMsQ0FBQztBQUVGOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sV0FBVyxHQUFHLENBQUMsYUFBcUIsRUFBVyxFQUFFO0lBQzVELE1BQU0sSUFBSSxHQUFHLFlBQVksQ0FBQyxhQUFhLENBQUMsQ0FBQztJQUN6QyxJQUFJLElBQUksQ0FBQyxTQUFTLENBQUMsS0FBSyxDQUFDLGFBQWEsRUFBRSxhQUFhLENBQUMsT0FBTyxHQUFHLGFBQWEsQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDO1FBQUUsT0FBTyxJQUFJLENBQUM7SUFDMUcsTUFBTSxLQUFLLEdBQUcsSUFBSSxDQUFDLEtBQUssRUFBRSxDQUFDO0lBQzNCLElBQUksS0FBSyxLQUFLLGFBQWEsQ0FBQyxXQUFXO1FBQUUsT0FBTyxLQUFLLENBQUM7SUFDdEQsTUFBTSxJQUFJLGFBQWEsQ0FBQyxhQUFhLEVBQUUsY0FBYyxhQUFhLG9CQUFvQixFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUMsQ0FBQztBQUNyRyxDQUFDLENBQUM7QUFFRjs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSxVQUFVLEdBQUcsQ0FBQyxhQUFxQixFQUFRLEVBQUU7SUFDeEQsTUFBTSxJQUFJLEdBQUcsWUFBWSxDQUFDLGFBQWEsQ0FBQyxDQUFDO0lBQ3pDLElBQUksSUFBSSxDQUFDLFNBQVMsQ0FBQyxLQUFLLENBQUMsYUFBYSxFQUFFLGFBQWEsQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLEVBQUUsQ0FBQztRQUNyRSxNQUFNLElBQUksYUFBYSxDQUFDLGVBQWUsRUFBRSxjQUFjLGFBQWEsc0JBQXNCLEVBQUUsRUFBRSxLQUFLLEVBQUUsSUFBSSxDQUFDLEtBQUssRUFBRSxFQUFFLENBQUMsQ0FBQztJQUN2SCxDQUFDO0FBQ0gsQ0FBQyxDQUFDIn0=

package/dist_ts_filelock/index.d.ts

@@ -0,0 +1,2 @@
+export * from './filelock.classes.filelockerror.js';
+export { tryLockFile, unlockFile } from './filelock.flock.js';

package/dist_ts_filelock/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@push.rocks/smartdaemon/file-lock`: the exclusive, advisory `flock(2)` lock on a descriptor the
+ * caller opened, through glibc called with `node:ffi`. There is no blocking lock: a caller that must
+ * wait polls `tryLockFile` on a timer. Requires Node.js 26 or later: importing it on an older
+ * Node.js throws `FileLockError` `runtime_unsupported`.
+ */
+import { assertFileLockNode } from './filelock.flock.js';
+export * from './filelock.classes.filelockerror.js';
+export { tryLockFile, unlockFile } from './filelock.flock.js';
+assertFileLockNode();
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19maWxlbG9jay9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7Ozs7R0FLRztBQUNILE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBRXpELGNBQWMscUNBQXFDLENBQUM7QUFDcEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxVQUFVLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUU5RCxrQkFBa0IsRUFBRSxDQUFDIn0=

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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3lzdGVtZHJ1bnRpbWUubGliYy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzX3N5c3RlbWRydW50aW1lL3N5c3RlbWRydW50aW1lLmxpYmMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLG1CQUFtQixFQUFFLE1BQU0sa0NBQWtDLENBQUM7QUFFdkUscUZBQXFGO0FBQ3JGLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLEVBQUUsQ0FBQztBQVExQyxNQUFNLHlCQUF5QixHQUEwQixDQUFDLFVBQVUsRUFBRSxRQUFRLEVBQUUsRUFBRSxDQUNoRixJQUFJLG1CQUFtQixDQUFDLHFCQUFxQixFQUFFLFVBQVUsRUFBRSxRQUFRLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxDQUFDLENBQUM7QUFFaEgsNkdBQTZHO0FBQzdHLE1BQU0sQ0FBQyxNQUFNLGNBQWMsR0FBRyxDQUM1QixVQUFrQixFQUNsQixjQUFxQyxFQUNyQyxVQUFVLEdBQVcsT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLEVBQ3BDLEVBQUU7SUFDUixNQUFNLEtBQUssR0FBRyxNQUFNLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDdkQsSUFBSSxDQUFDLENBQUMsS0FBSyxJQUFJLHVCQUF1QixDQUFDLEVBQUUsQ0FBQztRQUN4QyxNQUFNLGNBQWMsQ0FDbEIsMkJBQTJCLFVBQVUscUJBQXFCLHVCQUF1Qiw4QkFBOEIsVUFBVSxHQUFHLENBQzdILENBQUM7SUFDSixDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBRUYsdUdBQXVHO0FBQ3ZHLE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLENBQUMsVUFBVSxHQUFXLE9BQU8sQ0FBQyxRQUFRLENBQUMsSUFBSSxFQUFRLEVBQUUsQ0FDM0YsY0FBYyxDQUFDLGlCQUFpQixFQUFFLHlCQUF5QixFQUFFLFVBQVUsQ0FBQyxDQUFDO0FBRTNFOzs7Ozs7Ozs7Ozs7OztHQWNHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHO0lBQzNCLE9BQU8sRUFBRSxDQUFDO0lBQ1YsVUFBVSxFQUFFLENBQUM7SUFDYixZQUFZLEVBQUUsU0FBUztJQUN2QixVQUFVLEVBQUUsQ0FBQztJQUNiLFVBQVUsRUFBRSxDQUFDO0lBQ2IsWUFBWSxFQUFFLE1BQU07SUFDcEIsT0FBTyxFQUFFLENBQUM7SUFDVixPQUFPLEVBQUUsQ0FBQztJQUNWLFVBQVUsRUFBRSxDQUFDO0lBQ2IsZUFBZSxFQUFFLENBQUM7SUFDbEIsS0FBSyxFQUFFLENBQUM7SUFDUixXQUFXLEVBQUUsRUFBRTtJQUNmLGFBQWEsRUFBRSxDQUFDO0lBQ2hCLE9BQU8sRUFBRSxDQUFDO0lBQ1YsT0FBTyxFQUFFLENBQUM7SUFDVixPQUFPLEVBQUUsQ0FBQztDQUNGLENBQUM7QUFFWCw2RkFBNkY7QUFDN0YsTUFBTSxDQUFDLE1BQU0seUJBQXlCLEdBQUcsR0FBRyxDQUFDO0FBRTdDLHdGQUF3RjtBQUN4RixNQUFNLENBQUMsTUFBTSw0QkFBNEIsR0FBRyxHQUFHLENBQUM7QUFFaEQsTUFBTSxhQUFhLEdBQUc7SUFDcEIsTUFBTSxFQUFFLEVBQUUsU0FBUyxFQUFFLENBQUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxPQUFPLENBQUMsRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFO0lBQ25FLE9BQU8sRUFBRSxFQUFFLFNBQVMsRUFBRSxDQUFDLE9BQU8sRUFBRSxTQUFTLEVBQUUsT0FBTyxDQUFDLEVBQUUsTUFBTSxFQUFFLE9BQU8sRUFBRTtJQUN0RSxLQUFLLEVBQUUsRUFBRSxTQUFTLEVBQUUsQ0FBQyxPQUFPLENBQUMsRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFO0lBQ2hELDhFQUE4RTtJQUM5RSxLQUFLLEVBQUUsRUFBRSxTQUFTLEVBQUUsQ0FBQyxPQUFPLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUU7SUFDbEUsYUFBYSxFQUFFLEVBQUUsU0FBUyxFQUFFLENBQUMsT0FBTyxFQUFFLFNBQVMsQ0FBQyxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUU7SUFDbkUsU0FBUyxFQUFFLEVBQUUsU0FBUyxFQUFFLENBQUMsT0FBTyxFQUFFLFNBQVMsQ0FBQyxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUU7SUFDL0QsS0FBSyxFQUFFLEVBQUUsU0FBUyxFQUFFLENBQUMsT0FBTyxFQUFFLE9BQU8sQ0FBQyxFQUFFLE1BQU0sRUFBRSxPQUFPLEVBQUU7SUFDekQsZ0JBQWdCLEVBQUUsRUFBRSxTQUFTLEVBQUUsRUFBRSxFQUFFLE1BQU0sRUFBRSxTQUFTLEVBQUU7Q0FDWixDQUFDO0FBWTdDLElBQUksTUFBTSxHQUF3QixJQUFJLENBQUM7QUFFdkM7Ozs7O0dBS0c7QUFDSCxNQUFNLENBQUMsTUFBTSxXQUFXLEdBQUcsQ0FBQyxjQUFjLEdBQTBCLHlCQUF5QixFQUFnQixFQUFFO0lBQzdHLElBQUksTUFBTSxLQUFLLElBQUk7UUFBRSxPQUFPLE1BQU0sQ0FBQztJQUNuQyxJQUFJLE9BQU8sQ0FBQyxRQUFRLEtBQUssT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksS0FBSyxLQUFLLElBQUksT0FBTyxDQUFDLElBQUksS0FBSyxPQUFPLENBQUMsRUFBRSxDQUFDO1FBQ3pGLE1BQU0sY0FBYyxDQUFDLHdFQUF3RSxPQUFPLENBQUMsUUFBUSxPQUFPLE9BQU8sQ0FBQyxJQUFJLEdBQUcsQ0FBQyxDQUFDO0lBQ3ZJLENBQUM7SUFDRCxNQUFNLFNBQVMsR0FBMkIsT0FBTyxDQUFDLGdCQUFnQixDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQy9FLElBQUksU0FBUyxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQzVCLE1BQU0sY0FBYyxDQUFDLGlFQUFpRSxDQUFDLENBQUM7SUFDMUYsQ0FBQztJQUNELElBQUksU0FBb0UsQ0FBQztJQUN6RSxJQUFJLENBQUM7UUFDSCxTQUFTLEdBQUcsU0FBUyxDQUFDLE1BQU0sQ0FBQyxXQUFXLEVBQUUsYUFBYSxDQUFDLENBQUMsU0FBUyxDQUFDO0lBQ3JFLENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO1FBQ2YsTUFBTSxjQUFjLENBQ2xCLHNHQUFzRyxFQUN0RyxLQUFLLENBQ04sQ0FBQztJQUNKLENBQUM7SUFDRCxNQUFNLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztRQUNyQixTQUFTO1FBQ1QsR0FBRyxFQUFFLFNBQVM7UUFDZCxLQUFLLEVBQUUsR0FBRyxFQUFFLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxTQUFTLENBQUMsZ0JBQWdCLEVBQUUsRUFBRSxDQUFDLENBQUM7S0FDakUsQ0FBQyxDQUFDO0lBQ0gsT0FBTyxNQUFNLENBQUM7QUFDaEIsQ0FBQyxDQUFDO0FBRUYsa0dBQWtHO0FBQ2xHLE1BQU0sQ0FBQyxNQUFNLG1CQUFtQixHQUFHLENBQUMsVUFBa0IsRUFBVSxFQUFFLENBQ2hFLENBQUMsR0FBRyxNQUFNLENBQUMsVUFBVSxDQUFDLFVBQVUsRUFBRSxNQUFNLENBQUMsR0FBRyxDQUFDLFVBQVUsQ0FBQyxVQUFVLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFFbkYsNkZBQTZGO0FBQzdGLE1BQU0sQ0FBQyxNQUFNLGtCQUFrQixHQUFHLENBQUMsU0FBaUIsRUFBRSxTQUFpQixFQUFFLFVBQWtCLEVBQVEsRUFBRTtJQUNuRyxTQUFTLENBQUMsYUFBYSxDQUFDLGFBQWEsQ0FBQyxPQUFPLEVBQUUsU0FBUyxDQUFDLENBQUM7SUFDMUQsU0FBUyxDQUFDLEtBQUssQ0FBQyxVQUFVLEVBQUUsU0FBUyxHQUFHLENBQUMsRUFBRSxNQUFNLENBQUMsQ0FBQztJQUNuRCxJQUFJLFVBQVUsQ0FBQyxVQUFVLENBQUMsR0FBRyxDQUFDO1FBQUUsU0FBUyxDQUFDLFNBQVMsR0FBRyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUM7QUFDL0QsQ0FBQyxDQUFDO0FBRUYsK0NBQStDO0FBQy9DLE1BQU0sQ0FBQyxNQUFNLFlBQVksR0FBRyxDQUFDLFFBQWdCLEVBQVUsRUFBRSxDQUFDLEVBQUUsR0FBRyxDQUFDLENBQUMsQ0FBQyxHQUFHLFFBQVEsR0FBRyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdaemon",
-  "version": "3.1.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,8 +41,8 @@
   },
   "homepage": "https://code.foss.global/push.rocks/smartdaemon",
   "devDependencies": {
-    "@git.zone/tsrepo": "^1.1.1",
-    "@types/node": "^26.6.5"
+    "@git.zone/tsrepo": "^2.1.0",
+    "@types/node": "^26.6.6"
   },
   "dependencies": {
     "@push.rocks/lik": "^6.4.4",
@@ -50,6 +54,7 @@
   "files": [
     "ts/**/*",
     "ts_systemdruntime/**/*",
+    "ts_filelock/**/*",
     "ts_web/**/*",
     "dist/**/*",
     "dist_*/**/*",

package/readme.md

@@ -1155,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
@@ -1411,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.1.0',
+  version: '3.2.0',
   description: 'Start scripts as long running daemons and manage them.'
 }

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

package/ts_filelock/filelock.flock.ts

@@ -0,0 +1,48 @@
+import {
+  assertLibcNode,
+  libcConstants,
+  systemdLibc,
+  type ISystemdLibc,
+  type TLibcUnsupportedError,
+} from '../ts_systemdruntime/systemdruntime.libc.js';
+import { isSystemdDescriptor } from '../ts_systemdruntime/systemdruntime.validation.js';
+import { FileLockError } from './filelock.classes.filelockerror.js';
+
+const fileLockUnsupported: TLibcUnsupportedError = (messageArg, causeArg) =>
+  new FileLockError('runtime_unsupported', messageArg, causeArg === undefined ? {} : { cause: causeArg });
+
+/** Internal: refuses a Node.js older than 26; the subpath runs it on import. */
+export const assertFileLockNode = (versionArg: string = process.versions.node): void =>
+  assertLibcNode('file-lock', fileLockUnsupported, versionArg);
+
+const fileLockLibc = (descriptorArg: number): ISystemdLibc => {
+  if (!isSystemdDescriptor(descriptorArg)) {
+    throw new FileLockError('descriptor_invalid', `${String(descriptorArg)} is not a descriptor number.`);
+  }
+  return systemdLibc(fileLockUnsupported);
+};
+
+/**
+ * Takes the exclusive `flock(2)` lock on the open file description behind `descriptorArg`
+ * (`LOCK_EX | LOCK_NB`), without waiting. Returns true when the lock is granted, also when this
+ * open file description already holds it, and false only when another open file description holds
+ * a conflicting lock (`EWOULDBLOCK`). Throws `FileLockError` for every other failure.
+ */
+export const tryLockFile = (descriptorArg: number): boolean => {
+  const libc = fileLockLibc(descriptorArg);
+  if (libc.functions.flock(descriptorArg, libcConstants.LOCK_EX | libcConstants.LOCK_NB) === 0) return true;
+  const errno = libc.errno();
+  if (errno === libcConstants.EWOULDBLOCK) return false;
+  throw new FileLockError('lock_failed', `Descriptor ${descriptorArg} cannot be locked.`, { errno });
+};
+
+/**
+ * Releases the `flock(2)` lock of the open file description behind `descriptorArg` (`LOCK_UN`).
+ * Releasing a description that holds no lock succeeds. Throws `FileLockError` on failure.
+ */
+export const unlockFile = (descriptorArg: number): void => {
+  const libc = fileLockLibc(descriptorArg);
+  if (libc.functions.flock(descriptorArg, libcConstants.LOCK_UN) !== 0) {
+    throw new FileLockError('unlock_failed', `Descriptor ${descriptorArg} cannot be unlocked.`, { errno: libc.errno() });
+  }
+};

package/ts_filelock/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@push.rocks/smartdaemon/file-lock`: the exclusive, advisory `flock(2)` lock on a descriptor the
+ * caller opened, through glibc called with `node:ffi`. There is no blocking lock: a caller that must
+ * wait polls `tryLockFile` on a timer. Requires Node.js 26 or later: importing it on an older
+ * Node.js throws `FileLockError` `runtime_unsupported`.
+ */
+import { assertFileLockNode } from './filelock.flock.js';
+
+export * from './filelock.classes.filelockerror.js';
+export { tryLockFile, unlockFile } from './filelock.flock.js';
+
+assertFileLockNode();

package/ts_systemdruntime/systemdruntime.libc.ts

@@ -4,17 +4,33 @@ 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 => {
+/**
+ * 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;
+
+const systemdRuntimeUnsupported: TLibcUnsupportedError = (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: string,
+  unsupportedArg: TLibcUnsupportedError,
+  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}.`,
+    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: string = process.versions.node): void =>
+  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:
@@ -27,6 +43,8 @@ export const assertSystemdRuntimeNode = (versionArg: string = process.versions.n
  *   `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,
@@ -40,7 +58,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,
 } as const;
 
 /** `sun_path` is 108 bytes; an address of up to 107 bytes keeps a path's terminating NUL. */
@@ -57,6 +79,7 @@ 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' },
 } as const satisfies ffi.FunctionDefinitions;
 
@@ -73,29 +96,27 @@ export interface ISystemdLibc {
 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.
+ * 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 = (): ISystemdLibc => {
+export const systemdLibc = (unsupportedArg: TLibcUnsupportedError = systemdRuntimeUnsupported): 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}.`,
-    );
+    throw unsupportedArg(`glibc calls through node:ffi support 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?).');
+    throw unsupportedArg('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',
+    throw unsupportedArg(
       'glibc (libc.so.6) could not be opened through node:ffi; under the permission model pass --allow-ffi.',
-      { cause: error },
+      error,
     );
   }
   loaded = Object.freeze({