@primafuture/systemd-tasks 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.2.0 — 2026-10-10
+
+- Add observed `finalizeAfterCompletion(reference, { afterRelease, timeoutMs })`:
+  an opt-in transient systemd-owned finalizer survives caller detach and death,
+  confirms payload/guardian cleanup, releases existing retention, and executes
+  one bounded native after-release command with finite stdin.
+- Bind repeated registrations to the exact reference and callback, preserve
+  truthful registration outcomes, and collect the finalizer itself after exit.
+- Cover post-payload reads with the same finalization deadline and honor native
+  callback stop grace through manager-owned cgroup termination.
+- Keep default retention, existing intent/reference formats, manual lifecycle,
+  and output ownership unchanged.
+
 ## 1.1.0 — 2026-09-17 (local candidate)
 
 - Add the `@primafuture/systemd-tasks/observed` entrypoint with immutable

package/README.md

@@ -4,7 +4,7 @@ Run one-shot Linux processes owned by the **systemd user manager**, with literal
 arguments, binary file-descriptor I/O, manager-owned timeouts, and recoverable
 results after the Node client exits or crashes.
 
-Version 1.1.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
+Version 1.2.0 requires Node 24.13.0+, Linux x64 with glibc 2.28+, systemd 257+,
 and cgroup v2. The verified environment
 is Node 24.13.0, systemd 257.9-0ubuntu2.4, Linux 6.17.0-14-generic, x86-64.
 Other versions satisfying those minimums are not independently verified.
@@ -147,6 +147,60 @@ order, so it drains bytes already written before completing. This also closes a
 guardian whose payload start was cancelled before exec. `release()` refuses until
 both process services are clean, then removes retention.
 
+### Automatic finalization of a background task
+
+Observed clients can explicitly hand completion to the user manager:
+
+```ts
+const found = await client.lookup(intent);
+if (found.status === 'found' && found.snapshot.identity === 'complete') {
+	await client.finalizeAfterCompletion(found.reference, {
+		timeoutMs: 30000,
+		afterRelease: {
+			executable: '/absolute/path/to/node',
+			argv: ['/absolute/path/to/application.mjs', '--finish-owned-record'],
+			cwd: '/absolute/application/directory',
+			env: {},
+			runtimeLimitMs: 10000,
+			stopGraceMs: 1000,
+			stdin: JSON.stringify({ generation: 'application-owned-generation' }),
+		},
+	});
+}
+```
+
+Register after persisting the exact reference and before advertising the background
+task as ready. A separate transient finalizer survives observer detach, CLI exit,
+and death of the original client. It does not stop the original task. It waits for
+payload termination and confirmed payload/guardian cleanup, uses the existing
+`release()` checks, and then executes the finite native command once, without a
+shell, inherited environment, or output replay. The command runs in the finalizer's
+own systemd control group; its output is discarded. The finalizer is collected
+after it exits, including failure. Safe error metadata remains in the journal.
+
+`timeoutMs` is one shared deadline for lookup, cleanup, release, and the
+after-release command once the finalizer confirms payload termination. It does
+not bound the task's active lifetime or restart for each phase. Callback runtime
+is also limited by its non-null `runtimeLimitMs`, when supplied. On timeout the
+finalizer exits; systemd stops its remaining command processes with `SIGTERM`,
+allows `stopGraceMs`, and escalates to `SIGKILL` only if necessary. Stop grace is
+a separate bounded cleanup interval, not additional execution time. The callback
+may not be a resident service. A timed-out read or release never starts the callback.
+
+The receipt says `accepted` or `already-registered`, not `completed`. An identical
+registration while the finalizer exists does not create another callback. A
+different callback for the same task is a conflict. An unknown registration outcome
+must be reconciled before proceeding; never blindly submit a replacement task.
+Failed cleanup does not execute the callback. Callback failure does not restore
+released task results or automatically retry the callback.
+
+This is deliberately opt-in and does not change the default retention policy.
+After handing finalization off, do not rely on a late `wait()` retaining an exit
+result: release can win that race. Applications should confirm their own cleanup
+effect plus absence of the exact task rather than fabricate an exit status. The
+callback must condition its own changes on its persisted generation. Recovery is
+still required for a client death before registration and for manager restart.
+
 ## Lifecycle and recovery
 
 | Operation | Contract |
