@camstack/addon-pipeline 1.2.81 → 1.2.82

package/dist/stream-broker/index.js

@@ -207,7 +207,9 @@ function formatProbedSummary(declared, snapshot, opts) {
 * on our own initiative, and says nothing about waking it because somebody
 * pressed play. That asymmetry is the whole design: brokers stay AVAILABLE
 * (definable, from the durable catalog) without being ACTIVE, and the dial is
-* the only thing that touches the camera.
+* the only thing that touches the camera. Concurrent/retried requests for the
+* same waking device share one transaction; a client retry must not become a
+* second physical wake.
 *
 * ## Honest states
 *
@@ -243,10 +245,48 @@ var BatteryStreamUnavailableError = class extends Error {
 };
 /** Bound on the firmware wake. Matches the cap's own sensible range. */
 var WAKE_FOR_STREAM_TIMEOUT_MS = 8e3;
-/** Bound on the post-wake catalog nudge. Sized off the camera's ~14s awake
-*  window: long enough for a real `onWakeTransition` catalog build to land,
-*  short enough that a viewer is not left staring at nothing. */
-var STREAM_PARAMS_SETTLE_TIMEOUT_MS = 6e3;
+/**
+* Bound AFTER firmware acknowledgement for the provider to rebuild/publish
+* stream parameters and the broker to observe them. Field cameras can
+* acknowledge several seconds before their media/catalog plane is usable.
+*/
+var BROKER_SETTLE_TIMEOUT_MS = 2e4;
+/** Reconcile cadence while the acknowledged camera finishes waking. */
+var BROKER_SETTLE_POLL_INTERVAL_MS = 1500;
+function wait(timeoutMs) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, timeoutMs).unref?.();
+	});
+}
+/**
+* Device-scoped single-flight for wake-on-play. A wake applies to the whole
+* camera, not one profile/brokerId, so concurrent profile requests and client
+* retries all await the same bounded transaction.
+*/
+var BatteryWakeOnPlaySingleFlight = class {
+	inFlight = /* @__PURE__ */ new Map();
+	async run(deviceId, deps) {
+		const existing = this.inFlight.get(deviceId);
+		if (existing) {
+			await existing;
+			if (!deps.hasBroker()) await deps.ensureBroker().catch((err) => {
+				deps.logger.debug("wake-on-play: joined demand broker retry failed", {
+					tags: { deviceId },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			});
+			if (!deps.hasBroker()) throw new BatteryStreamUnavailableError(deviceId, "waking", "the shared wake completed but this stream profile is not available yet — try again");
+			return;
+		}
+		const transaction = wakeBatteryDeviceForPlay(deviceId, deps);
+		this.inFlight.set(deviceId, transaction);
+		try {
+			await transaction;
+		} finally {
+			if (this.inFlight.get(deviceId) === transaction) this.inFlight.delete(deviceId);
+		}
+	}
+};
 /**
 * Make a broker available for a battery camera that has none, by asking the
 * camera to wake.
@@ -257,26 +297,25 @@ var STREAM_PARAMS_SETTLE_TIMEOUT_MS = 6e3;
 * {@link BatteryStreamUnavailableError} only for a battery camera we could not
 * produce a stream for — with the reason named.
 *
-* Retries the broker resolution exactly ONCE after the wake. A second wake
-* would be us deciding the camera should be up, which is the proactive
-* behaviour the contract forbids; the operator pressing play again is a new
-* demand and gets a new wake.
+* After an acknowledged wake, repeatedly reconciles the provider catalog and
+* retries broker resolution within one field-sized bound. It never issues a
+* second wake inside that transaction.
 */
 async function wakeBatteryDeviceForPlay(deviceId, deps) {
 	if (deps.hasBroker()) return;
 	if (await deps.isBatteryDevice(deviceId).catch(() => null) !== true) return;
 	const facts = await deps.readBatteryFacts(deviceId).catch(() => null);
-	const nowMs = (deps.nowMs ?? Date.now)();
+	const observedAt = (deps.nowMs ?? Date.now)();
 	const presence = require_dist.deriveBatteryPresence({
 		status: facts,
-		nowMs
+		nowMs: observedAt
 	});
 	if (presence === "unreachable") {
 		deps.logger.warn("wake-on-play refused — battery camera is unreachable, not asleep", {
 			tags: { deviceId },
 			meta: {
 				lastContactAt: facts?.lastContactAt ?? 0,
-				silenceMs: nowMs - (facts?.lastContactAt ?? 0)
+				silenceMs: observedAt - (facts?.lastContactAt ?? 0)
 			}
 		});
 		throw new BatteryStreamUnavailableError(deviceId, "unreachable", "nothing has been heard from it for hours — check the battery or its network");
@@ -292,29 +331,46 @@ async function wakeBatteryDeviceForPlay(deviceId, deps) {
 		awoke: false,
 		durationMs: 0
 	}));
-	const nudged = await deps.awaitStreamParamsChanged(deviceId, STREAM_PARAMS_SETTLE_TIMEOUT_MS).catch(() => false);
-	await deps.reconcileCatalog(deviceId).catch((err) => {
-		deps.logger.debug("wake-on-play: catalog reconcile failed", {
-			tags: { deviceId },
-			meta: { error: err instanceof Error ? err.message : String(err) }
-		});
-	});
-	await deps.ensureBroker().catch((err) => {
-		deps.logger.debug("wake-on-play: broker retry failed", {
-			tags: { deviceId },
-			meta: { error: err instanceof Error ? err.message : String(err) }
+	const nowMs = deps.nowMs ?? Date.now;
+	const settleStartedAt = nowMs();
+	const settleDeadline = settleStartedAt + (wake.awoke ? BROKER_SETTLE_TIMEOUT_MS : 0);
+	const maxAttempts = wake.awoke ? Math.ceil(BROKER_SETTLE_TIMEOUT_MS / BROKER_SETTLE_POLL_INTERVAL_MS) + 1 : 1;
+	let attempts = 0;
+	while (attempts < maxAttempts) {
+		attempts += 1;
+		await deps.reconcileCatalog(deviceId).catch((err) => {
+			deps.logger.debug("wake-on-play: catalog reconcile failed", {
+				tags: { deviceId },
+				meta: {
+					attempt: attempts,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
 		});
-	});
-	if (deps.hasBroker()) {
-		deps.logger.info("wake-on-play succeeded — broker available after wake", {
-			tags: { deviceId },
-			meta: {
-				awoke: wake.awoke,
-				wakeMs: wake.durationMs,
-				nudged
-			}
+		await deps.ensureBroker().catch((err) => {
+			deps.logger.debug("wake-on-play: broker retry failed", {
+				tags: { deviceId },
+				meta: {
+					attempt: attempts,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
 		});
-		return;
+		if (deps.hasBroker()) {
+			deps.logger.info("wake-on-play succeeded — broker available after wake", {
+				tags: { deviceId },
+				meta: {
+					awoke: wake.awoke,
+					wakeMs: wake.durationMs,
+					settleMs: nowMs() - settleStartedAt,
+					attempts
+				}
+			});
+			return;
+		}
+		const remainingMs = settleDeadline - nowMs();
+		if (remainingMs <= 0 || attempts >= maxAttempts) break;
+		await (deps.wait ?? wait)(Math.min(BROKER_SETTLE_POLL_INTERVAL_MS, remainingMs));
 	}
 	const outcome = wake.awoke ? "waking" : "sleeping";
 	deps.logger.warn("wake-on-play exhausted — no stream after the wake", {
@@ -322,7 +378,8 @@ async function wakeBatteryDeviceForPlay(deviceId, deps) {
 		meta: {
 			awoke: wake.awoke,
 			wakeMs: wake.durationMs,
-			nudged,
+			settleMs: nowMs() - settleStartedAt,
+			attempts,
 			outcome
 		}
 	});
@@ -14401,6 +14458,13 @@ var StreamBrokerManager = class StreamBrokerManager {
 	*/
 	brokerEnsures = /* @__PURE__ */ new Map();
 	/**
+	* Device-scoped wake-on-play transactions. A camera wake is shared by every
+	* profile, so Viewer retries or concurrent sessions must join the existing
+	* sleeping → waking → broker-settle transaction instead of issuing another
+	* `battery.wakeForStream` mutation.
+	*/
+	batteryWakeOnPlay = new BatteryWakeOnPlaySingleFlight();
+	/**
 	* brokerId → the profile tier a remote-ensured adapter was created for
 	* (Slice 3b Task 2). `this.assignments` only tracks LOCALLY-owned devices,
 	* so the `profileTierResolver` closure below always misses for a remote
@@ -15206,7 +15270,8 @@ var StreamBrokerManager = class StreamBrokerManager {
 	/**
 	* Wake-on-play (D173). Called by `WebrtcSessionProvider` when the normal
 	* resolution left no broker: if the device is battery-operated, ask the
-	* camera to wake, re-pull its catalog, and retry the resolution ONCE.
+	* camera to wake, then poll catalog reconciliation + broker resolution
+	* through one bounded settle transaction.
 	*
 	* Throws `BatteryStreamUnavailableError` — naming `sleeping` / `waking` /
 	* `unreachable` — instead of letting `BrokerWebrtcServer` answer a healthy,
@@ -15219,7 +15284,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (this.disabledDevices.has(deviceId)) return;
 		const api = this.api;
 		if (!api) return;
-		await wakeBatteryDeviceForPlay(deviceId, {
+		await this.batteryWakeOnPlay.run(deviceId, {
 			logger: this.logger,
 			isBatteryDevice: async (id) => {
 				const dev = await api.deviceManager.getDevice.query({ deviceId: id }).catch(() => null);
@@ -15242,38 +15307,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 				deviceId: id,
 				timeoutMs
 			}),
-			awaitStreamParamsChanged: (id, timeoutMs) => this.awaitStreamParamsChanged(id, timeoutMs),
 			reconcileCatalog: (id) => this.reconcileDeviceCatalog(id),
 			ensureBroker: () => this.ensureBrokerForWebrtcSession(deviceId, brokerId, camStreamId),
 			hasBroker: () => this.hasRegisteredBroker(brokerId)
 		});
 	}
 	/**
-	* Bounded wait for the provider's `StreamParamsChanged` nudge for one
-	* device. Resolves `false` on timeout — a timeout is information, not a
-	* failure: a catalog restored from the durable slice announces nothing, and
-	* the caller reconciles either way.
-	*/
-	awaitStreamParamsChanged(deviceId, timeoutMs) {
-		const bus = this.eventBus;
-		if (!bus) return Promise.resolve(false);
-		return new Promise((resolve) => {
-			let settled = false;
-			const finish = (value) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				unsubscribe();
-				resolve(value);
-			};
-			const unsubscribe = bus.subscribe({ category: require_dist.EventCategory.StreamParamsChanged }, (event) => {
-				if (event.data.deviceId === deviceId) finish(true);
-			});
-			const timer = setTimeout(() => finish(false), timeoutMs);
-			timer.unref?.();
-		});
-	}
-	/**
 	* Single-flight body for `ensureBrokerForWebrtcSession`'s remote-adapter
 	* get-or-create — resolves the ingest owner, and for `remote-adapter` mode
 	* constructs the `RemoteEncodedSourceBroker`, registers it with the WebRTC

package/dist/stream-broker/index.mjs

@@ -202,7 +202,9 @@ function formatProbedSummary(declared, snapshot, opts) {
 * on our own initiative, and says nothing about waking it because somebody
 * pressed play. That asymmetry is the whole design: brokers stay AVAILABLE
 * (definable, from the durable catalog) without being ACTIVE, and the dial is
-* the only thing that touches the camera.
+* the only thing that touches the camera. Concurrent/retried requests for the
+* same waking device share one transaction; a client retry must not become a
+* second physical wake.
 *
 * ## Honest states
 *
@@ -238,10 +240,48 @@ var BatteryStreamUnavailableError = class extends Error {
 };
 /** Bound on the firmware wake. Matches the cap's own sensible range. */
 var WAKE_FOR_STREAM_TIMEOUT_MS = 8e3;
-/** Bound on the post-wake catalog nudge. Sized off the camera's ~14s awake
-*  window: long enough for a real `onWakeTransition` catalog build to land,
-*  short enough that a viewer is not left staring at nothing. */
-var STREAM_PARAMS_SETTLE_TIMEOUT_MS = 6e3;
+/**
+* Bound AFTER firmware acknowledgement for the provider to rebuild/publish
+* stream parameters and the broker to observe them. Field cameras can
+* acknowledge several seconds before their media/catalog plane is usable.
+*/
+var BROKER_SETTLE_TIMEOUT_MS = 2e4;
+/** Reconcile cadence while the acknowledged camera finishes waking. */
+var BROKER_SETTLE_POLL_INTERVAL_MS = 1500;
+function wait(timeoutMs) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, timeoutMs).unref?.();
+	});
+}
+/**
+* Device-scoped single-flight for wake-on-play. A wake applies to the whole
+* camera, not one profile/brokerId, so concurrent profile requests and client
+* retries all await the same bounded transaction.
+*/
+var BatteryWakeOnPlaySingleFlight = class {
+	inFlight = /* @__PURE__ */ new Map();
+	async run(deviceId, deps) {
+		const existing = this.inFlight.get(deviceId);
+		if (existing) {
+			await existing;
+			if (!deps.hasBroker()) await deps.ensureBroker().catch((err) => {
+				deps.logger.debug("wake-on-play: joined demand broker retry failed", {
+					tags: { deviceId },
+					meta: { error: err instanceof Error ? err.message : String(err) }
+				});
+			});
+			if (!deps.hasBroker()) throw new BatteryStreamUnavailableError(deviceId, "waking", "the shared wake completed but this stream profile is not available yet — try again");
+			return;
+		}
+		const transaction = wakeBatteryDeviceForPlay(deviceId, deps);
+		this.inFlight.set(deviceId, transaction);
+		try {
+			await transaction;
+		} finally {
+			if (this.inFlight.get(deviceId) === transaction) this.inFlight.delete(deviceId);
+		}
+	}
+};
 /**
 * Make a broker available for a battery camera that has none, by asking the
 * camera to wake.
@@ -252,26 +292,25 @@ var STREAM_PARAMS_SETTLE_TIMEOUT_MS = 6e3;
 * {@link BatteryStreamUnavailableError} only for a battery camera we could not
 * produce a stream for — with the reason named.
 *
-* Retries the broker resolution exactly ONCE after the wake. A second wake
-* would be us deciding the camera should be up, which is the proactive
-* behaviour the contract forbids; the operator pressing play again is a new
-* demand and gets a new wake.
+* After an acknowledged wake, repeatedly reconciles the provider catalog and
+* retries broker resolution within one field-sized bound. It never issues a
+* second wake inside that transaction.
 */
 async function wakeBatteryDeviceForPlay(deviceId, deps) {
 	if (deps.hasBroker()) return;
 	if (await deps.isBatteryDevice(deviceId).catch(() => null) !== true) return;
 	const facts = await deps.readBatteryFacts(deviceId).catch(() => null);
-	const nowMs = (deps.nowMs ?? Date.now)();
+	const observedAt = (deps.nowMs ?? Date.now)();
 	const presence = deriveBatteryPresence({
 		status: facts,
-		nowMs
+		nowMs: observedAt
 	});
 	if (presence === "unreachable") {
 		deps.logger.warn("wake-on-play refused — battery camera is unreachable, not asleep", {
 			tags: { deviceId },
 			meta: {
 				lastContactAt: facts?.lastContactAt ?? 0,
-				silenceMs: nowMs - (facts?.lastContactAt ?? 0)
+				silenceMs: observedAt - (facts?.lastContactAt ?? 0)
 			}
 		});
 		throw new BatteryStreamUnavailableError(deviceId, "unreachable", "nothing has been heard from it for hours — check the battery or its network");
@@ -287,29 +326,46 @@ async function wakeBatteryDeviceForPlay(deviceId, deps) {
 		awoke: false,
 		durationMs: 0
 	}));
-	const nudged = await deps.awaitStreamParamsChanged(deviceId, STREAM_PARAMS_SETTLE_TIMEOUT_MS).catch(() => false);
-	await deps.reconcileCatalog(deviceId).catch((err) => {
-		deps.logger.debug("wake-on-play: catalog reconcile failed", {
-			tags: { deviceId },
-			meta: { error: err instanceof Error ? err.message : String(err) }
-		});
-	});
-	await deps.ensureBroker().catch((err) => {
-		deps.logger.debug("wake-on-play: broker retry failed", {
-			tags: { deviceId },
-			meta: { error: err instanceof Error ? err.message : String(err) }
+	const nowMs = deps.nowMs ?? Date.now;
+	const settleStartedAt = nowMs();
+	const settleDeadline = settleStartedAt + (wake.awoke ? BROKER_SETTLE_TIMEOUT_MS : 0);
+	const maxAttempts = wake.awoke ? Math.ceil(BROKER_SETTLE_TIMEOUT_MS / BROKER_SETTLE_POLL_INTERVAL_MS) + 1 : 1;
+	let attempts = 0;
+	while (attempts < maxAttempts) {
+		attempts += 1;
+		await deps.reconcileCatalog(deviceId).catch((err) => {
+			deps.logger.debug("wake-on-play: catalog reconcile failed", {
+				tags: { deviceId },
+				meta: {
+					attempt: attempts,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
 		});
-	});
-	if (deps.hasBroker()) {
-		deps.logger.info("wake-on-play succeeded — broker available after wake", {
-			tags: { deviceId },
-			meta: {
-				awoke: wake.awoke,
-				wakeMs: wake.durationMs,
-				nudged
-			}
+		await deps.ensureBroker().catch((err) => {
+			deps.logger.debug("wake-on-play: broker retry failed", {
+				tags: { deviceId },
+				meta: {
+					attempt: attempts,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
 		});
-		return;
+		if (deps.hasBroker()) {
+			deps.logger.info("wake-on-play succeeded — broker available after wake", {
+				tags: { deviceId },
+				meta: {
+					awoke: wake.awoke,
+					wakeMs: wake.durationMs,
+					settleMs: nowMs() - settleStartedAt,
+					attempts
+				}
+			});
+			return;
+		}
+		const remainingMs = settleDeadline - nowMs();
+		if (remainingMs <= 0 || attempts >= maxAttempts) break;
+		await (deps.wait ?? wait)(Math.min(BROKER_SETTLE_POLL_INTERVAL_MS, remainingMs));
 	}
 	const outcome = wake.awoke ? "waking" : "sleeping";
 	deps.logger.warn("wake-on-play exhausted — no stream after the wake", {
@@ -317,7 +373,8 @@ async function wakeBatteryDeviceForPlay(deviceId, deps) {
 		meta: {
 			awoke: wake.awoke,
 			wakeMs: wake.durationMs,
-			nudged,
+			settleMs: nowMs() - settleStartedAt,
+			attempts,
 			outcome
 		}
 	});
@@ -14396,6 +14453,13 @@ var StreamBrokerManager = class StreamBrokerManager {
 	*/
 	brokerEnsures = /* @__PURE__ */ new Map();
 	/**
+	* Device-scoped wake-on-play transactions. A camera wake is shared by every
+	* profile, so Viewer retries or concurrent sessions must join the existing
+	* sleeping → waking → broker-settle transaction instead of issuing another
+	* `battery.wakeForStream` mutation.
+	*/
+	batteryWakeOnPlay = new BatteryWakeOnPlaySingleFlight();
+	/**
 	* brokerId → the profile tier a remote-ensured adapter was created for
 	* (Slice 3b Task 2). `this.assignments` only tracks LOCALLY-owned devices,
 	* so the `profileTierResolver` closure below always misses for a remote
@@ -15201,7 +15265,8 @@ var StreamBrokerManager = class StreamBrokerManager {
 	/**
 	* Wake-on-play (D173). Called by `WebrtcSessionProvider` when the normal
 	* resolution left no broker: if the device is battery-operated, ask the
-	* camera to wake, re-pull its catalog, and retry the resolution ONCE.
+	* camera to wake, then poll catalog reconciliation + broker resolution
+	* through one bounded settle transaction.
 	*
 	* Throws `BatteryStreamUnavailableError` — naming `sleeping` / `waking` /
 	* `unreachable` — instead of letting `BrokerWebrtcServer` answer a healthy,
@@ -15214,7 +15279,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		if (this.disabledDevices.has(deviceId)) return;
 		const api = this.api;
 		if (!api) return;
-		await wakeBatteryDeviceForPlay(deviceId, {
+		await this.batteryWakeOnPlay.run(deviceId, {
 			logger: this.logger,
 			isBatteryDevice: async (id) => {
 				const dev = await api.deviceManager.getDevice.query({ deviceId: id }).catch(() => null);
@@ -15237,38 +15302,12 @@ var StreamBrokerManager = class StreamBrokerManager {
 				deviceId: id,
 				timeoutMs
 			}),
-			awaitStreamParamsChanged: (id, timeoutMs) => this.awaitStreamParamsChanged(id, timeoutMs),
 			reconcileCatalog: (id) => this.reconcileDeviceCatalog(id),
 			ensureBroker: () => this.ensureBrokerForWebrtcSession(deviceId, brokerId, camStreamId),
 			hasBroker: () => this.hasRegisteredBroker(brokerId)
 		});
 	}
 	/**
-	* Bounded wait for the provider's `StreamParamsChanged` nudge for one
-	* device. Resolves `false` on timeout — a timeout is information, not a
-	* failure: a catalog restored from the durable slice announces nothing, and
-	* the caller reconciles either way.
-	*/
-	awaitStreamParamsChanged(deviceId, timeoutMs) {
-		const bus = this.eventBus;
-		if (!bus) return Promise.resolve(false);
-		return new Promise((resolve) => {
-			let settled = false;
-			const finish = (value) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				unsubscribe();
-				resolve(value);
-			};
-			const unsubscribe = bus.subscribe({ category: EventCategory.StreamParamsChanged }, (event) => {
-				if (event.data.deviceId === deviceId) finish(true);
-			});
-			const timer = setTimeout(() => finish(false), timeoutMs);
-			timer.unref?.();
-		});
-	}
-	/**
 	* Single-flight body for `ensureBrokerForWebrtcSession`'s remote-adapter
 	* get-or-create — resolves the ingest owner, and for `remote-adapter` mode
 	* constructs the `RemoteEncodedSourceBroker`, registers it with the WebRTC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-pipeline",
-  "version": "1.2.81",
+  "version": "1.2.82",
   "description": "Pipeline bundle — runner, detection, motion, audio + stream broker. Multi-entry npm package shipping pipeline addons under a single bundle.",
   "keywords": [
     "camstack",