@push.rocks/smartdaemon 3.0.0 → 3.2.0

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({