@smthrs/platform-node 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/internal/WindowsProcessJob.js

@@ -0,0 +1,115 @@
+/**
+ * A native Windows job guardian, attached before the owner can launch a target.
+ * @since 1.0.0
+ */
+import { spawn } from "node:child_process";
+import { parse } from "node:path";
+import { packageRoot, resolveConfiguredExecutable, resolveDefaultExecutable } from "./AtomicFileSystemExecutable.js";
+import { processFault } from "./ProcessFault.js";
+const deferred = () => {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => {
+        resolve = yes;
+        reject = no;
+    });
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+};
+/**
+ * Resolve the same trusted helper for the owner's self-observation and guardian.
+ * @private
+ * @since 1.0.0
+ */
+export const resolveJobExecutable = () => {
+    const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY;
+    return configured === undefined
+        ? resolveDefaultExecutable(packageRoot, undefined)
+        : resolveConfiguredExecutable(configured, undefined);
+};
+/**
+ * Retains the guardian's dedicated control pipe until cleanup. EOF, including
+ * host death, terminates the job independently of the Node owner's event loop.
+ * @private
+ * @since 1.0.0
+ */
+export class WindowsProcessJob {
+    ready = deferred();
+    settled = deferred();
+    child;
+    receivedReady = false;
+    receivedSettled = false;
+    failed = false;
+    constructor(ownerPid, created, executable) {
+        if (typeof created !== "string" || !/^[1-9][0-9]{0,19}$/.test(created)) {
+            throw processFault("owner_identity_missing", "Windows process owner has no exact creation identity");
+        }
+        const options = { cwd: parse(process.execPath).root, env: {}, windowsHide: true };
+        this.child = spawn(executable, ["--process-job", String(ownerPid), created], {
+            ...options,
+            stdio: ["pipe", "pipe", "pipe"]
+        });
+        let buffer = "";
+        this.child.stdout.setEncoding("utf8");
+        this.child.stdout.on("data", (data) => {
+            if (this.failed)
+                return;
+            try {
+                buffer += data;
+                if (Buffer.byteLength(buffer) > 4096) {
+                    throw processFault("status_too_large", "Windows job status exceeds its bound");
+                }
+                for (;;) {
+                    const end = buffer.indexOf("\n");
+                    if (end < 0)
+                        break;
+                    const frame = JSON.parse(buffer.slice(0, end));
+                    buffer = buffer.slice(end + 1);
+                    if (frame?.status === "ready" && frame.ownerPid === ownerPid && !this.receivedReady) {
+                        this.receivedReady = true;
+                        this.ready.resolve();
+                    }
+                    else if (frame?.status === "settled" && this.receivedReady && !this.receivedSettled) {
+                        this.receivedSettled = true;
+                    }
+                    else
+                        throw processFault("status_invalid", "Invalid Windows job status");
+                }
+            }
+            catch (cause) {
+                this.fail(cause);
+            }
+        });
+        // Drain diagnostics without retaining unbounded native output.
+        this.child.stderr.resume();
+        this.child.once("error", (cause) => this.fail(cause));
+        this.child.stdin.on("error", (cause) => this.fail(cause));
+        this.child.stdout.on("error", (cause) => this.fail(cause));
+        this.child.stderr.on("error", (cause) => this.fail(cause));
+        this.child.once("close", (code, signal) => {
+            if (!this.failed && code === 0 && signal === null && this.receivedSettled && buffer === "") {
+                this.settled.resolve();
+            }
+            else
+                this.fail(processFault("cleanup_unverified", "Windows job cleanup could not be verified"));
+        });
+    }
+    fail(cause) {
+        this.failed = true;
+        this.ready.reject(cause);
+        this.settled.reject(cause);
+        this.stop();
+    }
+    /** Closing this pipe asks the native guardian to terminate its job. */
+    stop() {
+        this.child.stdin.destroy();
+    }
+    /** Keep the guardian and all three pipes consistent with the host handle. */
+    reference(referenced) {
+        const method = referenced ? "ref" : "unref";
+        this.child[method]();
+        for (const pipe of [this.child.stdin, this.child.stdout, this.child.stderr])
+            pipe[method]();
+    }
+}
+//# sourceMappingURL=WindowsProcessJob.js.map