@@ -160,6 +214,7 @@ both process services are clean, then removes retention.
 | `stop(reference, options?)` | Request manager stop; `wait: true` additionally waits for cleanup. |
 | `release(reference, options?)` | Refuse live tasks, then discard owned result retention. Never deletes logs. |
 | `disconnect()` | Release local socket/listeners only; tasks keep running. Idempotent. |
+| Observed `finalizeAfterCompletion(reference, options)` | Register exact manager-owned cleanup followed by one finite native command. Opt-in, not a completion receipt. |
 
 Save the **intent before calling start**, then save an observed reference and final
 result as they become available. Intents contain the command and environment,

package/dist/finalizer.mjs

@@ -0,0 +1,448 @@
+// src/finalizer.ts
+import * as childProcess from "child_process";
+import * as performance from "perf_hooks";
+import * as timers from "timers/promises";
+
+// src/observed-finalization.ts
+import * as crypto3 from "crypto";
+import * as fs from "fs/promises";
+import * as path2 from "path";
+
+// src/errors.ts
+import * as util from "util";
+var TaskError = class extends Error {
+  /** Stable category used by applications instead of parsing human-readable messages. */
+  code;
+  /** Safe delivery and identity metadata; never contains a command specification. */
+  details;
+  /** Preserve the original cause for explicit access while keeping default output redacted. */
+  constructor(code, message, details = {}, cause) {
+    super(message, cause === void 0 ? void 0 : { cause });
+    this.name = "TaskError";
+    this.code = code;
+    this.details = Object.freeze({ ...details });
+  }
+  /** Serialization deliberately excludes raw causes, stack contents, and request payloads. */
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message, details: this.details };
+  }
+  /** Console and util.inspect must not expand a transport cause containing request data. */
+  [util.inspect.custom]() {
+    return `${this.name} [${this.code}]: ${this.message}`;
+  }
+};
+
+// src/observed-validation.ts
+import * as crypto2 from "crypto";
+
+// src/validation.ts
+import * as crypto from "crypto";
+import * as path from "path";
+var maximumLocalTimeoutMs = 2147483647;
+var maximumDurationMs = Number.MAX_SAFE_INTEGER;
+function invalid(reason) {
+  throw new TaskError("INVALID_INPUT", "The task request is invalid.", { reason, mutationOutcome: "not-submitted" });
+}
+function record(value, reason) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) invalid(reason);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) invalid(reason);
+  return value;
+}
+function keys(value, allowed, reason) {
+  if (Object.keys(value).some(
+    /** Reject keys outside the explicit contract allowlist. */
+    (key) => !allowed.includes(key)
+  ) || Object.getOwnPropertySymbols(value).length > 0) invalid(reason);
+}
+function string(value, reason) {
+  if (typeof value !== "string" || value.includes("\0")) invalid(reason);
+  for (const character of value) {
+    const code = character.codePointAt(0);
+    if (code >= 55296 && code <= 57343) invalid(reason);
+  }
+  return value;
+}
+function absolutePath(value, reason) {
+  const result = string(value, reason);
+  if (!path.posix.isAbsolute(result)) invalid(reason);
+  return result;
+}
+function duration(value, maximum, reason) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) invalid(reason);
+  return value;
+}
+function validateSpec(value) {
+  const source = record(value, "spec-object");
+  keys(source, ["executable", "argv", "cwd", "env", "runtimeLimitMs", "stopGraceMs", "systemdProperties"], "spec-keys");
+  const executable = absolutePath(source.executable, "executable-path");
+  const cwd = absolutePath(source.cwd, "cwd-path");
+  if (!Array.isArray(source.argv)) invalid("argv-array");
+  const argv = Object.freeze(source.argv.map(
+    /** Validate literal arguments without shell expansion or coercion. */
+    (value2) => string(value2, "argv-string")
+  ));
+  const environment = record(source.env, "environment-object");
+  const env = /* @__PURE__ */ Object.create(null);
+  for (const key of Object.keys(environment).sort()) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) invalid("environment-name");
+    env[key] = string(environment[key], "environment-value");
+  }
+  const runtimeLimitMs = source.runtimeLimitMs === null ? null : duration(source.runtimeLimitMs, maximumDurationMs, "runtime-limit");
+  const stopGraceMs = duration(source.stopGraceMs, maximumDurationMs, "stop-grace");
+  const properties = [];
+  if (source.systemdProperties !== void 0) {
+    if (!Array.isArray(source.systemdProperties)) invalid("properties-array");
+    const names = /* @__PURE__ */ new Set();
+    for (const value2 of source.systemdProperties) {
+      const property = record(value2, "property-object");
+      keys(property, ["name", "signature", "value"], "property-keys");
+      if (property.name !== "CPUWeight" && property.name !== "IOWeight") invalid("reserved-or-unsupported-property");
+      if (property.signature !== "t") invalid("property-signature");
+      if (names.has(property.name)) invalid("duplicate-property");
+      names.add(property.name);
+      properties.push(Object.freeze({ name: property.name, signature: "t", value: duration(property.value, 1e4, "property-value") }));
+    }
+  }
+  properties.sort(
+    /** Canonicalize resource ordering for a stable specification fingerprint. */
+    (left, right) => left.name.localeCompare(right.name)
+  );
+  return Object.freeze({ executable, argv, cwd, env: Object.freeze(env), runtimeLimitMs, stopGraceMs, systemdProperties: Object.freeze(properties) });
+}
+function uuid(value, reason) {
+  const result = string(value, reason);
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(result)) invalid(reason);
+  return result;
+}
+function digest(value, reason) {
+  const result = string(value, reason);
+  if (!/^[0-9a-f]{64}$/.test(result)) invalid(reason);
+  return result;
+}
+function validateInvocationId(value) {
+  if (value === null) return null;
+  const result = string(value, "invocation-id");
+  if (!/^[0-9a-f]{32}$/.test(result)) invalid("invocation-id");
+  return result;
+}
+function validateManagerIdentity(value) {
+  const source = record(value, "manager-identity");
+  keys(source, ["scope", "uid", "machineId", "bootId", "busId", "owner"], "manager-keys");
+  if (source.scope !== "user" || typeof source.uid !== "number" || !Number.isSafeInteger(source.uid) || source.uid < 0) invalid("manager-scope-or-uid");
+  const machineId = string(source.machineId, "machine-id");
+  const busId = string(source.busId, "bus-id");
+  const bootId = string(source.bootId, "boot-id");
+  const owner = string(source.owner, "manager-owner");
+  if (!/^[0-9a-f]{32}$/.test(machineId) || !/^[0-9a-f]{32}$/.test(busId)) invalid("manager-identifiers");
+  if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(bootId) || !/^:[0-9]+\.[0-9]+$/.test(owner)) invalid("manager-identifiers");
+  return Object.freeze({ scope: "user", uid: source.uid, machineId, bootId, busId, owner });
+}
+
+// src/observed-validation.ts
+var maximumObservedInputBytes = 512 * 1024;
+var maximumObservedInputBase64Characters = 4 * Math.ceil(maximumObservedInputBytes / 3);
+var observedUnitPrefix = "pf-systemd-tasks-observed-";
+var observedIdentityKeys = [
+  "kind",
+  "version",
+  "protocolVersion",
+  "id",
+  "unitName",
+  "retentionUnitName",
+  "guardianUnitName",
+  "managerScope",
+  "fingerprint"
+];
+function normalizeSpec(value) {
+  const source = record(value, "observed-spec-object");
+  keys(source, ["executable", "argv", "cwd", "env", "runtimeLimitMs", "stopGraceMs", "systemdProperties", "stdin"], "observed-spec-keys");
+  const spec = validateSpec({
+    executable: source.executable,
+    argv: source.argv,
+    cwd: source.cwd,
+    env: source.env,
+    runtimeLimitMs: source.runtimeLimitMs,
+    stopGraceMs: source.stopGraceMs,
+    ...source.systemdProperties === void 0 ? {} : { systemdProperties: source.systemdProperties }
+  });
+  if (source.stdin === null) return Object.freeze({ spec, stdinBase64: null });
+  let bytes;
+  if (typeof source.stdin === "string") bytes = Buffer.from(source.stdin, "utf8");
+  else if (source.stdin instanceof Uint8Array) bytes = Buffer.from(source.stdin);
+  else return invalid("observed-stdin");
+  if (bytes.byteLength > maximumObservedInputBytes) invalid("observed-stdin-limit");
+  return Object.freeze({ spec, stdinBase64: bytes.toString("base64") });
+}
+function identity(source) {
+  if (source.kind !== "observed" || source.version !== 1 || source.protocolVersion !== 1 || source.managerScope !== "user") invalid("observed-identity-version-or-scope");
+  const id = uuid(source.id, "observed-identity-id");
+  if (source.unitName !== `${observedUnitPrefix}${id}.service` || source.retentionUnitName !== `${observedUnitPrefix}${id}-retention.service` || source.guardianUnitName !== `${observedUnitPrefix}${id}-guardian.service`) invalid("observed-identity-unit-name");
+  return Object.freeze({
+    kind: "observed",
+    version: 1,
+    protocolVersion: 1,
+    id,
+    unitName: source.unitName,
+    retentionUnitName: source.retentionUnitName,
+    guardianUnitName: source.guardianUnitName,
+    managerScope: "user",
+    fingerprint: digest(source.fingerprint, "observed-identity-fingerprint")
+  });
+}
+function validateObservedReference(value) {
+  const source = record(value, "observed-reference-object");
+  keys(source, [...observedIdentityKeys, "manager", "invocationId", "retentionInvocationId", "guardianInvocationId"], "observed-reference-keys");
+  return Object.freeze({
+    ...identity(source),
+    manager: validateManagerIdentity(source.manager),
+    invocationId: validateInvocationId(source.invocationId),
+    retentionInvocationId: validateInvocationId(source.retentionInvocationId),
+    guardianInvocationId: validateInvocationId(source.guardianInvocationId)
+  });
+}
+
+// src/observed-finalization.ts
+var maximumBootstrapBytes = maximumObservedInputBytes * 2;
+function requireCompleteReference(value) {
+  const reference = validateObservedReference(value);
+  if (!reference.invocationId || !reference.retentionInvocationId || !reference.guardianInvocationId) {
+    invalid("finalization-reference-incomplete");
+  }
+  return reference;
+}
+function prepare(reference, value) {
+  const source = record(value, "finalization-options");
+  keys(source, ["afterRelease", "timeoutMs"], "finalization-option-keys");
+  return Object.freeze({
+    reference: requireCompleteReference(reference),
+    timeoutMs: duration(source.timeoutMs, maximumLocalTimeoutMs, "finalization-timeout"),
+    afterRelease: normalizeSpec(source.afterRelease)
+  });
+}
+function parse(value) {
+  const source = record(value, "finalization-bootstrap");
+  keys(source, ["reference", "timeoutMs", "afterRelease"], "finalization-bootstrap-keys");
+  const afterRelease2 = record(source.afterRelease, "finalization-after-release");
+  keys(afterRelease2, ["spec", "stdinBase64"], "finalization-after-release-keys");
+  const spec = validateSpec(afterRelease2.spec);
+  let stdin = null;
+  if (afterRelease2.stdinBase64 !== null) {
+    const encoded = string(afterRelease2.stdinBase64, "finalization-stdin");
+    if (encoded.length > 4 * Math.ceil(maximumObservedInputBytes / 3)) {
+      invalid("finalization-stdin-limit");
+    }
+    stdin = Buffer.from(encoded, "base64");
+    if (stdin.toString("base64") !== encoded) {
+      invalid("finalization-stdin-base64");
+    }
+  }
+  return prepare(requireCompleteReference(source.reference), {
+    timeoutMs: duration(source.timeoutMs, maximumLocalTimeoutMs, "finalization-timeout"),
+    afterRelease: { ...spec, stdin }
+  });
+}
+
+// src/finalizer.ts
+import * as runtime from "#runtime";
+
+// src/waiting.ts
+var WaitControl = class {
+  /** Internal cancellation combines the caller's abort with a local deadline. */
+  controller = new AbortController();
+  /** Local timer, absent for an explicitly unbounded wait. */
+  timer;
+  /** Caller signal whose listener must be removed at settlement. */
+  external;
+  /** Captured listener identity allows deterministic cleanup. */
+  onAbort;
+  /** A timeout is an observation deadline, never a manager escalation timeout. */
+  constructor(options) {
+    this.external = options.signal;
+    this.onAbort = /** Propagate caller cancellation into this local wait scope only. */
+    () => this.controller.abort(new TaskError("WAIT_ABORTED", "Local waiting was aborted."));
+    if (options.timeoutMs !== void 0) this.timer = setTimeout(
+      /** Expire local observation without changing systemd execution timers. */
+      () => this.controller.abort(new TaskError("WAIT_TIMEOUT", "The local waiting deadline expired.")),
+      options.timeoutMs
+    );
+    if (this.external?.aborted) this.onAbort();
+    else this.external?.addEventListener("abort", this.onAbort, { once: true });
+  }
+  /** Refuse an already-cancelled operation before it can submit a mutation. */
+  check() {
+    if (this.controller.signal.aborted) throw this.controller.signal.reason;
+  }
+  /** Stop this caller's observation while leaving a shared request or server mutation intact. */
+  async race(promise) {
+    if (this.controller.signal.aborted) {
+      void promise.catch(
+        /** Consume eventual settlement of work that outlives the cancelled caller. */
+        () => {
+        }
+      );
+      this.check();
+    }
+    const signal = this.controller.signal;
+    let abort;
+    const cancelled = new Promise(
+      /** Bridge local cancellation into the current asynchronous observation. */
+      (_resolve, reject) => {
+        abort = /** Reject with the original local cancellation category. */
+        () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+      }
+    );
+    try {
+      return await Promise.race([promise, cancelled]);
+    } finally {
+      if (abort) signal.removeEventListener("abort", abort);
+    }
+  }
+  /** Remove every local timer and listener without touching a running task. */
+  dispose() {
+    clearTimeout(this.timer);
+    this.external?.removeEventListener("abort", this.onAbort);
+  }
+};
+
+// src/finalizer.ts
+async function readBootstrap() {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    const buffer = Buffer.from(chunk);
+    bytes += buffer.byteLength;
+    if (bytes > maximumBootstrapBytes) {
+      throw new TaskError("INVALID_INPUT", "The finalizer input exceeds its bound.", {
+        reason: "finalization-bootstrap-limit"
+      });
+    }
+    chunks.push(buffer);
+  }
+  return parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+}
+async function afterRelease(bootstrap, timeoutMs) {
+  const spec = bootstrap.afterRelease.spec;
+  const runtimeMs = Math.min(timeoutMs, spec.runtimeLimitMs ?? timeoutMs);
+  const control = new WaitControl({ timeoutMs: runtimeMs });
+  try {
+    control.check();
+    await control.race(new Promise(
+      /** Spawn neposkytuje shell, děděné env ani výstup do veřejné diagnostiky. */
+      (resolve2, reject) => {
+        const child = childProcess.spawn(spec.executable, [...spec.argv], {
+          cwd: spec.cwd,
+          env: { ...spec.env },
+          stdio: [bootstrap.afterRelease.stdinBase64 === null ? "ignore" : "pipe", "ignore", "ignore"],
+          shell: false
+        });
+        let failure;
+        child.once(
+          "error",
+          /** Uchová chybu exec; close uzavře i vlastněné descriptors. */
+          (error) => {
+            failure = error;
+          }
+        );
+        child.stdin?.once(
+          "error",
+          /** Nedokončený bootstrap se nesmí vydávat za úspěšný callback. */
+          (error) => {
+            failure = error;
+          }
+        );
+        child.once(
+          "close",
+          /** Výsledek dítěte není výsledek původního payloadu. */
+          (code, signal) => {
+            if (failure !== void 0 || code !== 0 || signal !== null) {
+              reject(new TaskError("RESULT_UNAVAILABLE", "The after-release command did not complete successfully.", {
+                reason: "after-release-failed",
+                taskId: bootstrap.reference.id
+              }, failure));
+              return;
+            }
+            resolve2();
+          }
+        );
+        if (bootstrap.afterRelease.stdinBase64 !== null) {
+          child.stdin.end(Buffer.from(bootstrap.afterRelease.stdinBase64, "base64"));
+        }
+      }
+    ));
+  } finally {
+    control.dispose();
+  }
+}
+async function run() {
+  const bootstrap = await readBootstrap();
+  const client = await runtime.connectObserved();
+  const budget = { deadline: null, control: null };
+  try {
+    const remaining = () => {
+      if (budget.deadline === null) {
+        budget.deadline = performance.performance.now() + bootstrap.timeoutMs;
+        budget.control = new WaitControl({ timeoutMs: bootstrap.timeoutMs });
+      }
+      budget.control.check();
+      const milliseconds = Math.floor(budget.deadline - performance.performance.now());
+      if (milliseconds <= 0) {
+        throw new TaskError("WAIT_TIMEOUT", "The finalization deadline expired.", {
+          reason: "finalization-timeout",
+          taskId: bootstrap.reference.id
+        });
+      }
+      return milliseconds;
+    };
+    for (; ; ) {
+      budget.control?.check();
+      const found = await (budget.control === null ? client.lookup(bootstrap.reference) : budget.control.race(client.lookup(bootstrap.reference)));
+      if (found.status === "not-found") {
+        break;
+      }
+      if (found.status === "incomplete" || found.snapshot.payload.managerTerminal) {
+        remaining();
+      }
+      if (found.status === "found" && found.snapshot.phase === "completed") {
+        break;
+      }
+      if (found.status === "incomplete" || found.snapshot.guardian.managerTerminal) {
+        const delayMs = Math.min(remaining(), 50);
+        await budget.control.race(timers.setTimeout(delayMs));
+        continue;
+      }
+      try {
+        const waitOptions = { timeoutMs: budget.deadline === null ? 1e3 : Math.min(remaining(), 1e3) };
+        const snapshot = await (budget.control === null ? client.wait(bootstrap.reference, waitOptions) : budget.control.race(client.wait(bootstrap.reference, waitOptions)));
+        if (snapshot.payload.managerTerminal) {
+          remaining();
+        }
+        if (snapshot.phase === "completed") {
+          break;
+        }
+      } catch (error) {
+        if (!(error instanceof runtime.TaskError) || error.code !== "WAIT_TIMEOUT" && error.code !== "RESULT_UNAVAILABLE") {
+          throw error;
+        }
+      }
+    }
+    const releaseTimeoutMs = remaining();
+    await budget.control.race(client.release(bootstrap.reference, { timeoutMs: releaseTimeoutMs }));
+    const callbackTimeoutMs = remaining();
+    await budget.control.race(afterRelease(bootstrap, callbackTimeoutMs));
+  } finally {
+    budget.control?.dispose();
+    await client.disconnect();
+  }
+}
+void run().catch(
+  /** Journal dostane pouze vlastní redigovanou chybu, nikdy cizí payload. */
+  (error) => {
+    const reported = error instanceof TaskError || error instanceof runtime.TaskError ? error : new TaskError("RESULT_UNAVAILABLE", "The observed task finalizer failed.", { reason: "finalization-failed" });
+    process.stderr.write(`${JSON.stringify(reported.toJSON())}
+`);
+    process.exit(1);
+  }
+);
+//# sourceMappingURL=finalizer.mjs.map