@camstack/addon-pipeline 1.1.26 → 1.1.28

package/dist/{frame-handle-plane-Dq20KtKL.mjs → frame-handle-plane-BIoY6nRV.mjs}

@@ -1,6 +1,14 @@
-import { B as errMsg, p as RingBuffer } from "./dist-CgEP_0OL.mjs";
+import { B as errMsg, p as RingBuffer } from "./dist-C6_wgXqF.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
+/**
+* Long-poll window handed to `pullFrames`/`pullHandles`: an empty drain blocks
+* decoder-side until a frame commits or this elapses, replacing the old ~1kHz
+* `setTimeout(…,1)` busy-spin with a single await-notify round-trip. Kept
+* modest so a hung UDS/Moleculer transport can't pin the call; the decoder
+* cancels the waiter on `destroySession` so teardown never waits it out.
+*/
+var POLL_WAIT_MS = 50;
 var DecoderSessionProxy = class {
 	api;
 	sessionId;
@@ -26,10 +34,10 @@ var DecoderSessionProxy = class {
 		while (this.polling) {
 			const frames = await this.api.pullFrames({
 				sessionId: this.sessionId,
-				maxCount: 4
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
 			});
 			for (const frame of frames) onFrame(frame);
-			if (frames.length === 0) await new Promise((r) => setTimeout(r, 1));
 		}
 	}
 	/**
@@ -49,10 +57,10 @@ var DecoderSessionProxy = class {
 		while (this.polling) try {
 			const handles = await this.api.pullHandles({
 				sessionId: this.sessionId,
-				maxCount: 4
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
 			});
 			for (const handle of handles) onHandle(handle);
-			if (handles.length === 0) await new Promise((r) => setTimeout(r, 1));
 		} catch (err) {
 			this.polling = false;
 			const msg = err instanceof Error ? err.message : String(err);

package/dist/{frame-handle-plane-DtTRX_0n.js → frame-handle-plane-D6BzyEgy.js}

@@ -1,6 +1,14 @@
-const require_dist = require("./dist-DAIlCdAx.js");
+const require_dist = require("./dist-Biq62zt4.js");
 let node_crypto = require("node:crypto");
 //#region src/stream-broker/stream-broker/decoder-session-proxy.ts
+/**
+* Long-poll window handed to `pullFrames`/`pullHandles`: an empty drain blocks
+* decoder-side until a frame commits or this elapses, replacing the old ~1kHz
+* `setTimeout(…,1)` busy-spin with a single await-notify round-trip. Kept
+* modest so a hung UDS/Moleculer transport can't pin the call; the decoder
+* cancels the waiter on `destroySession` so teardown never waits it out.
+*/
+var POLL_WAIT_MS = 50;
 var DecoderSessionProxy = class {
 	api;
 	sessionId;
@@ -26,10 +34,10 @@ var DecoderSessionProxy = class {
 		while (this.polling) {
 			const frames = await this.api.pullFrames({
 				sessionId: this.sessionId,
-				maxCount: 4
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
 			});
 			for (const frame of frames) onFrame(frame);
-			if (frames.length === 0) await new Promise((r) => setTimeout(r, 1));
 		}
 	}
 	/**
@@ -49,10 +57,10 @@ var DecoderSessionProxy = class {
 		while (this.polling) try {
 			const handles = await this.api.pullHandles({
 				sessionId: this.sessionId,
-				maxCount: 4
+				maxCount: 4,
+				waitMs: POLL_WAIT_MS
 			});
 			for (const handle of handles) onHandle(handle);
-			if (handles.length === 0) await new Promise((r) => setTimeout(r, 1));
 		} catch (err) {
 			this.polling = false;
 			const msg = err instanceof Error ? err.message : String(err);

package/dist/frame-ring-sink-9J0wCdLF.js

@@ -0,0 +1,444 @@
+const require_dist = require("./dist-Biq62zt4.js");
+let _camstack_shm_ring = require("@camstack/shm-ring");
+//#region src/shared/decoder-backend-keys.ts
+/** Built-in default when a node has no selection — the subprocess decoder. */
+var DEFAULT_DECODER_BACKEND = "ffmpeg";
+/** Narrow an unknown settings value to a {@link DecoderBackend}, else `null`. */
+function parseDecoderBackend(value) {
+	return value === "ffmpeg" || value === "nodeav" ? value : null;
+}
+/**
+* Normalise a raw kernel node id to the bare node id used for scoping.
+* `localNodeId` can carry a `<node>/<addon>` suffix; the decoder selection is
+* per-NODE, so strip the addon segment. Falls back to `hub`.
+*/
+function normalizeDecoderNodeId(rawNodeId) {
+	const raw = rawNodeId ?? "hub";
+	return raw.includes("/") ? raw.split("/")[0] ?? "hub" : raw;
+}
+//#endregion
+//#region src/shared/decoder-backend.ts
+/** The addon whose global settings OWN the per-node `backend` field. */
+var DECODER_OWNER_ADDON_ID = "decoder-ffmpeg";
+function isHydratedField(entry) {
+	return typeof entry === "object" && entry !== null && "key" in entry;
+}
+/**
+* Pure selection from an already-read hydrated settings payload: extract the
+* owner's `backend` field value (which the owner projected per-node from its
+* scoped store key) and narrow it. A missing/invalid field or a null payload
+* resolves to {@link DEFAULT_DECODER_BACKEND} — never a bare store key.
+*/
+function pickDecoderBackendFromSettings(view) {
+	if (view === null) return DEFAULT_DECODER_BACKEND;
+	for (const section of view.sections) for (const entry of section.fields) {
+		if (!isHydratedField(entry) || entry.key !== "backend") continue;
+		return parseDecoderBackend(entry.value) ?? "ffmpeg";
+	}
+	return DEFAULT_DECODER_BACKEND;
+}
+/**
+* Resolve the decoder backend this node should run. Called by BOTH decoder
+* addons at the start of `onInitialize`; the addon whose backend is NOT
+* selected registers nothing.
+*
+* Fails safe: no api surface, a read error, or a null payload (owner not
+* answering yet) resolves to {@link DEFAULT_DECODER_BACKEND} — the default
+* backend still registers, and the non-default one stands down (never both).
+*/
+async function resolveDecoderBackend(api, nodeId, logger) {
+	if (!api) {
+		logger.warn("decoder-backend: no api surface — using default backend", { meta: { default: DEFAULT_DECODER_BACKEND } });
+		return DEFAULT_DECODER_BACKEND;
+	}
+	try {
+		const view = await api.addonSettings.getGlobalSettings.query({
+			addonId: DECODER_OWNER_ADDON_ID,
+			nodeId: normalizeDecoderNodeId(nodeId)
+		});
+		if (view === null) {
+			logger.warn("decoder-backend: owner settings unavailable — using default backend", { meta: {
+				default: DEFAULT_DECODER_BACKEND,
+				owner: DECODER_OWNER_ADDON_ID
+			} });
+			return DEFAULT_DECODER_BACKEND;
+		}
+		return pickDecoderBackendFromSettings(view);
+	} catch (err) {
+		logger.warn("decoder-backend: settings read failed — using default backend", { meta: {
+			default: DEFAULT_DECODER_BACKEND,
+			error: err instanceof Error ? err.message : String(err)
+		} });
+		return DEFAULT_DECODER_BACKEND;
+	}
+}
+//#endregion
+//#region src/shared/notifying-ring-buffer.ts
+/**
+* A {@link RingBuffer} that can notify a single blocked consumer the moment an
+* item commits — the server side of the `pullFrames`/`pullHandles` long-poll.
+*
+* The decoder's `onFrame`/`onFrameHandle` callback drives `push()`; a consumer
+* that finds the ring momentarily empty calls {@link waitForItem} and is woken
+* on the very next `push()` (a real commit signal) rather than spinning at
+* ~1kHz on `setTimeout(…,1)`. If nothing commits it resolves after `waitMs`,
+* and {@link cancel} (session teardown) resolves any in-flight wait promptly so
+* a blocked long-poll never waits out `waitMs` on destroy.
+*
+* Semantics are otherwise identical to `RingBuffer`: fixed capacity,
+* latest-wins overwrite when full, FIFO `drain`.
+*/
+var NotifyingRingBuffer = class {
+	ring;
+	waiters = /* @__PURE__ */ new Set();
+	constructor(capacity) {
+		this.ring = new require_dist.RingBuffer(capacity);
+	}
+	get size() {
+		return this.ring.size;
+	}
+	push(item) {
+		this.ring.push(item);
+		this.wakeAll();
+	}
+	drain(maxCount) {
+		return this.ring.drain(maxCount);
+	}
+	/**
+	* Resolve as soon as an item commits to the ring, or after `waitMs`,
+	* whichever comes first. Returns immediately when items are already present
+	* or `waitMs <= 0` (legacy immediate-return). {@link cancel} also resolves an
+	* in-flight wait.
+	*/
+	async waitForItem(waitMs) {
+		if (this.ring.size > 0 || waitMs <= 0) return;
+		await new Promise((resolve) => {
+			let settled = false;
+			const finish = () => {
+				if (settled) return;
+				settled = true;
+				this.waiters.delete(wake);
+				clearTimeout(timer);
+				resolve();
+			};
+			const wake = () => finish();
+			const timer = setTimeout(finish, waitMs);
+			if (typeof timer.unref === "function") timer.unref();
+			this.waiters.add(wake);
+		});
+	}
+	/**
+	* Cancel every in-flight {@link waitForItem} — called on session teardown so
+	* a blocked long-poll returns promptly instead of waiting out `waitMs`.
+	*/
+	cancel() {
+		this.wakeAll();
+	}
+	wakeAll() {
+		if (this.waiters.size === 0) return;
+		const pending = [...this.waiters];
+		this.waiters.clear();
+		for (const wake of pending) wake();
+	}
+};
+//#endregion
+//#region src/decoder-ffmpeg/frame-ring-sink.ts
+/**
+* `DecoderFrameRingSink` — the decoder's shared-memory write side (Phase 5 / D9).
+*
+* When a decoder session is configured with `frameSink: 'shm'`, the decoder
+* **owns** the shared-memory ring segment for that stream: it creates the
+* segment on the first decoded frame (when the output geometry is known),
+* writes every subsequent decoded frame into the ring via a `FrameRingWriter`,
+* and closes + unlinks the segment when the session is destroyed.
+*
+* What leaves the decoder is no longer the pixel `Buffer` — it is a tiny,
+* serialisable `FrameHandle` (`FrameRingWriter.writeFrame`'s return value).
+* Same-host consumers (motion, detection, the WebRTC encoder) open the same
+* segment with a `FrameRingReader` and read the pixels zero-copy.
+*
+* ## Lazy segment creation
+*
+* The segment cannot be sized until the first frame: `slotByteLength` is
+* `width × height × bytesPerPixel`, and the output dimensions are only known
+* once the scaler has produced its first `dstFrame`. So `writeFrame` is a
+* no-op-until-armed: the first call sizes + creates the segment, every later
+* call writes into it.
+*
+* ## Resolution-change decision
+*
+* A live camera stream can change resolution mid-stream (the decoder's scaler
+* is rebuilt on a config toggle, or the source renegotiates). The slot is
+* sized for the **first** frame's geometry. A later frame that no longer fits
+* the slot triggers a **segment re-create**: the old segment is closed +
+* unlinked and a fresh, larger segment is created under a new generation-tagged
+* name. This is simpler and leak-free versus over-allocating slots for a
+* worst-case 4K frame on every stream; resolution changes on a live camera are
+* rare, and a brief gap while consumers re-open the segment is acceptable
+* (latest-wins — a missed frame is correct behaviour).
+*/
+/**
+* Per-ring shared-memory budget (MB) — the slot count is derived per-resolution
+* from this budget via {@link deriveSlotCount}, so a 360p stream gets many
+* slots and a 4K stream a few, both inside the same memory footprint.
+*
+* Read ONCE at module load from `CAMSTACK_SHM_RING_BUDGET_MB`; a non-finite or
+* non-positive value falls back to the 16 MB default.
+*
+* The default is deliberately small (16 MB) so many concurrent per-camera rings
+* fit inside a bounded `/dev/shm`. The decoder output is capped at 640px wide, so
+* a slot is ≤ ~920 KB and 16 MB still yields ~17–70 latest-wins slots. A ring
+* segment larger than the container's `/dev/shm` tmpfs backing (Docker default is
+* only 64 MB) faults an **uncatchable SIGBUS** on write past `st_size` — the old
+* 128 MB default overflowed a 64 MB `/dev/shm` and crashed the decoder on 8MP
+* streams. Pair this with a `--shm-size` that scales with concurrent-decode load.
+*/
+var RING_BUDGET_MB = (() => {
+	const raw = Number(process.env["CAMSTACK_SHM_RING_BUDGET_MB"]);
+	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 16;
+})();
+/** {@link RING_BUDGET_MB} in bytes — the budget passed to `deriveSlotCount`. */
+var RING_BUDGET_BYTES = RING_BUDGET_MB * 1024 * 1024;
+/** A unique, stable shared-memory segment name for a decoder stream.
+*
+* macOS POSIX shm names are capped at ~31 characters (`PSHMNAMLEN`). A
+* `camstack.frames.<deviceId>.<streamId>` scheme overflows that for realistic
+* ids, so the sink uses a short, collision-resistant scheme instead:
+* `csf.<base36 hash>.<gen>`. The hash folds the device id, the session tag
+* and a per-process random salt; the generation suffix makes a re-created
+* segment (resolution change) a distinct name so a stale consumer mapping is
+* never silently reused.
+*/
+function makeSegmentName(seed, generation) {
+	let hash = 5381;
+	for (let i = 0; i < seed.length; i += 1) hash = (hash << 5) + hash + seed.charCodeAt(i) | 0;
+	return `csf.${(hash >>> 0).toString(36)}.${generation}`;
+}
+/**
+* The decoder-side owner of one stream's shared-memory frame ring.
+*
+* Not constructed until a session actually uses the shm sink; the segment
+* itself is created lazily on the first `writeFrame`.
+*/
+var DecoderFrameRingSink = class {
+	seed;
+	logger;
+	nodeId;
+	segment = null;
+	writer = null;
+	segmentName = null;
+	slotByteLength = 0;
+	generation = 0;
+	destroyed = false;
+	/** Frames committed into the ring across this sink's lifetime (all generations). */
+	framesWritten = 0;
+	constructor(options) {
+		const salt = Math.random().toString(36).slice(2, 8);
+		this.seed = `${options.seed}.${salt}`;
+		this.logger = options.logger;
+		this.nodeId = options.nodeId;
+	}
+	/** Whether a segment has been created (i.e. at least one frame written). */
+	get isArmed() {
+		return this.writer !== null;
+	}
+	/** The current segment name, or `null` before the first frame. */
+	get currentSegmentName() {
+		return this.segmentName;
+	}
+	/**
+	* Write one decoded frame into the ring and return its `FrameHandle`.
+	*
+	* On the first call (or after a geometry change that overflows the current
+	* slot) the segment is created / re-created sized for this frame. Returns
+	* `null` only when the sink has been destroyed.
+	*
+	* This is the copy-in convenience form (it copies `pixels` into the slot).
+	* The decoder's hot path uses the zero-copy {@link beginFrame} /
+	* {@link commitFrame} scatter-write pair instead — the scaler produces its
+	* packed output directly into the slot, eliminating the write-side memcpy.
+	*/
+	writeFrame(pixels, meta) {
+		if (this.destroyed) return null;
+		if (this.writer === null || (0, _camstack_shm_ring.computeSlotByteLength)(meta.width, meta.height, meta.format) > this.slotByteLength) this.recreateSegment((0, _camstack_shm_ring.computeSlotByteLength)(meta.width, meta.height, meta.format));
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.writeFrame(pixels, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Reserve a ring slot for a frame of the given geometry — the **zero-copy**
+	* scatter-write entry point (Phase 5 / D9 Task 7c).
+	*
+	* The segment is created / re-created here if this is the first frame or the
+	* geometry overflows the current slot capacity, so the slot is correctly
+	* sized before the caller fills it. The returned `buffer` is a writable view
+	* **directly over the mapped segment** — the node-av scaler scatters its
+	* packed output straight into it, with no intermediate copy. The caller MUST
+	* call {@link commitFrame} with the returned `slot` once the slot is filled.
+	*
+	* Returns `null` when the sink is destroyed or the segment cannot be created.
+	*/
+	beginFrame(width, height, format) {
+		if (this.destroyed) return null;
+		const requiredSlotBytes = (0, _camstack_shm_ring.computeSlotByteLength)(width, height, format);
+		if (this.writer === null || requiredSlotBytes > this.slotByteLength) this.recreateSegment(requiredSlotBytes);
+		const writer = this.writer;
+		if (writer === null) return null;
+		const { slot, buffer } = writer.beginFrame();
+		return {
+			slot,
+			buffer
+		};
+	}
+	/**
+	* Publish the frame whose slot was reserved by {@link beginFrame} and filled
+	* in place by the caller. `slot` MUST be the value from the matching
+	* `beginFrame`. Returns the published `FrameHandle`, or `null` if the sink
+	* was destroyed (or the segment lost) between begin and commit.
+	*/
+	commitFrame(slot, meta) {
+		if (this.destroyed) return null;
+		const writer = this.writer;
+		if (writer === null) return null;
+		const handle = writer.commitFrame(slot, meta);
+		this.framesWritten += 1;
+		return handle;
+	}
+	/**
+	* Current shm ring usage — `null` until the first frame arms the segment.
+	* Surfaced through `decoder.getShmStats` so a downstream consumer can
+	* observe ring pressure (slot depth, byte budget, frames written).
+	*/
+	getShmStats() {
+		if (this.writer === null) return null;
+		return {
+			slotCount: this.writer.slotCount,
+			slotByteLength: this.slotByteLength,
+			segmentBytes: (0, _camstack_shm_ring.computeSegmentSize)(this.writer.slotCount, this.slotByteLength),
+			framesWritten: this.framesWritten
+		};
+	}
+	/**
+	* Abandon a slot reserved by {@link beginFrame} **without publishing it** —
+	* the degenerate-path counterpart of {@link commitFrame}.
+	*
+	* A caller that reserved a slot but then could not produce valid pixels (no
+	* decoded source planes, or the scaler threw) MUST call this instead of
+	* `commitFrame`: it closes the open seqlock without advancing `writeIndex`,
+	* so no reader ever sees the slot's uninitialised bytes as a real frame, and
+	* no `FrameHandle` is handed downstream. `slot` MUST be the value from the
+	* matching `beginFrame`. A no-op if the sink was destroyed (or the segment
+	* lost) between begin and abort.
+	*/
+	abortFrame(slot) {
+		if (this.destroyed) return;
+		const writer = this.writer;
+		if (writer === null) return;
+		writer.abortFrame(slot);
+	}
+	/** Close + unlink the segment. Idempotent. */
+	destroy() {
+		if (this.destroyed) return;
+		this.destroyed = true;
+		this.releaseSegment();
+	}
+	/**
+	* Create a fresh segment sized for at least `slotByteLength` bytes per slot,
+	* replacing any prior one. A re-create bumps the generation so the new
+	* segment has a distinct name — a consumer holding the old mapping is never
+	* silently handed a resized segment.
+	*/
+	recreateSegment(slotByteLength) {
+		this.releaseSegment();
+		this.generation += 1;
+		const name = makeSegmentName(this.seed, this.generation);
+		const slotCount = (0, _camstack_shm_ring.deriveSlotCount)(RING_BUDGET_BYTES, slotByteLength);
+		if (slotCount === _camstack_shm_ring.MIN_RING_SLOTS && _camstack_shm_ring.MIN_RING_SLOTS * slotByteLength > RING_BUDGET_BYTES) this.logger.warn("decoder shm ring: budget too small for resolution — using MIN slots", { meta: {
+			slotByteLength,
+			budgetMb: RING_BUDGET_MB
+		} });
+		const totalBytes = (0, _camstack_shm_ring.computeSegmentSize)(slotCount, slotByteLength);
+		try {
+			const segment = (0, _camstack_shm_ring.createSegment)(name, totalBytes);
+			this.segment = segment;
+			this.segmentName = name;
+			this.slotByteLength = slotByteLength;
+			this.writer = new _camstack_shm_ring.FrameRingWriter(segment.buffer, name, slotCount, slotByteLength, this.nodeId);
+			this.logger.info("decoder shm ring: segment created", { meta: {
+				segment: name,
+				slotCount,
+				slotByteLength,
+				totalBytes,
+				generation: this.generation
+			} });
+		} catch (err) {
+			this.segment = null;
+			this.writer = null;
+			this.segmentName = null;
+			this.slotByteLength = 0;
+			this.logger.error("decoder shm ring: segment create failed", { meta: {
+				segment: name,
+				slotByteLength,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	/** Unmap + unlink the current segment, if any. */
+	releaseSegment() {
+		const segment = this.segment;
+		if (segment === null) return;
+		this.segment = null;
+		this.writer = null;
+		const name = this.segmentName;
+		this.segmentName = null;
+		try {
+			segment.close();
+			segment.unlink();
+			this.logger.info("decoder shm ring: segment released", { meta: { segment: name } });
+		} catch (err) {
+			this.logger.warn("decoder shm ring: segment release failed", { meta: {
+				segment: name,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+Object.defineProperty(exports, "DEFAULT_DECODER_BACKEND", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_DECODER_BACKEND;
+	}
+});
+Object.defineProperty(exports, "DecoderFrameRingSink", {
+	enumerable: true,
+	get: function() {
+		return DecoderFrameRingSink;
+	}
+});
+Object.defineProperty(exports, "NotifyingRingBuffer", {
+	enumerable: true,
+	get: function() {
+		return NotifyingRingBuffer;
+	}
+});
+Object.defineProperty(exports, "RING_BUDGET_MB", {
+	enumerable: true,
+	get: function() {
+		return RING_BUDGET_MB;
+	}
+});
+Object.defineProperty(exports, "makeSegmentName", {
+	enumerable: true,
+	get: function() {
+		return makeSegmentName;
+	}
+});
+Object.defineProperty(exports, "resolveDecoderBackend", {
+	enumerable: true,
+	get: function() {
+		return resolveDecoderBackend;
+	}
+});