package/dist/esm/internal/WindowsProcessJob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WindowsProcessJob.js","sourceRoot":"","sources":["../../../src/internal/WindowsProcessJob.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A native Windows job guardian, attached before the owner can launch a target.\n * @since 1.0.0\n */\n\nimport { spawn } from \"node:child_process\"\nimport type { Socket } from \"node:net\"\nimport { parse } from \"node:path\"\nimport { packageRoot, resolveConfiguredExecutable, resolveDefaultExecutable } from \"./AtomicFileSystemExecutable.ts\"\nimport { processFault } from \"./ProcessFault.ts\"\n\nconst deferred = <A>() => {\n  let resolve!: (value: A) => void\n  let reject!: (cause: unknown) => void\n  const promise = new Promise<A>((yes, no) => {\n    resolve = yes\n    reject = no\n  })\n  void promise.catch(() => {})\n  return { promise, resolve, reject }\n}\n\n/**\n * Resolve the same trusted helper for the owner's self-observation and guardian.\n * @private\n * @since 1.0.0\n */\nexport const resolveJobExecutable = (): string => {\n  const configured = process.env.SMITHERS_WORKSPACE_JJ_EXPORT_BINARY\n  return configured === undefined\n    ? resolveDefaultExecutable(packageRoot, undefined)\n    : resolveConfiguredExecutable(configured, undefined)\n}\n\n/**\n * Retains the guardian's dedicated control pipe until cleanup. EOF, including\n * host death, terminates the job independently of the Node owner's event loop.\n * @private\n * @since 1.0.0\n */\nexport class WindowsProcessJob {\n  readonly ready = deferred<void>()\n  readonly settled = deferred<void>()\n  private readonly child\n  private receivedReady = false\n  private receivedSettled = false\n  private failed = false\n\n  constructor(ownerPid: number, created: unknown, executable: string) {\n    if (typeof created !== \"string\" || !/^[1-9][0-9]{0,19}$/.test(created)) {\n      throw processFault(\"owner_identity_missing\", \"Windows process owner has no exact creation identity\")\n    }\n    const options = { cwd: parse(process.execPath).root, env: {}, windowsHide: true }\n    this.child = spawn(executable, [\"--process-job\", String(ownerPid), created], {\n      ...options,\n      stdio: [\"pipe\", \"pipe\", \"pipe\"]\n    })\n    let buffer = \"\"\n    this.child.stdout.setEncoding(\"utf8\")\n    this.child.stdout.on(\"data\", (data: string) => {\n      if (this.failed) return\n      try {\n        buffer += data\n        if (Buffer.byteLength(buffer) > 4096) {\n          throw processFault(\"status_too_large\", \"Windows job status exceeds its bound\")\n        }\n        for (;;) {\n          const end = buffer.indexOf(\"\\n\")\n          if (end < 0) break\n          const frame = JSON.parse(buffer.slice(0, end)) as { status?: unknown; ownerPid?: unknown } | null\n          buffer = buffer.slice(end + 1)\n          if (frame?.status === \"ready\" && frame.ownerPid === ownerPid && !this.receivedReady) {\n            this.receivedReady = true\n            this.ready.resolve()\n          } else if (frame?.status === \"settled\" && this.receivedReady && !this.receivedSettled) {\n            this.receivedSettled = true\n          } else throw processFault(\"status_invalid\", \"Invalid Windows job status\")\n        }\n      } catch (cause) {\n        this.fail(cause)\n      }\n    })\n    // Drain diagnostics without retaining unbounded native output.\n    this.child.stderr.resume()\n    this.child.once(\"error\", (cause) => this.fail(cause))\n    this.child.stdin.on(\"error\", (cause) => this.fail(cause))\n    this.child.stdout.on(\"error\", (cause) => this.fail(cause))\n    this.child.stderr.on(\"error\", (cause) => this.fail(cause))\n    this.child.once(\"close\", (code, signal) => {\n      if (!this.failed && code === 0 && signal === null && this.receivedSettled && buffer === \"\") {\n        this.settled.resolve()\n      } else this.fail(processFault(\"cleanup_unverified\", \"Windows job cleanup could not be verified\"))\n    })\n  }\n\n  private fail(cause: unknown): void {\n    this.failed = true\n    this.ready.reject(cause)\n    this.settled.reject(cause)\n    this.stop()\n  }\n\n  /** Closing this pipe asks the native guardian to terminate its job. */\n  stop(): void {\n    this.child.stdin.destroy()\n  }\n\n  /** Keep the guardian and all three pipes consistent with the host handle. */\n  reference(referenced: boolean): void {\n    const method = referenced ? \"ref\" : \"unref\"\n    this.child[method]()\n    for (const pipe of [this.child.stdin, this.child.stdout, this.child.stderr]) (pipe as Socket)[method]()\n  }\n}\n"]}