@camstack/addon-pipeline 1.1.24 → 1.1.26

package/dist/pipeline-runner/index.mjs

@@ -1,4 +1,6 @@
-import { A as nodePin, B as BaseAddon, M as pipelineRunnerCapability, S as defineCustomActions, W as EventCategory, X as makeSourceBrokerId, at as lazy, ct as object, nt as array, q as createEvent, rt as boolean, st as number, tt as _enum, ut as string, y as customAction, z as errMsg } from "../dist-pd_-3C0T.mjs";
+import { B as errMsg, C as defineCustomActions, G as EventCategory, J as createEvent, N as pipelineRunnerCapability, V as BaseAddon, Z as makeSourceBrokerId, b as customAction, ct as number, dt as string, it as boolean, j as nodePin, lt as object, nt as _enum, ot as lazy, rt as array } from "../dist-CgEP_0OL.mjs";
+import { t as FrameHandlePlane } from "../frame-handle-plane-Dq20KtKL.mjs";
+import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 //#region src/pipeline-runner/bench-actions.ts
 /**
@@ -236,6 +238,26 @@ var INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS = 250;
 */
 var MAX_SUBSCRIBE_RETRY_BACKOFF_MS = 5e3;
 /**
+* The default source: the broker's shm plane over tRPC — today's path. The
+* methods return the underlying client promises DIRECTLY (no async wrapper)
+* so the poller's scheduling is microtask-identical to the pre-seam code.
+*/
+function brokerFrameHandleSource(api, brokerId) {
+	return {
+		subscribe: (input) => api.streamBroker.subscribeFrames.mutate({
+			brokerId,
+			format: input.format,
+			maxFps: input.maxFps,
+			tag: input.tag
+		}),
+		pullHandles: (input) => api.streamBroker.pullFrameHandles.query({
+			subscriptionId: input.subscriptionId,
+			maxCount: input.maxCount
+		}),
+		unsubscribe: (input) => api.streamBroker.unsubscribeFrames.mutate({ subscriptionId: input.subscriptionId }).then(() => void 0)
+	};
+}
+/**
 * Subscribe to a broker's shm frame stream and start the poll loop. Always
 * resolves to a teardown closure — when the broker is not yet registered the
 * closure cancels the ongoing retry loop; when polling is active it stops the
@@ -267,19 +289,19 @@ async function startFrameHandlePoller(options) {
 */
 async function subscribeWithRetry(options, lifecycle) {
 	const { api, brokerId, format, maxFps, tag, logger } = options;
+	const source = options.source ?? brokerFrameHandleSource(api, brokerId);
 	let backoffMs = INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS;
 	let attempt = 0;
 	while (!lifecycle.stopped) {
 		attempt += 1;
 		try {
-			const result = await api.streamBroker.subscribeFrames.mutate({
-				brokerId,
+			const result = await source.subscribe({
 				format,
 				maxFps,
 				tag
 			});
 			if (lifecycle.stopped) {
-				await api.streamBroker.unsubscribeFrames.mutate({ subscriptionId: result.subscriptionId }).catch((err) => {
+				await source.unsubscribe({ subscriptionId: result.subscriptionId }).catch((err) => {
 					logger.warn("frame-handle poller: late unsubscribe failed", { meta: {
 						brokerId,
 						subscriptionId: result.subscriptionId,
@@ -288,7 +310,7 @@ async function subscribeWithRetry(options, lifecycle) {
 				});
 				return;
 			}
-			lifecycle.activeTeardown = startPolling(options, result.subscriptionId, result.maxFps, lifecycle);
+			lifecycle.activeTeardown = startPolling(options, source, result.subscriptionId, result.maxFps, lifecycle);
 			return;
 		} catch (err) {
 			if (lifecycle.stopped) return;
@@ -329,8 +351,8 @@ function sleep(ms, lifecycle) {
 * Returns the teardown closure that stops the loop and releases the
 * subscription.
 */
-function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
-	const { api, brokerId, onFrame, logger, ownNodeId, getRemoteFrame, tag } = options;
+function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle) {
+	const { brokerId, onFrame, logger, ownNodeId, getRemoteFrame, tag } = options;
 	const readers = new FrameRingReaderCache(logger);
 	const throttle = new ForeignHandleThrottle();
 	const pollIntervalMs = resolvedMaxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / resolvedMaxFps)) : FALLBACK_POLL_INTERVAL_MS;
@@ -338,7 +360,7 @@ function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
 	const tick = async () => {
 		if (lifecycle.stopped) return;
 		try {
-			const handles = await api.streamBroker.pullFrameHandles.query({
+			const handles = await source.pullHandles({
 				subscriptionId,
 				maxCount: PULL_MAX_COUNT
 			});
@@ -370,8 +392,8 @@ function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
 			timer = void 0;
 		}
 		readers.close();
-		api.streamBroker.unsubscribeFrames.mutate({ subscriptionId }).catch((err) => {
-			logger.warn("frame-handle poller: unsubscribeFrames failed", { meta: {
+		source.unsubscribe({ subscriptionId }).catch((err) => {
+			logger.warn("frame-handle poller: unsubscribe failed", { meta: {
 				brokerId,
 				subscriptionId,
 				error: errMsg(err)
@@ -380,6 +402,221 @@ function startPolling(options, subscriptionId, resolvedMaxFps, lifecycle) {
 	};
 }
 //#endregion
+//#region src/pipeline-runner/remote-source-plane.ts
+/**
+* Runner-side mode selection (pure): whether an attach payload routes this
+* camera through the remote-source leg. Absent `frameSource` (a pre-P2c
+* payload) and `local-broker` both take today's co-located broker path —
+* the rollout-OFF safety invariant.
+*/
+function isRemoteRestream(frameSource) {
+	return frameSource !== void 0 && frameSource.kind === "remote-restream";
+}
+/**
+* Resolve WHICH broker profile a camStream id feeds for a device (pure).
+*
+* `getStreamWithCodec` targets a PROFILE (its assigned camStream), while the
+* runner is dispatched with camStream ids (`motionStreamId` /
+* `detectionStreamId`). The broker's profile slots carry the mapping
+* (`sourceCamStreamId`); a stream no slot feeds returns `null` — the acquire
+* fails fast and the poller's backoff retries (the assignment may still be
+* propagating).
+*/
+function profileForStreamId(slots, deviceId, streamId) {
+	for (const slot of slots) if (slot.deviceId === deviceId && slot.sourceCamStreamId === streamId) return slot.profile;
+	return null;
+}
+var RemoteSourcePlane = class {
+	api;
+	logger;
+	deviceId;
+	ownNodeId;
+	hostname;
+	/** Single-flight entry creation per camStream id. */
+	entries = /* @__PURE__ */ new Map();
+	disposed = false;
+	constructor(options) {
+		this.api = options.api;
+		this.logger = options.logger.withTags({ deviceId: options.deviceId });
+		this.deviceId = options.deviceId;
+		this.ownNodeId = options.ownNodeId;
+		this.hostname = options.hostname;
+	}
+	/**
+	* A {@link FrameHandleSource} for one camStream id, pluggable into
+	* `startFrameHandlePoller`. Motion (`gray`) and detection (`rgb`)
+	* subscriptions of the same stream share ONE acquired restream and ONE
+	* satellite plane (per-format decoder sessions inside it — hub parity).
+	*/
+	makeSource(streamId) {
+		return {
+			subscribe: async (input) => {
+				if (this.disposed) throw new Error("RemoteSourcePlane: subscribe after dispose");
+				const entry = await this.ensureEntry(streamId);
+				const result = await entry.plane.subscribe({
+					format: input.format,
+					maxFps: input.maxFps,
+					tag: input.tag
+				});
+				entry.subscriptionIds.add(result.subscriptionId);
+				return result;
+			},
+			pullHandles: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return [];
+				return entry.plane.pullHandles(input.subscriptionId, input.maxCount);
+			},
+			unsubscribe: async (input) => {
+				const entry = await this.peekEntry(streamId);
+				if (!entry) return;
+				entry.subscriptionIds.delete(input.subscriptionId);
+				await entry.plane.unsubscribe(input.subscriptionId).catch(() => {});
+				if (entry.subscriptionIds.size === 0) {
+					this.entries.delete(streamId);
+					await this.teardownEntry(entry, streamId);
+				}
+			}
+		};
+	}
+	/** Dispose every entry: satellite planes destroyed, restreams released. Idempotent. */
+	async dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		const pending = [...this.entries.entries()];
+		this.entries.clear();
+		for (const [streamId, entryPromise] of pending) try {
+			const entry = await entryPromise;
+			await this.teardownEntry(entry, streamId);
+		} catch {}
+	}
+	/** The live entry for a stream, or `null` (never creates one). */
+	async peekEntry(streamId) {
+		const pending = this.entries.get(streamId);
+		if (!pending) return null;
+		try {
+			return await pending;
+		} catch {
+			return null;
+		}
+	}
+	/** Single-flight: acquire the restream + build the satellite plane once per stream. */
+	ensureEntry(streamId) {
+		const existing = this.entries.get(streamId);
+		if (existing) return existing;
+		const creation = this.createEntry(streamId);
+		this.entries.set(streamId, creation);
+		creation.catch(() => {
+			if (this.entries.get(streamId) === creation) this.entries.delete(streamId);
+		});
+		return creation;
+	}
+	async createEntry(streamId) {
+		const { api, deviceId, ownNodeId } = this;
+		if (this.hostname === void 0) throw new Error("RemoteSourcePlane: owner hostname unresolvable — set frameSource.hubHostnameOverride or CAMSTACK_HUB_URL (a 127.0.0.1 restream URL would dial the wrong box)");
+		const profile = profileForStreamId(await api.streamBroker.listAllProfileSlots.query(), deviceId, streamId);
+		if (profile === null) throw new Error(`RemoteSourcePlane: no broker profile is fed by camStream '${streamId}' of device ${deviceId} — cannot acquire the owner restream`);
+		const rtpSource = await api.streamBroker.getStreamWithCodec.mutate({
+			deviceId,
+			video: "copy",
+			audio: "none",
+			profile,
+			hostname: this.hostname,
+			tag: `runner:${ownNodeId}:remote-src:${deviceId}/${streamId}`
+		});
+		const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
+		const plane = new FrameHandlePlane({
+			decoderApi: this.buildPinnedDecoderCapApi(),
+			logger: this.logger,
+			localNodeId: ownNodeId,
+			resolveStreamInfo: () => ({
+				codec,
+				numericDeviceId: deviceId,
+				tag: `runner-remote:${deviceId}/${streamId}`,
+				pullModeUrl: rtpSource.url
+			})
+		});
+		this.logger.info("remote-source plane: owner restream acquired", { meta: {
+			streamId,
+			profile,
+			codec,
+			pipelineKey: rtpSource.pipelineKey,
+			hostname: this.hostname
+		} });
+		return {
+			plane,
+			pipelineKey: rtpSource.pipelineKey,
+			subscriptionIds: /* @__PURE__ */ new Set(),
+			released: false
+		};
+	}
+	/** Destroy an entry's satellite plane and release its restream refcount once. */
+	async teardownEntry(entry, streamId) {
+		await entry.plane.dispose().catch((err) => {
+			this.logger.warn("remote-source plane: satellite plane dispose failed", { meta: {
+				streamId,
+				error: errMsg(err)
+			} });
+		});
+		if (entry.released) return;
+		entry.released = true;
+		await this.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: entry.pipelineKey }).catch((err) => {
+			this.logger.debug("remote-source plane: releaseStreamWithCodec failed (benign on hub restart)", { meta: {
+				streamId,
+				pipelineKey: entry.pipelineKey,
+				error: errMsg(err)
+			} });
+		});
+	}
+	/**
+	* Every decoder call pinned to THIS runner's node — mirror of the hub
+	* broker's wrapper (`stream-broker-manager.buildDecoderCapApi`): the
+	* `decoder` cap is a singleton whose UNPINNED calls resolve to the
+	* cluster-elected node, which is generally NOT this agent. Pinning create
+	* AND every session op to the same local node keeps the session + its shm
+	* ring here, where this plane's readers live.
+	*/
+	buildPinnedDecoderCapApi() {
+		const api = this.api;
+		const pin = nodePin(this.ownNodeId);
+		const toWireBytes = (bytes) => {
+			const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+			copy.set(bytes);
+			return copy;
+		};
+		return {
+			supportsCodec: async (input) => api.decoder.supportsCodec.query({ ...input }, pin),
+			getInfo: async () => api.decoder.getInfo.query(void 0, pin),
+			createSession: async (config) => api.decoder.createSession.query({ ...config }, pin),
+			pushPacket: async (input) => {
+				await api.decoder.pushPacket.query({
+					sessionId: input.sessionId,
+					packet: {
+						...input.packet,
+						data: toWireBytes(input.packet.data)
+					}
+				}, pin);
+			},
+			pullFrames: async (input) => {
+				return (await api.decoder.pullFrames.query({ ...input }, pin)).map((frame) => ({
+					...frame,
+					data: Buffer.from(frame.data)
+				}));
+			},
+			pullHandles: async (input) => api.decoder.pullHandles.query({ ...input }, pin),
+			destroySession: async (input) => {
+				await api.decoder.destroySession.query({ ...input }, pin);
+			},
+			openStream: async (input) => {
+				await api.decoder.openStream.query({ ...input }, pin);
+			},
+			updateConfig: async (input) => {
+				await api.decoder.updateConfig.query({ ...input }, pin);
+			},
+			getStats: async (input) => api.decoder.getStats.query({ ...input }, pin)
+		};
+	}
+};
+//#endregion
 //#region src/pipeline-runner/frame-queue.ts
 /**
 * Latest-frame-only buffer. Keeps only the most recent item, dropping all
@@ -537,7 +774,10 @@ var PipelineTimingSampler = class {
 	detSamples = /* @__PURE__ */ new Map();
 	motSamples = /* @__PURE__ */ new Map();
 	audioSamples = /* @__PURE__ */ new Map();
-	droppedFrames = 0;
+	/** Per-device cumulative dropped-frames readers (see {@link DroppedFramesSource}). */
+	droppedSources = /* @__PURE__ */ new Map();
+	/** Cumulative value seen at the previous report — the delta base. */
+	lastDroppedCumulative = /* @__PURE__ */ new Map();
 	reportTimer = null;
 	log = null;
 	runtimeInfo = {};
@@ -569,13 +809,34 @@ var PipelineTimingSampler = class {
 		if (!this.audioSamples.has(deviceId)) this.audioSamples.set(deviceId, []);
 		this.audioSamples.get(deviceId).push(s);
 	}
-	addDrop() {
-		this.droppedFrames++;
+	/**
+	* Register the cumulative dropped-frames reader for a device. The
+	* baseline snapshot is taken immediately so the first report after
+	* registration only covers drops that happened AFTER registration.
+	*/
+	setDroppedFramesSource(deviceId, source) {
+		this.droppedSources.set(deviceId, source);
+		this.lastDroppedCumulative.set(deviceId, source());
+	}
+	clearDroppedFramesSource(deviceId) {
+		this.droppedSources.delete(deviceId);
+		this.lastDroppedCumulative.delete(deviceId);
+	}
+	/**
+	* Snapshot the device's cumulative dropped counter and return the
+	* delta since the previous snapshot. Guarded to never go negative
+	* (a replaced/reset queue restarts its counter at 0).
+	*/
+	sampleDroppedDelta(deviceId) {
+		const source = this.droppedSources.get(deviceId);
+		if (!source) return 0;
+		const cumulative = source();
+		const previous = this.lastDroppedCumulative.get(deviceId) ?? 0;
+		this.lastDroppedCumulative.set(deviceId, cumulative);
+		return Math.max(0, cumulative - previous);
 	}
 	report() {
 		if (!this.log) return;
-		const dropped = this.droppedFrames;
-		this.droppedFrames = 0;
 		const avg = (arr) => arr.length > 0 ? Math.round(arr.reduce((a, b) => a + b, 0) / arr.length) : 0;
 		const max = (arr) => arr.length > 0 ? Math.round(Math.max(...arr)) : 0;
 		const p95 = (arr) => {
@@ -584,8 +845,11 @@ var PipelineTimingSampler = class {
 			return Math.round(sorted[Math.floor(sorted.length * .95)] ?? sorted[sorted.length - 1]);
 		};
 		const rt = this.runtimeInfo;
-		for (const [deviceId, det] of this.detSamples) {
-			if (det.length === 0) continue;
+		const statDeviceIds = new Set([...this.detSamples.keys(), ...this.droppedSources.keys()]);
+		for (const deviceId of statDeviceIds) {
+			const det = this.detSamples.get(deviceId) ?? [];
+			const dropped = this.sampleDroppedDelta(deviceId);
+			if (det.length === 0 && dropped === 0) continue;
 			const e2e = det.map((s) => s.endToEnd);
 			const inf = det.map((s) => s.inference);
 			const frameAge = det.map((s) => s.frameAge).filter((v) => v >= 0);
@@ -781,6 +1045,7 @@ var PipelineRunner = class {
 			occupancyTimer: null
 		};
 		this.cameras.set(deviceId, state);
+		this.timingSampler.setDroppedFramesSource(deviceId, () => detectionQueue.droppedFrames);
 		if (registration.detectionMode === "on-motion") this.defaultRoundRobinKeys.push(deviceId);
 		if (registration.detectionMode === "on-motion" && (registration.occupancyRecheckSec ?? 0) > 0) state.occupancyTimer = setInterval(() => {
 			if (state.phase === "watching") this.config.onOccupancyRecheck?.(deviceId, registration.occupancyRecheckFrames ?? 4);
@@ -810,6 +1075,7 @@ var PipelineRunner = class {
 		if (state.phase === "active") this.detectionStreamHandler?.(deviceId, "unsubscribe");
 		state.motionQueue.clear();
 		state.detectionQueue.clear();
+		this.timingSampler.clearDroppedFramesSource(deviceId);
 		this.cameras.delete(deviceId);
 		const idx = this.defaultRoundRobinKeys.indexOf(deviceId);
 		if (idx !== -1) {
@@ -1153,6 +1419,14 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	*/
 	onboardAnalyzerTeardownTimers = /* @__PURE__ */ new Map();
 	/**
+	* REMOTE-SOURCE legs (cross-node Phase 2, P2d) — one per attached camera
+	* whose `frameSource.kind === 'remote-restream'`: the owner's compressed
+	* restream + a local satellite frame plane. DORMANT with today's default
+	* payloads (`local-broker` / absent) — the map stays empty and every code
+	* path is identical to pre-Phase-2. Torn down on detach / shutdown.
+	*/
+	remotePlanes = /* @__PURE__ */ new Map();
+	/**
 	* Snapshot-equality cache for metrics-snapshot defer. The runner
 	* fires per-camera metrics every `METRICS_SNAPSHOT_INTERVAL_MS`;
 	* for an idle camera (no inference, queue empty, fps=0) every tick
@@ -1248,6 +1522,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		}
 		this.lastAnalyzerDetected.clear();
 		for (const deviceId of [...this.onboardAnalyzerTeardownTimers.keys(), ...this.onboardAnalyzerSubs.keys()]) this.clearOnboardAnalyzer(deviceId);
+		const remotePlanes = [...this.remotePlanes.values()];
+		this.remotePlanes.clear();
+		await Promise.all(remotePlanes.map((plane) => plane.dispose().catch(() => {})));
 		if (this.runner) {
 			this.runner.stop();
 			this.runner = null;
@@ -1643,6 +1920,16 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		this.clearOnboardAnalyzer(deviceId);
 		attachment.motionUnsubscribe?.();
 		attachment.detectionUnsubscribe?.();
+		const remotePlane = this.remotePlanes.get(deviceId);
+		if (remotePlane) {
+			this.remotePlanes.delete(deviceId);
+			remotePlane.dispose().catch((err) => {
+				this.ctx?.logger.debug("remote-source plane dispose failed on detach", {
+					tags: { deviceId },
+					meta: { error: errMsg(err) }
+				});
+			});
+		}
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
@@ -1784,6 +2071,39 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			timestamp: remote.timestamp
 		};
 	}
+	/**
+	* The remote-source leg for a camera, or `null` for today's co-located
+	* broker path (P2d). Created lazily on the FIRST subscription of a
+	* `remote-restream` camera and shared by its motion + detection pollers;
+	* `detachInternal` / `onShutdown` dispose it. With rollout OFF every
+	* attach payload is `local-broker` (or absent) → always `null` → the
+	* subscribe paths below are byte-identical to pre-Phase-2.
+	*/
+	remoteSourceFor(config) {
+		const frameSource = config.frameSource;
+		if (!isRemoteRestream(frameSource)) return null;
+		const existing = this.remotePlanes.get(config.deviceId);
+		if (existing) return existing;
+		const api = this.ctx.api;
+		if (!api) return null;
+		const hostname = resolveHubHostname(frameSource.hubHostnameOverride, process.env["CAMSTACK_HUB_URL"]);
+		const plane = new RemoteSourcePlane({
+			api,
+			logger: this.ctx.logger,
+			deviceId: config.deviceId,
+			ownNodeId: this.nodeId,
+			hostname
+		});
+		this.ctx.logger.info("remote-source leg armed for camera", {
+			tags: { deviceId: config.deviceId },
+			meta: {
+				ownerNodeId: frameSource.ownerNodeId,
+				hostname: hostname ?? "(unresolved — acquires will fail until set)"
+			}
+		});
+		this.remotePlanes.set(config.deviceId, plane);
+		return plane;
+	}
 	async subscribeMotionFrames(config) {
 		const ctx = this.ctx;
 		const runner = this.runner;
@@ -1794,6 +2114,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			log.warn("subscribeMotionFrames: this.ctx.api not available");
 			return null;
 		}
+		const remote = this.remoteSourceFor(config);
 		return startFrameHandlePoller({
 			api,
 			brokerId: makeSourceBrokerId(config.deviceId, config.motionStreamId),
@@ -1803,6 +2124,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			logger: log,
 			ownNodeId: this.nodeId,
 			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
+			...remote ? { source: remote.makeSource(config.motionStreamId) } : {},
 			onFrame: (frame, _handle) => {
 				runner.enqueueMotionFrame(config.deviceId, frame);
 			}
@@ -1879,6 +2201,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			log.warn("subscribeDetectionFrames: this.ctx.api not available");
 			return null;
 		}
+		const remote = this.remoteSourceFor(config);
 		return startFrameHandlePoller({
 			api,
 			brokerId: makeSourceBrokerId(config.deviceId, config.detectionStreamId),
@@ -1888,6 +2211,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			logger: log,
 			ownNodeId: this.nodeId,
 			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
+			...remote ? { source: remote.makeSource(config.detectionStreamId) } : {},
 			onFrame: (frame, handle) => {
 				runner.enqueueDetectionFrame(config.deviceId, frame, handle);
 			}