@orkestrel/worker 0.0.3 → 0.0.5

package/dist/src/server/index.cjs

@@ -1,9 +1,267 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let node_worker_threads = require("node:worker_threads");
 let _orkestrel_contract = require("@orkestrel/contract");
-let _src_core = require("../core/index.cjs");
+let node_worker_threads = require("node:worker_threads");
 let _orkestrel_database_server = require("@orkestrel/database/server");
 let _orkestrel_queue = require("@orkestrel/queue");
+let _src_core = require("../core/index.cjs");
+//#region src/server/Thread.ts
+/**
+* Internal mutable implementation of the readonly {@link NodeThread} observation contract.
+*
+* @remarks
+* Liveness and the first terminal error live behind runtime-private fields. Thread `error`,
+* `messageerror`, and `exit` all latch death, so pool validation cannot reuse a thread whose
+* inbound message could not be deserialized.
+*/
+var Thread = class {
+	#worker;
+	#promise;
+	#resolve;
+	#reject;
+	#recordHandler;
+	#recordExitHandler;
+	#onlineHandler;
+	#spawnErrorHandler;
+	#spawnExitHandler;
+	#alive = true;
+	#death;
+	constructor(script, workerData) {
+		this.#worker = new node_worker_threads.Worker(script, { ...workerData !== void 0 ? { workerData } : {} });
+		const readiness = Promise.withResolvers();
+		this.#promise = readiness.promise;
+		this.#resolve = readiness.resolve;
+		this.#reject = readiness.reject;
+		this.#recordHandler = this.#record.bind(this);
+		this.#recordExitHandler = this.#recordExit.bind(this);
+		this.#onlineHandler = this.#online.bind(this);
+		this.#spawnErrorHandler = this.#spawnError.bind(this);
+		this.#spawnExitHandler = this.#spawnExit.bind(this);
+		this.#worker.on("error", this.#recordHandler);
+		this.#worker.on("messageerror", this.#recordHandler);
+		this.#worker.on("exit", this.#recordExitHandler);
+		this.#worker.once("online", this.#onlineHandler);
+		this.#worker.once("error", this.#spawnErrorHandler);
+		this.#worker.once("exit", this.#spawnExitHandler);
+	}
+	get worker() {
+		return this.#worker;
+	}
+	get alive() {
+		return this.#alive;
+	}
+	get death() {
+		return this.#death;
+	}
+	get promise() {
+		return this.#promise;
+	}
+	evict() {
+		this.#alive = false;
+	}
+	#record(error) {
+		this.#alive = false;
+		if (this.#death === void 0) this.#death = error;
+	}
+	#recordExit(code) {
+		this.#alive = false;
+		if (this.#death === void 0) this.#death = /* @__PURE__ */ new Error(`worker thread exited (code ${String(code)})`);
+	}
+	#online() {
+		this.#worker.off("error", this.#spawnErrorHandler);
+		this.#worker.off("exit", this.#spawnExitHandler);
+		this.#resolve(this);
+	}
+	#spawnError(error) {
+		this.#worker.off("online", this.#onlineHandler);
+		this.#worker.off("exit", this.#spawnExitHandler);
+		this.#reject(error);
+	}
+	#spawnExit(code) {
+		this.#worker.off("online", this.#onlineHandler);
+		this.#worker.off("error", this.#spawnErrorHandler);
+		this.#reject(/* @__PURE__ */ new Error(`worker thread exited before coming online (code ${String(code)})`));
+	}
+};
+//#endregion
+//#region src/server/validators.ts
+/**
+* Narrow an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
+*
+* @remarks
+* A total predicate: a record whose `id` matches and whose `ok` discriminant is well-formed.
+* Anything else is rejected so a dispatch listener can ignore foreign or malformed messages.
+*
+* @param value - The inbound message to narrow
+* @param id - The job id a matching reply must carry
+* @returns `true` when the value is this job's well-formed reply
+*/
+function isReply(value, id) {
+	const outcome = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		if (value.id !== id) return false;
+		if (value.ok === true) return "value" in value;
+		return value.ok === false && typeof value.error === "string";
+	});
+	return outcome.success && outcome.value;
+}
+//#endregion
+//#region src/server/Dispatch.ts
+/**
+* Internal lifecycle entity for one dispatched worker-thread job.
+*
+* @remarks
+* Owns stable `message` / `messageerror` / death listener identities, settlement, result-guard
+* containment, and abort eviction for one dispatch. Deserialization failure, a matching-id
+* malformed reply, and abort each evict and terminate the thread before rejecting, with
+* termination failure preserved. Non-record, id-less, hostile-id, and foreign-id chatter is ignored.
+*/
+var Dispatch = class {
+	#thread;
+	#worker;
+	#input;
+	#execution;
+	#result;
+	#id = crypto.randomUUID();
+	#promise;
+	#fulfill;
+	#reject;
+	#messageHandler;
+	#messageErrorHandler;
+	#errorHandler;
+	#exitHandler;
+	#abortHandler;
+	#settled = false;
+	constructor(thread, input, execution, result) {
+		this.#thread = thread;
+		this.#worker = thread.worker;
+		this.#input = input;
+		this.#execution = execution;
+		this.#result = result;
+		const settlement = Promise.withResolvers();
+		this.#promise = settlement.promise;
+		this.#fulfill = settlement.resolve;
+		this.#reject = settlement.reject;
+		this.#messageHandler = this.#message.bind(this);
+		this.#messageErrorHandler = this.#messageError.bind(this);
+		this.#errorHandler = this.#error.bind(this);
+		this.#exitHandler = this.#exit.bind(this);
+		this.#abortHandler = this.#abort.bind(this);
+		this.#start();
+	}
+	get promise() {
+		return this.#promise;
+	}
+	#start() {
+		if (this.#thread.death !== void 0 || !this.#thread.alive) {
+			this.#fail(this.#thread.death ?? /* @__PURE__ */ new Error("worker thread is dead"));
+			return;
+		}
+		this.#worker.on("message", this.#messageHandler);
+		this.#worker.on("messageerror", this.#messageErrorHandler);
+		this.#worker.on("error", this.#errorHandler);
+		this.#worker.on("exit", this.#exitHandler);
+		if (this.#execution.signal.aborted) {
+			this.#abort();
+			return;
+		}
+		this.#execution.signal.addEventListener("abort", this.#abortHandler, { once: true });
+		try {
+			this.#worker.postMessage({
+				id: this.#id,
+				command: "run",
+				input: this.#input
+			});
+		} catch (error) {
+			this.#fail(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	#message(value) {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return;
+		const id = (0, _orkestrel_contract.attempt)(() => value.id);
+		if (!id.success || id.value !== this.#id) return;
+		if (!isReply(value, this.#id)) {
+			this.#terminate(/* @__PURE__ */ new Error("worker reply was malformed"));
+			return;
+		}
+		if (value.ok) {
+			const reply = value.value;
+			try {
+				if (this.#result(reply)) this.#succeed(reply);
+				else this.#fail(/* @__PURE__ */ new Error("reply did not satisfy result guard"));
+			} catch (error) {
+				this.#fail(error);
+			}
+			return;
+		}
+		this.#fail(new Error(value.error));
+	}
+	#messageError(error) {
+		this.#terminate(error);
+	}
+	#error(error) {
+		this.#fail(error);
+	}
+	#exit() {
+		this.#fail(this.#thread.death ?? /* @__PURE__ */ new Error("worker thread exited"));
+	}
+	#abort() {
+		const notification = [];
+		try {
+			this.#worker.postMessage({
+				id: this.#id,
+				command: "abort"
+			});
+		} catch (cause) {
+			notification.push(cause);
+		}
+		this.#terminate(this.#execution.signal.reason, notification);
+	}
+	#terminate(error, notification = []) {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#detach();
+		if (this.#thread instanceof Thread) this.#thread.evict();
+		let termination;
+		try {
+			termination = this.#worker.terminate();
+		} catch (cause) {
+			this.#reject(new AggregateError([
+				error,
+				...notification,
+				cause
+			], "worker termination failed"));
+			return;
+		}
+		termination.then(() => {
+			if (notification.length === 0) this.#reject(error);
+			else this.#reject(new AggregateError([error, ...notification], "worker abort notification failed"));
+		}, (cause) => this.#reject(new AggregateError([
+			error,
+			...notification,
+			cause
+		], "worker termination failed")));
+	}
+	#succeed(value) {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#detach();
+		this.#fulfill(value);
+	}
+	#fail(error) {
+		if (this.#settled) return;
+		this.#settled = true;
+		this.#detach();
+		this.#reject(error);
+	}
+	#detach() {
+		this.#worker.off("message", this.#messageHandler);
+		this.#worker.off("messageerror", this.#messageErrorHandler);
+		this.#worker.off("error", this.#errorHandler);
+		this.#worker.off("exit", this.#exitHandler);
+		this.#execution.signal.removeEventListener("abort", this.#abortHandler);
+	}
+};
+//#endregion
 //#region src/server/helpers.ts
 /**
 * Spawn one worker thread and resolve a live {@link NodeThread} once it comes online.
@@ -16,71 +274,18 @@ let _orkestrel_queue = require("@orkestrel/queue");
 * listeners that flip `alive` to `false` AND latch the first terminal event on
 * {@link NodeThread.death}: a crash is observable to an in-flight {@link dispatch} (via
 * its own listeners), to the pool's `validate` (via `alive`), and — crucially — to a
-* dispatch that attaches AFTER the death (via the latch). The latch closes a real race:
-* under event-loop pressure a dead thread's `online` + `error` + `exit` are delivered in
-* ONE synchronous exit-drain batch, so every death event fires before the microtask chain
-* resolving this spawn can hand the thread to `dispatch` — without the latch that job
-* would await events that already fired, forever. The pool's `create` hook calls this.
+* dispatch that attaches AFTER the death (via the latch). A `messageerror` is terminal too,
+* so a thread whose inbound payload could not be deserialized is never reused. The latch
+* closes a real race: a thread can become terminal before the readiness promise continuation
+* hands it to `dispatch`, leaving no future death event for that dispatch to observe. Without
+* the latch, that job would wait forever. The pool's `create` hook calls this.
 *
 * @param script - The worker module each thread runs (must call `serveWorker`)
 * @param workerData - Opaque, structured-cloneable data handed to the thread at spawn
 * @returns A promise resolving the online {@link NodeThread}
 */
 function spawnThread(script, workerData) {
-	const worker = new node_worker_threads.Worker(script, { workerData });
-	const thread = {
-		worker,
-		alive: true,
-		death: void 0
-	};
-	worker.on("error", (error) => {
-		thread.alive = false;
-		if (thread.death === void 0) thread.death = error;
-	});
-	worker.on("exit", (code) => {
-		thread.alive = false;
-		if (thread.death === void 0) thread.death = /* @__PURE__ */ new Error(`worker thread exited (code ${code})`);
-	});
-	return new Promise((resolve, reject) => {
-		const onOnline = () => {
-			worker.off("error", onError);
-			worker.off("exit", onExit);
-			resolve(thread);
-		};
-		const onError = (error) => {
-			worker.off("online", onOnline);
-			worker.off("exit", onExit);
-			reject(error);
-		};
-		const onExit = (code) => {
-			worker.off("online", onOnline);
-			worker.off("error", onError);
-			reject(/* @__PURE__ */ new Error(`worker thread exited before coming online (code ${code})`));
-		};
-		worker.once("online", onOnline);
-		worker.once("error", onError);
-		worker.once("exit", onExit);
-	});
-}
-/**
-* Narrow an inbound `message` to a {@link Reply} for a given job `id` — no assertion.
-*
-* @remarks
-* A total {@link Guard}-style predicate (never throws): a record whose `id` matches and
-* whose `ok` discriminant is well-formed (a `true` carries any `value`; a `false` carries a
-* string `error`). Anything else — another job's reply, a malformed payload — is `false`, so
-* a {@link dispatch} listener ignores it (a thread that chatters on the channel can't corrupt
-* a job).
-*
-* @param value - The inbound message to narrow
-* @param id - The job id a matching reply must carry
-* @returns `true` (narrowing `value` to {@link Reply}) when it is this job's well-formed reply
-*/
-function isReply(value, id) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	if (value.id !== id) return false;
-	if (value.ok === true) return true;
-	return value.ok === false && typeof value.error === "string";
+	return new Thread(script, workerData).promise;
 }
 /**
 * Dispatch one job to a leased {@link NodeThread} and await its narrowed reply.
@@ -90,15 +295,15 @@ function isReply(value, id) {
 * that id: a success `value` is narrowed through `result` (a value that fails the guard
 * rejects — the zero-`as` type bridge), a failure rejects with the thread's error string.
 * A thread that ALREADY died rejects synchronously at entry from the latched
-* {@link NodeThread.death} — its death events fired before this dispatch existed (under
-* load they arrive in one batched exit drain) and will never fire again, so waiting on
-* the listeners below would dangle forever; the latch makes the death total across every
-* event ordering. If the thread `error`s / `exit`s mid-flight it is marked dead and the
-* job rejects. On `execution.signal` abort it posts an `abort` envelope (cooperative) AND
-* evicts the thread — `alive = false` + `terminate()` — because CPU-bound work cannot
-* honour the signal; the freed pool slot then gets a fresh thread. Every listener (the
-* thread's `message` / `error` / `exit` and the signal's `abort`) is removed on settle,
-* and a `settled` guard prevents a double-settle.
+* {@link NodeThread.death} — its death events fired before this dispatch existed and will
+* never fire again, so waiting on the listeners below would dangle forever; the latch makes
+* death total across every event ordering. If the thread `error`s / `exit`s mid-flight it is
+* marked dead and the
+* job rejects. An inbound `messageerror` also evicts and terminates the thread before
+* rejection. On `execution.signal` abort it contains the cooperative `abort` post,
+* evicts the thread, and observes `terminate()` settlement because CPU-bound work cannot
+* honour the signal; the freed pool slot then gets a fresh thread. Every per-job listener
+* (`message` / `messageerror` / `error` / `exit` / `abort`) is removed on settle.
 *
 * @typeParam TResult - The reply type the `result` guard narrows to
 * @param thread - The leased thread to run the job on
@@ -108,73 +313,7 @@ function isReply(value, id) {
 * @returns A promise resolving the narrowed `TResult`, or rejecting on error / abort
 */
 function dispatch(thread, input, execution, result) {
-	const id = crypto.randomUUID();
-	const worker = thread.worker;
-	return new Promise((resolve, reject) => {
-		if (thread.death !== void 0 || !thread.alive) {
-			reject(thread.death ?? /* @__PURE__ */ new Error("worker thread is dead"));
-			return;
-		}
-		let settled = false;
-		let detach = () => {};
-		const settle = (action) => {
-			if (settled) return;
-			settled = true;
-			detach();
-			action();
-		};
-		const onMessage = (value) => {
-			if (!isReply(value, id)) return;
-			if (value.ok) {
-				const reply = value.value;
-				if (result(reply)) settle(() => resolve(reply));
-				else settle(() => reject(/* @__PURE__ */ new Error("reply did not satisfy result guard")));
-				return;
-			}
-			const message = value.error;
-			settle(() => reject(new Error(message)));
-		};
-		const onError = (error) => {
-			thread.alive = false;
-			settle(() => reject(error));
-		};
-		const onExit = () => {
-			thread.alive = false;
-			settle(() => reject(/* @__PURE__ */ new Error("worker thread exited")));
-		};
-		const onAbort = () => {
-			worker.postMessage({
-				id,
-				command: "abort"
-			});
-			thread.alive = false;
-			worker.terminate();
-			settle(() => reject(/* @__PURE__ */ new Error("job aborted")));
-		};
-		detach = () => {
-			worker.off("message", onMessage);
-			worker.off("error", onError);
-			worker.off("exit", onExit);
-			execution.signal.removeEventListener("abort", onAbort);
-		};
-		worker.on("message", onMessage);
-		worker.on("error", onError);
-		worker.on("exit", onExit);
-		if (execution.signal.aborted) {
-			onAbort();
-			return;
-		}
-		execution.signal.addEventListener("abort", onAbort, { once: true });
-		try {
-			worker.postMessage({
-				id,
-				command: "run",
-				input
-			});
-		} catch (error) {
-			settle(() => reject(error instanceof Error ? error : new Error(String(error))));
-		}
-	});
+	return new Dispatch(thread, input, execution, result).promise;
 }
 //#endregion
 //#region src/server/serve.ts
