@orkestrel/process 0.0.5 → 0.0.6

package/dist/src/server/index.js

@@ -4,7 +4,7 @@ import { statSync } from "node:fs";
 import { join, posix, win32 } from "node:path";
 import { platform } from "node:process";
 import { boundsOf, holds, isNonEmptyString, isNonNegativeInteger, isString } from "@orkestrel/contract";
-import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
+import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError } from "../core/index.js";
 import { createInterface } from "node:readline";
 import { StringDecoder } from "node:string_decoder";
 import { Emitter } from "@orkestrel/emitter";
@@ -592,17 +592,41 @@ function waitForExit(child, timeout) {
 	return settled.promise.finally(() => clearTimeout(timer));
 }
 /**
+* Waits for one child process's streams to close, bounded by a deadline.
+*
+* @param child - The child boundary
+* @param timeout - The milliseconds to wait before giving up
+* @returns True when the host close arrived inside the deadline; false otherwise
+*
+* @example
+* ```ts
+* const closed = await waitForClose(child, 5_000)
+* ```
+*/
+function waitForClose(child, timeout) {
+	const closed = Promise.withResolvers();
+	const expired = Promise.withResolvers();
+	const timer = setTimeout(() => expired.resolve(false), timeout);
+	child.once("close", closed.resolve);
+	return Promise.race([closed.promise.then(() => true), expired.promise]).finally(() => {
+		clearTimeout(timer);
+		child.off("close", closed.resolve);
+	});
+}
+/**
 * Terminates one child process tree and reports whether its native exit was observed.
 *
 * @remarks
-* Windows ends the whole tree at once through {@link killTree}, falling back to a direct kill after
-* the utility fails, because the host has no cooperative termination to offer. A POSIX host signals
-* the process group `SIGTERM`, falls back to the direct child when no group owns its pid, waits
-* `grace`, then sends `SIGKILL` through the same route. No signal is initiated after the native exit
-* is observed; the window between initiating a signal and the host delivering it belongs to the
-* operating system. `confirm` bounds each awaited step rather than the call as a whole: on Windows
-* it bounds the `taskkill` call and then the final wait, and on a POSIX host `grace` bounds the
-* cooperative wait and `confirm` the final one. Never rejects.
+* An already-exited child is returned on before any route to its pid runs, because the host has
+* reaped that number and may have handed it to another process. Windows ends the whole tree at once
+* through {@link killTree}, falling back to a direct kill after the utility fails, because the host
+* has no cooperative termination to offer. A POSIX host signals the process group `SIGTERM`, falls
+* back to the direct child when no group owns its pid, waits `grace`, then sends `SIGKILL` through
+* the same route. No signal is initiated after the native exit is observed; the window between
+* initiating a signal and the host delivering it belongs to the operating system. `confirm` bounds
+* each awaited step rather than the call as a whole: on Windows it bounds the `taskkill` call and
+* then the final wait, and on a POSIX host `grace` bounds the cooperative wait and `confirm` the
+* final one. Never rejects.
 *
 * @param child - The child boundary
 * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
@@ -670,29 +694,23 @@ function buildExecuteResult(input) {
 //#endregion
 //#region src/server/Process.ts
 /**
-* One supervised child process with framed output, a bounded backlog, and bounded termination.
+* Supervises one child while keeping every observation channel aligned at termination.
 *
 * @remarks
-* Standard output is framed through `readline` into a single-consumer stream: each line goes to
-* exactly one waiting iterator, so concurrent iterators split the output rather than each receiving
-* all of it. While no consumer has ever requested an iterator, stdout keeps draining so `exit` still
-* resolves, and retention stops at the `backlog` mark: a
-* consumer attaching later receives the retained head, a gap, then the live stream. After an iterator
-* has been requested, stdout pauses at the mark and resumes at half of it, so that consumer loses
-* nothing before termination and the child feels real backpressure. The mark is soft — the ordinary backlog can
-* overshoot it by the line that crossed it plus the rest of its delivered chunk. Termination never
-* reapplies backpressure, and retained lines are capped at twice `backlog`; later lines are dropped
-* and `truncated` reports the omission. Standard error is decoded and forwarded live as the `stderr`
-* event while a byte-bounded raw tail is retained as `evidence`. The typed `emitter` also carries a
-* child `error` cause on a spawn fault, a `protocol` {@link ProcessError} on a host-reported stdin
-* fault after the constructor input phase, and the terminal `exit`, alongside the `exit` promise.
-* A fault arising from the constructor-supplied `input` write or its closing `end` stays quiet
-* because the package initiated that sequence. `pid`,
-* `code`, and `signal` read the spawned child directly, so the native exit is readable before the
-* `exit` promise settles on stdio close. `stop` ends the whole tree and reports whether the native
-* exit was observed; `destroy` stops the child, destroys stdin so every pending `send` settles, and
-* destroys the emitter last. `destroy` resolving does not imply the child's stdio has closed, so
-* `exit` and `lines` can still be outstanding when a descendant holds an inherited pipe.
+* The child's ending and the supervision's ending are distinct. `pid`, `code`, and `signal` read
+* the host child directly, so they expose native exit as soon as the host records it. `settled`,
+* `exit`, `evidence`, and `lines` reach one terminal moment after the read channels close or the
+* bounded `drain` window cuts them off. That window is armed by the child's native exit and by a
+* termination this package initiated, so every way a child can end reaches the moment. The terminal
+* routine freezes `evidence` and ends `lines` before it destroys stdout, stderr, or the emitter, so
+* the push channel never disappears while a pull channel can still change or wait indefinitely.
+*
+* Standard output is framed through `readline` into a single-consumer stream. Lines already framed
+* and queued remain available through the terminal moment, while bytes arriving after a requested
+* termination may be cut off. Standard error is forwarded through the live `stderr` event and
+* retained as a byte-bounded raw tail until that same moment. `stop` ends the child tree and the
+* observation surfaces. `destroy` performs that stop and then destroys the emitter after the
+* frozen terminal state exists.
 *
 * @example
 * ```ts
@@ -711,6 +729,7 @@ var Process = class {
 	#child;
 	#reader;
 	#grace;
+	#drain;
 	#evidence;
 	#backlog;
 	#delivery;
@@ -728,12 +747,13 @@ var Process = class {
 	#requested = false;
 	#paused = false;
 	#truncated = false;
-	#terminating = false;
-	#closed = false;
+	#stopping = false;
+	#settled = false;
 	#ended = false;
 	#input = 0;
 	#failure;
-	#stopping;
+	#waiting;
+	#termination;
 	#ending;
 	/**
 	* Spawn one child process and begin stream capture.
@@ -745,6 +765,7 @@ var Process = class {
 		const source = options.command;
 		const workspace = options.workspace;
 		const grace = options.grace;
+		const drain = options.drain;
 		const evidence = options.evidence;
 		const backlog = options.backlog;
 		const delivery = options.delivery;
@@ -757,6 +778,7 @@ var Process = class {
 		validateCommand(command);
 		validateWorkspace(workspace);
 		validateTimer(grace, "option 'grace'");
+		validateTimer(drain, "option 'drain'");
 		validateTimer(delivery, "option 'delivery'");
 		validateBytes(evidence, "option 'evidence'", 0);
 		validateBytes(backlog, "option 'backlog'", 1);
@@ -765,6 +787,7 @@ var Process = class {
 			...error === void 0 ? {} : { error }
 		});
 		this.#grace = grace ?? PROCESS_GRACE;
+		this.#drain = drain ?? PROCESS_DRAIN;
 		this.#evidence = evidence ?? PROCESS_EVIDENCE;
 		this.#backlog = backlog ?? PROCESS_BACKLOG;
 		this.#delivery = delivery ?? 0;
@@ -794,6 +817,7 @@ var Process = class {
 		this.#reader.on("line", this.#push.bind(this));
 		this.#reader.once("close", this.#finish.bind(this));
 		this.#child.once("error", (cause) => this.#emitter.emit("error", cause));
+		this.#child.once("exit", this.#expire.bind(this));
 		this.#child.once("close", this.#close.bind(this));
 		this.#child.stdin.on("error", (cause) => this.#failInputStream(cause));
 		this.#child.stderr.on("data", this.#retain.bind(this));
@@ -827,11 +851,11 @@ var Process = class {
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The captured stdout lines, in arrival order, ending when the child's stdout closes. */
+	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
 	get lines() {
 		return this.#lines;
 	}
