@camstack/system 1.2.289 → 1.2.291

package/dist/{manifest-system-deps-B8ZUclN4.js → manifest-system-deps-DTgkfBJy.js}

@@ -20,6 +20,7 @@ let node_perf_hooks = require("node:perf_hooks");
 let node_vm = require("node:vm");
 node_vm = require_chunk.__toESM(node_vm);
 let _camstack_types_addon = require("@camstack/types/addon");
+let node_events = require("node:events");
 let node_net = require("node:net");
 let _trpc_client = require("@trpc/client");
 //#region src/kernel/event-plane-report.ts
@@ -2613,6 +2614,577 @@ function createAddonDataPlaneFacility(args) {
 	};
 }
 //#endregion
+//#region src/kernel/moleculer/addon-peer-bytes-facility.ts
+/**
+* Kernel side of the addon→addon **byte transport** (`ctx.peerBytes`, D613).
+*
+* See {@link AddonPeerBytes} for what this exists for and what it deliberately
+* does not do. This file is the mechanism:
+*
+* - **One lazy loopback listener per addon process.** Bound on the first
+*   `offer()`, never before, so an addon that never offers pays no port.
+* - **One token per offer.** 24 random bytes, base64url, ONE `GET`. A replay
+*   is `offer-used` (410) for as long as the original ticket would have lived,
+*   so a second take is told what happened rather than "no such thing".
+*   `HEAD` answers the headers and consumes nothing.
+* - **Outstanding offers are bounded and swept on every mint**, which is also
+*   what makes a per-frame misuse of this facility refuse by name instead of
+*   working slowly.
+* - **Every write honours `write()`'s return and awaits `drain`** (D447), and
+*   a peer that has taken nothing for {@link PEER_BYTES_STALL_MS} is cut. Every
+*   exit — offered, taken, sent, cut, stalled, refused, disposed — is one log
+*   line, carrying `tags: { deviceId }` when the offer named a device.
+* - **The consumer's response is handed over PAUSED**, which is the whole
+*   reason `open()` lives in the framework rather than in each consumer: see
+*   {@link PeerBytesBody}.
+*/
+/** The HOST a node id belongs to. `hub` → `hub`; `hub/runner-3` → `hub`. */
+function hostNodeIdOf(nodeId) {
+	const slash = nodeId.indexOf("/");
+	return slash === -1 ? nodeId : nodeId.slice(0, slash);
+}
+/** A body chunk, without a cast. A readable in binary mode yields Buffers; in
+*  string mode, strings. Anything else is a broken stream and says so. */
+function asBuffer(chunk) {
+	if (Buffer.isBuffer(chunk)) return chunk;
+	if (typeof chunk === "string") return Buffer.from(chunk);
+	throw new Error("peer-bytes: a body chunk was neither a Buffer nor a string");
+}
+function tokenOf(req) {
+	const raw = req.url ?? "/";
+	const query = raw.indexOf("?");
+	return (query === -1 ? raw : raw.slice(0, query)).replace(/^\/+/, "");
+}
+/**
+* Write `bytes` to `res` in bounded chunks, honouring backpressure.
+*
+* D447, the consuming half stated from the producing side: a raw HTTP stream
+* writes no chunk the socket has not taken. `write()` returning false means the
+* kernel buffer is full and everything further is heap in THIS process — so we
+* wait for `drain`, and a peer that never drains within `stallMs` is cut rather
+* than held. Returns how many bytes reached the socket and why it stopped.
+*/
+async function writeBufferWithBackpressure(res, bytes, stallMs) {
+	const waitForDrain = () => new Promise((resolve) => {
+		const settle = (outcome) => {
+			clearTimeout(timer);
+			res.off("drain", onDrain);
+			res.off("close", onClose);
+			resolve(outcome);
+		};
+		const onDrain = () => {
+			settle("drained");
+		};
+		const onClose = () => {
+			settle("closed");
+		};
+		const timer = setTimeout(() => {
+			settle("stalled");
+		}, stallMs);
+		timer.unref();
+		res.on("drain", onDrain);
+		res.on("close", onClose);
+	});
+	let sent = 0;
+	while (sent < bytes.byteLength) {
+		if (res.destroyed || res.writableEnded) return {
+			sent,
+			outcome: "peer-gone"
+		};
+		const end = Math.min(sent + _camstack_types_addon.PEER_BYTES_CHUNK_BYTES, bytes.byteLength);
+		const took = res.write(bytes.subarray(sent, end));
+		sent = end;
+		if (took) continue;
+		const waited = await waitForDrain();
+		if (waited === "drained") continue;
+		return {
+			sent,
+			outcome: waited === "closed" ? "peer-gone" : "stalled"
+		};
+	}
+	return {
+		sent,
+		outcome: "sent"
+	};
+}
+function createAddonPeerBytesFacility(args) {
+	const now = args.now ?? (() => Date.now());
+	const ttlMs = args.ttlMs ?? _camstack_types_addon.PEER_BYTES_TICKET_TTL_MS;
+	const maxOutstanding = args.maxOutstanding ?? _camstack_types_addon.PEER_BYTES_MAX_OUTSTANDING;
+	const stallMs = args.stallMs ?? _camstack_types_addon.PEER_BYTES_STALL_MS;
+	const host = args.host ?? "127.0.0.1";
+	const hostNodeId = hostNodeIdOf(args.nodeId);
+	const offers = /* @__PURE__ */ new Map();
+	/** Tokens already taken, kept for their TTL so a replay is `offer-used`. */
+	const taken = /* @__PURE__ */ new Map();
+	let server = null;
+	let baseUrl = null;
+	let listening = null;
+	const sweep = () => {
+		const at = now();
+		for (const [token, offer] of offers) if (offer.expiresAtMs <= at) {
+			offers.delete(token);
+			args.logger.info("peer-bytes: an offer expired untaken", {
+				...offer.deviceId !== void 0 ? { tags: { deviceId: offer.deviceId } } : {},
+				meta: {
+					label: offer.label,
+					outstanding: offers.size
+				}
+			});
+		}
+		for (const [token, expiresAtMs] of taken) if (expiresAtMs <= at) taken.delete(token);
+	};
+	const route = (req, res) => {
+		const token = tokenOf(req);
+		const offer = offers.get(token);
+		if (offer === void 0) {
+			const status = taken.has(token) ? 410 : 404;
+			res.writeHead(status, { "x-camstack-peer-bytes": status === 410 ? "offer-used" : "no-offer" });
+			res.end();
+			return;
+		}
+		if (offer.expiresAtMs <= now()) {
+			offers.delete(token);
+			res.writeHead(410, { "x-camstack-peer-bytes": "offer-expired" }).end();
+			return;
+		}
+		if (req.method === "GET") {
+			offers.delete(token);
+			taken.set(token, offer.expiresAtMs);
+			args.logger.info("peer-bytes: an offer was taken", {
+				...offer.deviceId !== void 0 ? { tags: { deviceId: offer.deviceId } } : {},
+				meta: {
+					label: offer.label,
+					outstanding: offers.size
+				}
+			});
+		}
+		Promise.resolve(offer.handler(req, res)).catch((err) => {
+			args.logger.warn("peer-bytes: an offer handler threw", {
+				...offer.deviceId !== void 0 ? { tags: { deviceId: offer.deviceId } } : {},
+				meta: {
+					label: offer.label,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			if (!res.headersSent) res.writeHead(500);
+			res.end();
+		});
+	};
+	const listen = () => {
+		if (listening !== null) return listening;
+		listening = new Promise((resolve, reject) => {
+			const created = (0, node_http.createServer)((req, res) => {
+				route(req, res);
+			});
+			created.on("error", (err) => {
+				listening = null;
+				reject(err);
+			});
+			created.listen(0, host, () => {
+				const address = created.address();
+				if (address === null || typeof address === "string") {
+					created.close();
+					listening = null;
+					reject(/* @__PURE__ */ new Error("the peer-bytes listener bound no TCP port"));
+					return;
+				}
+				server = created;
+				baseUrl = `http://${host}:${address.port}`;
+				args.logger.info("peer-bytes: listener bound", { meta: {
+					addonId: args.addonId,
+					host,
+					port: address.port,
+					hostNodeId,
+					ttlMs
+				} });
+				resolve(baseUrl);
+			});
+		});
+		return listening;
+	};
+	const mint = async (options) => {
+		sweep();
+		const deviceTags = options.deviceId !== void 0 ? { tags: { deviceId: options.deviceId } } : {};
+		if (offers.size >= maxOutstanding) {
+			args.logger.warn("peer-bytes: offer refused — too many outstanding", {
+				...deviceTags,
+				meta: {
+					label: options.label,
+					outstanding: offers.size,
+					maxOutstanding
+				}
+			});
+			return {
+				kind: "refused",
+				code: "offer-exhausted",
+				detail: `${String(offers.size)} offers outstanding against a bound of ${String(maxOutstanding)}`
+			};
+		}
+		let base;
+		try {
+			base = baseUrl ?? await listen();
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			args.logger.warn("peer-bytes: offer refused — no listener", {
+				...deviceTags,
+				meta: {
+					label: options.label,
+					error: detail
+				}
+			});
+			return {
+				kind: "refused",
+				code: "listener-failed",
+				detail
+			};
+		}
+		const token = (0, node_crypto.randomBytes)(24).toString("base64url");
+		const expiresAtMs = now() + (options.ttlMs ?? ttlMs);
+		offers.set(token, {
+			handler: options.handler,
+			label: options.label,
+			deviceId: options.deviceId,
+			expiresAtMs
+		});
+		args.logger.info("peer-bytes: offer minted", {
+			...deviceTags,
+			meta: {
+				label: options.label,
+				declaredBytes: options.declaredBytes ?? null,
+				expiresInMs: expiresAtMs - now(),
+				outstanding: offers.size
+			}
+		});
+		return {
+			kind: "ticket",
+			ticket: {
+				url: `${base}/${token}`,
+				hostNodeId,
+				expiresAtMs,
+				declaredBytes: options.declaredBytes ?? null
+			}
+		};
+	};
+	const peerBytes = {
+		hostNodeId,
+		get outstanding() {
+			sweep();
+			return offers.size;
+		},
+		offer: mint,
+		offerBuffer: async (options) => {
+			const deviceTags = options.deviceId !== void 0 ? { tags: { deviceId: options.deviceId } } : {};
+			const handler = async (req, res) => {
+				res.writeHead(200, {
+					"content-type": options.contentType,
+					"content-length": String(options.bytes.byteLength),
+					"accept-ranges": "none"
+				});
+				if (req.method === "HEAD") {
+					res.end();
+					return;
+				}
+				const startedAt = now();
+				const result = await writeBufferWithBackpressure(res, options.bytes, stallMs);
+				if (result.outcome === "sent") {
+					res.end();
+					args.logger.info("peer-bytes: body sent", {
+						...deviceTags,
+						meta: {
+							label: options.label,
+							bytes: result.sent,
+							tookMs: now() - startedAt,
+							source: "buffer"
+						}
+					});
+					return;
+				}
+				args.logger.warn("peer-bytes: body cut before it was complete", {
+					...deviceTags,
+					meta: {
+						label: options.label,
+						branch: result.outcome,
+						sent: result.sent,
+						of: options.bytes.byteLength,
+						stallMs,
+						source: "buffer"
+					}
+				});
+				res.destroy();
+			};
+			return await mint({
+				handler,
+				label: options.label,
+				declaredBytes: options.bytes.byteLength,
+				...options.deviceId !== void 0 ? { deviceId: options.deviceId } : {},
+				...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+			});
+		},
+		offerFile: async (options) => {
+			const deviceTags = options.deviceId !== void 0 ? { tags: { deviceId: options.deviceId } } : {};
+			let declaredBytes = null;
+			try {
+				declaredBytes = (await (0, node_fs_promises.stat)(options.path)).size;
+			} catch {
+				declaredBytes = null;
+			}
+			const handler = async (req, res) => {
+				const headers = {
+					"content-type": options.contentType,
+					"accept-ranges": "none"
+				};
+				if (declaredBytes !== null) headers["content-length"] = String(declaredBytes);
+				if (req.method === "HEAD") {
+					res.writeHead(200, headers).end();
+					return;
+				}
+				const startedAt = now();
+				let stream;
+				try {
+					stream = (0, node_fs.createReadStream)(options.path);
+					await (0, node_events.once)(stream, "open");
+				} catch (err) {
+					const detail = err instanceof Error ? err.message : String(err);
+					args.logger.warn("peer-bytes: the offered file could not be opened", {
+						...deviceTags,
+						meta: {
+							label: options.label,
+							error: detail
+						}
+					});
+					if (!res.headersSent) res.writeHead(503, { "x-camstack-peer-bytes": "file-unreadable" });
+					res.end();
+					return;
+				}
+				res.writeHead(200, headers);
+				let sent = 0;
+				let lastProgressAt = now();
+				stream.pipe(res);
+				stream.on("data", (chunk) => {
+					sent += typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.byteLength;
+					lastProgressAt = now();
+				});
+				const stallTimer = setInterval(() => {
+					if (now() - lastProgressAt < stallMs) return;
+					clearInterval(stallTimer);
+					args.logger.warn("peer-bytes: body cut before it was complete", {
+						...deviceTags,
+						meta: {
+							label: options.label,
+							branch: "stalled",
+							sent,
+							stallMs,
+							source: "file"
+						}
+					});
+					stream.destroy();
+					res.destroy();
+				}, Math.max(1e3, Math.floor(stallMs / 4)));
+				stallTimer.unref();
+				const ended = await Promise.race([(0, node_events.once)(stream, "end").then(() => true), (0, node_events.once)(res, "close").then(() => false)]).catch(() => false);
+				clearInterval(stallTimer);
+				if (ended) {
+					args.logger.info("peer-bytes: body sent", {
+						...deviceTags,
+						meta: {
+							label: options.label,
+							bytes: sent,
+							tookMs: now() - startedAt,
+							source: "file"
+						}
+					});
+					return;
+				}
+				stream.destroy();
+				args.logger.warn("peer-bytes: body cut before it was complete", {
+					...deviceTags,
+					meta: {
+						label: options.label,
+						branch: "peer-gone",
+						sent,
+						of: declaredBytes,
+						source: "file"
+					}
+				});
+			};
+			return await mint({
+				handler,
+				label: options.label,
+				...declaredBytes !== null ? { declaredBytes } : {},
+				...options.deviceId !== void 0 ? { deviceId: options.deviceId } : {},
+				...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+			});
+		},
+		open: async (ticket) => {
+			if (ticket.hostNodeId !== hostNodeId) {
+				args.logger.warn("peer-bytes: refusing a ticket minted on another node", { meta: {
+					mintedOn: ticket.hostNodeId,
+					here: hostNodeId
+				} });
+				return {
+					kind: "refused",
+					code: "cross-node",
+					detail: `this ticket was minted on node "${ticket.hostNodeId}" and this process runs on "${hostNodeId}" — peer-bytes is loopback only, so there is nothing to dial`
+				};
+			}
+			if (ticket.expiresAtMs <= now()) return {
+				kind: "refused",
+				code: "ticket-expired",
+				detail: `this ticket expired ${String(now() - ticket.expiresAtMs)} ms ago`
+			};
+			let url;
+			try {
+				url = new URL(ticket.url);
+			} catch {
+				return {
+					kind: "refused",
+					code: "ticket-malformed",
+					detail: `"${ticket.url}" is not a URL`
+				};
+			}
+			if (url.protocol !== "http:") return {
+				kind: "refused",
+				code: "ticket-malformed",
+				detail: `peer-bytes dials http, not "${url.protocol}"`
+			};
+			const req = (0, node_http.request)({
+				hostname: url.hostname,
+				port: url.port,
+				path: url.pathname,
+				method: "GET"
+			});
+			let response;
+			try {
+				response = await new Promise((resolve, reject) => {
+					req.once("response", resolve);
+					req.once("error", reject);
+					req.end();
+				});
+			} catch (err) {
+				const detail = err instanceof Error ? err.message : String(err);
+				req.destroy();
+				args.logger.warn("peer-bytes: the dial failed", { meta: { error: detail } });
+				return {
+					kind: "refused",
+					code: "unreachable",
+					detail
+				};
+			}
+			response.pause();
+			const status = response.statusCode ?? 0;
+			if (status < 200 || status >= 300) {
+				const reason = response.headers["x-camstack-peer-bytes"];
+				response.resume();
+				req.destroy();
+				return {
+					kind: "refused",
+					code: "producer-refused",
+					detail: typeof reason === "string" ? `the producer answered ${String(status)} (${reason})` : `the producer answered ${String(status)}`,
+					status
+				};
+			}
+			const lengthHeader = response.headers["content-length"];
+			const declaredBytes = typeof lengthHeader === "string" && /^\d+$/.test(lengthHeader) ? Number(lengthHeader) : null;
+			const contentTypeHeader = response.headers["content-type"];
+			const stream = response;
+			return {
+				kind: "body",
+				body: {
+					status,
+					contentType: typeof contentTypeHeader === "string" ? contentTypeHeader : null,
+					declaredBytes,
+					stream,
+					cancel: (reason) => {
+						args.logger.info("peer-bytes: the consumer gave up on a body", { meta: { reason } });
+						response.destroy();
+						req.destroy();
+					},
+					writeToFile: async (path, options) => {
+						await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), { recursive: true });
+						const sink = (0, node_fs.createWriteStream)(path);
+						const discard = async () => {
+							sink.destroy();
+							if (!sink.closed) await (0, node_events.once)(sink, "close").catch(() => void 0);
+							await (0, node_fs_promises.rm)(path, { force: true });
+						};
+						let written = 0;
+						let overrun = false;
+						try {
+							for await (const chunk of stream) {
+								const buf = asBuffer(chunk);
+								written += buf.byteLength;
+								if (written > options.maxBytes) {
+									overrun = true;
+									break;
+								}
+								if (!sink.write(buf)) await (0, node_events.once)(sink, "drain");
+							}
+						} catch (err) {
+							const detail = err instanceof Error ? err.message : String(err);
+							response.destroy();
+							req.destroy();
+							await discard();
+							return {
+								kind: "refused",
+								code: "transfer-failed",
+								detail,
+								bytes: written
+							};
+						}
+						if (overrun) {
+							response.destroy();
+							req.destroy();
+							await discard();
+							return {
+								kind: "refused",
+								code: "too-large",
+								detail: `the body passed ${String(options.maxBytes)} bytes and was aborted`,
+								bytes: written
+							};
+						}
+						try {
+							sink.end();
+							await (0, node_events.once)(sink, "close");
+						} catch (err) {
+							const detail = err instanceof Error ? err.message : String(err);
+							await discard();
+							return {
+								kind: "refused",
+								code: "write-failed",
+								detail,
+								bytes: written
+							};
+						}
+						return {
+							kind: "written",
+							bytes: written
+						};
+					}
+				}
+			};
+		}
+	};
+	const dispose = async () => {
+		offers.clear();
+		taken.clear();
+		const open = server;
+		server = null;
+		baseUrl = null;
+		listening = null;
+		if (open === null) return;
+		await new Promise((resolve) => {
+			open.close(() => resolve());
+			open.closeAllConnections();
+		});
+		args.logger.info("peer-bytes: listener closed", { meta: { addonId: args.addonId } });
+	};
+	return {
+		peerBytes,
+		dispose
+	};
+}
+//#endregion
 //#region src/kernel/deps/npm-command.ts
 /**
 * npm invocation resolver — makes "is npm available?" a solved problem for
@@ -11190,6 +11762,12 @@ async function buildAddonContext(runtime, declaration, dataDir, options) {
 		...options?.dataPlaneSink !== void 0 ? { sink: options.dataPlaneSink } : {}
 	});
 	workerDisposerChain.add(() => dataPlaneFacility.dispose());
+	const peerBytesFacility = createAddonPeerBytesFacility({
+		addonId,
+		logger: scopedLogger,
+		nodeId
+	});
+	workerDisposerChain.add(() => peerBytesFacility.dispose());
 	return {
 		id: addonId,
 		logger: scopedLogger,
@@ -11198,6 +11776,7 @@ async function buildAddonContext(runtime, declaration, dataDir, options) {
 		dataDir: addonDataDir,
 		nodeDataDir,
 		dataPlane: dataPlaneFacility.dataPlane,
+		peerBytes: peerBytesFacility.peerBytes,
 		api,
 		deps: new AddonDepsManager(addonDataDir, scopedLogger),
 		settings: settingsView,
@@ -12120,6 +12699,12 @@ Object.defineProperty(exports, "createAddonDataPlaneFacility", {
 		return createAddonDataPlaneFacility;
 	}
 });
+Object.defineProperty(exports, "createAddonPeerBytesFacility", {
+	enumerable: true,
+	get: function() {
+		return createAddonPeerBytesFacility;
+	}
+});
 Object.defineProperty(exports, "createAddonService", {
 	enumerable: true,
 	get: function() {
@@ -12396,6 +12981,12 @@ Object.defineProperty(exports, "heapSpaceField", {
 		return heapSpaceField;
 	}
 });
+Object.defineProperty(exports, "hostNodeIdOf", {
+	enumerable: true,
+	get: function() {
+		return hostNodeIdOf;
+	}
+});
 Object.defineProperty(exports, "hubMainRssBudget", {
 	enumerable: true,
 	get: function() {