@@ -195,7 +334,10 @@ function isAbort(value) {
 * run/abort protocol: a `run` message narrows its `input` through `options.input` (an
 * invalid payload replies with an error envelope, never running the handler), then runs
 * `options.handler(input, { signal })` and replies `{ id, ok: true, value }` on success or
-* `{ id, ok: false, error }` on throw. Each in-flight job has its own `AbortController`,
+* `{ id, ok: false, error }` on throw. Input-guard throws use the same failure envelope. If a
+* success value cannot be cloned, the post is retried as a clone-safe failure; if that post also
+* fails, the parent port closes so the main side observes thread exit instead of waiting forever.
+* Each in-flight job has its own `AbortController`,
 * so an `abort` message for that id fires the handler's `signal` (cooperative — the main
 * side ALSO terminates the thread, so a handler that ignores its signal is still stopped).
 * Every inbound message is narrowed with the inlined guards — no `as`. On the main thread
@@ -208,7 +350,7 @@ function isAbort(value) {
 * @example
 * ```ts
 * // double.ts — a worker script
-* import { serveWorker } from '@src/server'
+* import { serveWorker } from '@orkestrel/worker/server'
 *
 * serveWorker<number, number>({
 * 	input: (value): value is number => typeof value === 'number',
@@ -219,6 +361,8 @@ function isAbort(value) {
 function serveWorker(options) {
 	const port = node_worker_threads.parentPort;
 	if (port === null) return;
+	const input = options.input;
+	const handler = options.handler;
 	const controllers = /* @__PURE__ */ new Map();
 	port.on("message", (raw) => {
 		if (isAbort(raw)) {
@@ -227,35 +371,99 @@ function serveWorker(options) {
 		}
 		if (!isRun(raw)) return;
 		const id = raw.id;
-		if (!options.input(raw.input)) {
-			port.postMessage({
-				id,
-				ok: false,
-				error: "input did not satisfy input guard"
-			});
-			return;
-		}
-		const input = raw.input;
 		const controller = new AbortController();
 		controllers.set(id, controller);
-		Promise.resolve().then(() => options.handler(input, { signal: controller.signal })).then((value) => {
+		Promise.resolve().then(() => {
+			if (!input(raw.input)) throw new Error("input did not satisfy input guard");
+			const value = raw.input;
+			return handler(value, { signal: controller.signal });
+		}).then((value) => {
 			controllers.delete(id);
 			port.postMessage({
 				id,
 				ok: true,
 				value
 			});
-		}, (error) => {
+		}).catch((error) => {
 			controllers.delete(id);
-			port.postMessage({
-				id,
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			});
+			let message = "worker operation failed";
+			try {
+				message = error instanceof Error ? error.message : String(error);
+			} catch {}
+			try {
+				port.postMessage({
+					id,
+					ok: false,
+					error: message
+				});
+			} catch {
+				try {
+					port.close();
+				} catch {}
+			}
 		});
 	});
 }
 //#endregion
+//#region src/server/NodeWorker.ts
+/**
+* Internal composition entity backing {@link createNodeWorker}.
+*
+* @remarks
+* Supplies bound Pool and Queue operations without nested function assignments. The resulting
+* public entity remains the plain core {@link WorkerInterface}.
+*/
+var NodeWorker = class {
+	#script;
+	#input;
+	#result;
+	#workerData;
+	#concurrency;
+	#retries;
+	#timeout;
+	#store;
+	constructor(options) {
+		this.#script = options.script;
+		this.#input = options.input;
+		this.#result = options.result;
+		this.#workerData = options.workerData;
+		this.#concurrency = options.concurrency;
+		this.#retries = options.retries;
+		this.#timeout = options.timeout;
+		this.#store = options.store;
+	}
+	build() {
+		return (0, _src_core.createWorker)({
+			pool: {
+				create: this.#create.bind(this),
+				destroy: this.#destroy.bind(this),
+				validate: this.#validate.bind(this),
+				...this.#concurrency !== void 0 ? { max: this.#concurrency } : {}
+			},
+			handler: this.#handle.bind(this),
+			...this.#concurrency !== void 0 ? { concurrency: this.#concurrency } : {},
+			...this.#retries !== void 0 ? { retries: this.#retries } : {},
+			...this.#timeout !== void 0 ? { timeout: this.#timeout } : {},
+			...this.#store !== void 0 ? { store: this.#store } : {}
+		});
+	}
+	#create() {
+		return spawnThread(this.#script, this.#workerData);
+	}
+	async #destroy(thread) {
+		await thread.worker.terminate();
+	}
+	#validate(thread) {
+		return thread.alive && thread.worker.threadId > 0;
+	}
+	#handle(input, thread, execution) {
+		const outcome = (0, _orkestrel_contract.attempt)(() => this.#input(input));
+		if (!outcome.success) return Promise.reject(outcome.error);
+		if (!outcome.value) return Promise.reject(/* @__PURE__ */ new Error("input did not satisfy input guard"));
+		return dispatch(thread, input, execution, this.#result);
+	}
+};
+//#endregion
 //#region src/server/factories.ts
 /**
 * Create a persistent JSON-file {@link QueueStoreInterface} — the core
@@ -277,8 +485,8 @@ function serveWorker(options) {
 *
 * @example
 * ```ts
-* import { stringShape } from '@src/core'
-* import { createJSONQueueStore } from '@src/server'
+* import { stringShape } from '@orkestrel/contract'
+* import { createJSONQueueStore } from '@orkestrel/worker/server'
 *
 * const store = createJSONQueueStore('data/queue.json', stringShape())
 * await store.save({ id: 'job-1', input: 'https://example.com', attempts: 0 })
@@ -318,7 +526,7 @@ function createJSONQueueStore(path, input) {
 *
 * @example
 * ```ts
-* import { createNodeWorker } from '@src/server'
+* import { createNodeWorker } from '@orkestrel/worker/server'
 *
 * const worker = createNodeWorker({
 * 	script: new URL('./double.js', import.meta.url),
@@ -328,26 +536,11 @@ function createJSONQueueStore(path, input) {
 * })
 *
 * const doubled = await worker.enqueue(21) // 42, computed on a worker thread
-* worker.destroy() // terminates every thread
+* await worker.destroy() // terminates every thread
 * ```
 */
 function createNodeWorker(options) {
-	return (0, _src_core.createWorker)({
-		pool: {
-			create: () => spawnThread(options.script, options.workerData),
-			destroy: (thread) => thread.worker.terminate().then(() => {}),
-			validate: (thread) => thread.alive && thread.worker.threadId > 0,
-			max: options.concurrency
-		},
-		handler: (input, thread, execution) => {
-			if (!options.input(input)) return Promise.reject(/* @__PURE__ */ new Error("input did not satisfy input guard"));
-			return dispatch(thread, input, execution, options.result);
-		},
-		concurrency: options.concurrency,
-		retries: options.retries,
-		timeout: options.timeout,
-		store: options.store
-	});
+	return new NodeWorker(options).build();
 }
 //#endregion
 exports.createJSONQueueStore = createJSONQueueStore;