-	/** The decoded byte-bounded stderr tail. */
+	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#tail.toString("utf8");
 	}
@@ -839,7 +863,15 @@ var Process = class {
 	get truncated() {
 		return this.#truncated;
 	}
-	/** The terminal child state, observed once from the close event. */
+	/** True after the terminal moment arrived and `exit` settled. */
+	get settled() {
+		return this.#settled;
+	}
+	/** True after termination began, including after the terminal moment. */
+	get stopping() {
+		return this.#stopping;
+	}
+	/** The terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#exit.promise;
 	}
@@ -862,7 +894,7 @@ var Process = class {
 	*/
 	send(text) {
 		const stdin = this.#child.stdin;
-		if (this.#closed || this.#terminating || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
+		if (this.#settled || this.#stopping || this.#failure !== void 0 || !stdin.writable) return Promise.resolve(false);
 		const settled = Promise.withResolvers();
 		this.#writes.set(settled, void 0);
 		try {
@@ -879,29 +911,32 @@ var Process = class {
 		return settled.promise;
 	}
 	/**
-	* Terminate the child process tree and await its observed exit.
+	* Terminates the child process tree and reaches the terminal observation moment.
 	*
 	* @remarks
-	* Never rejects, and every call shares one termination.
+	* Never rejects, and every call shares one termination. After the termination sequence returns,
+	* confirmed or not, it waits at most `drain` for the read channels to close, then cuts them off
+	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
+	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
 	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
 	*/
 	stop() {
-		if (this.#stopping !== void 0) return this.#stopping;
-		this.#stopping = this.#kill();
-		return this.#stopping;
+		if (this.#termination !== void 0) return this.#termination;
+		this.#termination = this.#kill();
+		return this.#termination;
 	}
 	/**
-	* Stop the child, close its standard-input channel, and destroy the observation emitter.
+	* Stops the child and destroys the observation emitter after the terminal state freezes.
 	*
 	* @remarks
-	* Always resolves, including when termination was never confirmed.
+	* Always resolves, including when termination was never confirmed. Every call shares one barrier.
 	*
 	* @returns The stable barrier shared by every call
 	*/
 	destroy() {
 		if (this.#ending !== void 0) return this.#ending;
-		this.#ending = this.#teardown();
+		this.#ending = this.#end();
 		return this.#ending;
 	}
 	#iterate() {
@@ -947,8 +982,8 @@ var Process = class {
 			return;
 		}
 		const bytes = Buffer.byteLength(line) + 1;
-		const limit = this.#terminating ? this.#backlog * 2 : this.#backlog;
-		if ((!this.#requested || this.#terminating) && this.#pending + bytes > limit) {
+		const limit = this.#stopping ? this.#backlog * 2 : this.#backlog;
+		if ((!this.#requested || this.#stopping) && this.#pending + bytes > limit) {
 			this.#truncated = true;
 			return;
 		}
@@ -957,14 +992,14 @@ var Process = class {
 		this.#restrain();
 	}
 	#restrain() {
-		if (this.#paused || this.#terminating || !this.#requested) return;
+		if (this.#paused || this.#stopping || !this.#requested) return;
 		if (this.#pending < this.#backlog) return;
 		this.#paused = true;
 		this.#reader.pause();
 	}
 	#relieve() {
 		if (!this.#paused || this.#ended) return;
-		if (!this.#terminating && this.#pending > this.#backlog / 2) return;
+		if (!this.#stopping && this.#pending > this.#backlog / 2) return;
 		this.#paused = false;
 		this.#reader.resume();
 	}
@@ -979,24 +1014,40 @@ var Process = class {
 		this.#waiters.length = 0;
 	}
 	#retain(chunk) {
-		if (!Buffer.isBuffer(chunk) || this.#closed) return;
+		if (!Buffer.isBuffer(chunk) || this.#settled) return;
 		this.#tail = trimTail(Buffer.concat([this.#tail, chunk]), this.#evidence);
 		const text = this.#decoder.write(chunk);
 		if (text.length > 0) this.#emitter.emit("stderr", text);
 	}
-	#close(code, signal) {
-		if (this.#closed) return;
+	#close() {
+		if (this.#settled) return;
+		this.#settle(true);
+	}
+	#expire() {
+		if (this.#settled) return;
+		this.#wait();
+	}
+	#wait() {
+		this.#waiting ??= waitForClose(this.#child, this.#drain).then(() => {
+			if (!this.#settled) this.#settle(false);
+		});
+		return this.#waiting;
+	}
+	#settle(drained) {
 		const suffix = this.#decoder.end();
 		if (suffix.length > 0) this.#emitter.emit("stderr", suffix);
-		this.#closed = true;
+		this.#settled = true;
 		this.#removeAbortListener();
 		this.#reader.close();
 		const exit = Object.freeze({
-			code,
-			signal
+			code: this.code,
+			signal: this.signal,
+			drained
 		});
 		this.#exit.resolve(exit);
 		this.#emitter.emit("exit", exit);
+		this.#child.stdout.destroy();
+		this.#child.stderr.destroy();
 	}
 	#terminate() {
 		this.stop();
@@ -1033,7 +1084,7 @@ var Process = class {
 		this.#failInputCallback(cause);
 	}
 	#failInputCallback(cause) {
-		if (this.#failure !== void 0 || this.#terminating) return;
+		if (this.#failure !== void 0 || this.#stopping) return;
 		this.#failure = cause;
 		this.#settleWrites();
 		this.#emitter.emit("error", new ProcessError("The standard-input channel failed", {
@@ -1051,16 +1102,17 @@ var Process = class {
 		}
 	}
 	async #kill() {
-		this.#terminating = true;
+		this.#stopping = true;
 		this.#capBacklog();
 		this.#relieve();
 		const confirmed = await stopChild(this.#child, this.#grace, PROCESS_CONFIRMATION);
 		this.#settleWrites();
 		this.#child.stdin.destroy();
+		if (!this.#settled) await this.#wait();
+		if (!this.#settled) this.#settle(false);
 		return confirmed;
 	}
-	async #teardown() {
-		this.#removeAbortListener();
+	async #end() {
 		await this.stop();
 		this.#emitter.destroy();
 	}
@@ -1079,9 +1131,9 @@ var Process = class {
 * the child registered. `launch` throws a {@link createDuplicateError} when the id is already live
 * and a {@link createProtocolError} after `destroy` has begun, including when the caller's own option
 * getter begins that teardown mid-construction — a spawn fault surfaces through the returned child's
-* `exit`, never from `launch`. `destroy` awaits every child's own teardown, which destroys each
-* child's observation emitter and leaves every subscription on it silently inert, then destroys the
-* registry emitter last.
+* `exit`, never from `launch`. `destroy` awaits every child's own teardown, including the teardown
+* of a child a lost race refused, which destroys each child's observation emitter and leaves every
+* subscription on it silently inert, then destroys the registry emitter last.
 *
 * @example
 * ```ts
@@ -1100,6 +1152,7 @@ var ProcessManager = class {
 	#emitter;
 	#children = /* @__PURE__ */ new Map();
 	#ids = /* @__PURE__ */ new Set();
+	#orphans = /* @__PURE__ */ new Set();
 	#destroying = false;
 	#ending;
 	/**
@@ -1146,11 +1199,11 @@ var ProcessManager = class {
 	* @remarks
 	* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
 	* nothing has started and a throw from one strands no process. A getter that begins `destroy`
-	* without throwing is the one remaining race, and it leaves a bounded residual: the child is
-	* already spawned, so the launch is refused with a {@link createProtocolError} and that child is
-	* torn down asynchronously, bounded by `grace` plus the confirmation window. The `protocol`
-	* refusal throws synchronously before the `destroy` barrier settles. The barrier does not cover
-	* that child's asynchronous teardown.
+	* without throwing is the one remaining race: the child is already spawned, so the launch is
+	* refused with a {@link createProtocolError} and that child is destroyed rather than adopted, its
+	* teardown bounded by `grace` plus the confirmation window. The `protocol` refusal throws
+	* synchronously, and the `destroy` barrier covers that teardown, so the refused child reaches its
+	* terminal moment before the barrier resolves.
 	*
 	* @param id - The registry key, unique among live children
 	* @param options - The child construction options
@@ -1164,6 +1217,7 @@ var ProcessManager = class {
 		const child = this.#construct(id, options);
 		if (this.#destroying) {
 			this.#ids.delete(id);
+			this.#orphans.add(child);
 			child.destroy();
 			throw createProtocolError(id);
 		}
@@ -1220,6 +1274,11 @@ var ProcessManager = class {
 	}
 	async #teardown() {
 		await Promise.allSettled([...this.#children.values()].map((child) => child.destroy()));
+		while (this.#orphans.size > 0) {
+			const orphans = [...this.#orphans];
+			this.#orphans.clear();
+			await Promise.allSettled(orphans.map((child) => child.destroy()));
+		}
 		this.#children.clear();
 		this.#ids.clear();
 		this.#emitter.destroy();
@@ -1411,6 +1470,7 @@ async function execute(command, options) {
 		}));
 	}, { once: true });
 	terminate.signal.addEventListener("abort", () => {
+		if (finish.signal.aborted) return;
 		clearTimeout(timeoutTimer);
 		cleanup.abort();
 		stopChild(child, grace, PROCESS_CONFIRMATION).then(() => {
@@ -1600,6 +1660,6 @@ function detach(command, options) {
 	child.unref();
 }
 //#endregion
-export { Process, ProcessManager, Retention, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, createProcess, createProcessManager, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForExit };
+export { Process, ProcessManager, Retention, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, createProcess, createProcessManager, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
 
 //# sourceMappingURL=index.js.map