@camstack/system 1.1.41 → 1.1.43

package/dist/builtins/snapshot/index.js

@@ -3,8 +3,203 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-BCseJMTD.js");
+const require_dist = require("../../dist-BP89I7gi.js");
 let node_child_process = require("node:child_process");
+//#region src/builtins/snapshot/snapshot-coalescing.ts
+/**
+* Pure, side-effect-free coalescing / stale-while-revalidate / bounded-pool
+* primitives for the snapshot wrapper.
+*
+* These are extracted from `SnapshotAddon` so the decision logic is unit-testable
+* without instantiating the addon (no camera, no ffmpeg, no tRPC). The addon wires
+* them to its cache + ladder; this module owns only the mechanics:
+*
+*   - {@link decideSnapshotServe} — the pure serve/refresh decision (fresh cache vs
+*     stale-while-revalidate vs cold blocking capture) keyed off the cached frame
+*     age, the per-device max-age, and whether the caller forced a refresh.
+*   - {@link Semaphore} — a counting semaphore bounding concurrent grabs.
+*   - {@link SingleFlight} — de-dupes concurrent captures for the same key and
+*     retains a SETTLED success for a short hold window so a mount burst collapses
+*     into one capture.
+*   - {@link raceForResult} — races a promise against a wait bound without
+*     cancelling the promise (the loser keeps running in the background).
+*/
+/**
+* Retain a SETTLED single-flight capture this long so a grid-mount burst of
+* `getSnapshot` calls (and a row of refresh buttons) collapses into ONE capture
+* instead of one dial per tile. Only success outcomes are held — a null/failed
+* capture expires immediately so a transiently-unreachable camera is retried on
+* the next call rather than pinned blank for the window.
+*/
+var COALESCE_MS = 4e3;
+/**
+* Stale-while-revalidate: when a cached frame exists but is past its max-age,
+* start the refresh and wait at most this long for it to land before returning
+* the STALE frame (the refresh keeps running and populates the cache for the
+* next poll). Keeps a grid mount painting instantly from cache.
+*/
+var SWR_STALE_WAIT_MS = 2500;
+/**
+* Cold path (no cached frame) or a forced refresh: wait up to this long for a
+* fresh capture. On a cold miss there is nothing to fall back to, so we block
+* (bounded) on the capture; on a forced refresh with a stale frame available we
+* still prefer a fresh one but cap the wait, falling back to stale on timeout.
+*/
+var SWR_COLD_WAIT_MS = 1e4;
+/**
+* Pure serve/refresh decision.
+*
+*   - fresh cache + !force            -> serve-cache
+*   - stale cache + !force            -> SWR: wait SWR_STALE_WAIT_MS, then stale
+*   - no cache   + !force             -> cold: wait SWR_COLD_WAIT_MS, no fallback
+*   - force (cache present or not)    -> prefer fresh: wait SWR_COLD_WAIT_MS,
+*                                       fall back to stale only if a frame exists
+*/
+function decideSnapshotServe(input) {
+	const { now, cachedAt, effectiveMaxAgeMs, force } = input;
+	const hasFrame = cachedAt !== null;
+	const fresh = hasFrame && now - cachedAt < effectiveMaxAgeMs;
+	if (!force && fresh) return { kind: "serve-cache" };
+	if (force) return {
+		kind: "await-refresh",
+		waitMs: SWR_COLD_WAIT_MS,
+		staleFallback: hasFrame
+	};
+	if (hasFrame) return {
+		kind: "await-refresh",
+		waitMs: SWR_STALE_WAIT_MS,
+		staleFallback: true
+	};
+	return {
+		kind: "await-refresh",
+		waitMs: SWR_COLD_WAIT_MS,
+		staleFallback: false
+	};
+}
+/**
+* A counting semaphore. `run` acquires a permit, awaits `fn`, and releases the
+* permit (even if `fn` throws), so at most `max` `fn`s run concurrently. Waiters
+* are served FIFO.
+*/
+var Semaphore = class {
+	available;
+	waiters = [];
+	constructor(max) {
+		if (!Number.isInteger(max) || max < 1) throw new Error(`Semaphore max must be a positive integer, got ${String(max)}`);
+		this.available = max;
+	}
+	async run(fn) {
+		const release = await this.acquire();
+		try {
+			return await fn();
+		} finally {
+			release();
+		}
+	}
+	async acquire() {
+		if (this.available > 0) {
+			this.available -= 1;
+			return this.makeReleaser();
+		}
+		await new Promise((resolve) => this.waiters.push(resolve));
+		return this.makeReleaser();
+	}
+	makeReleaser() {
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const next = this.waiters.shift();
+			if (next) {
+				next();
+				return;
+			}
+			this.available += 1;
+		};
+	}
+};
+/**
+* One in-flight capture per key. A settled SUCCESS is retained for `holdMs` so a
+* burst collapses into one capture; a settled failure/empty expires immediately
+* so the next caller retries. Concurrent callers ALWAYS join the running flight
+* regardless of eventual outcome.
+*/
+var Flight = class {
+	promise;
+	settledAt = null;
+	hold = false;
+	constructor(factory, now, holdWorthy) {
+		this.promise = (async () => {
+			try {
+				const value = await factory();
+				this.hold = holdWorthy(value);
+				return value;
+			} catch (err) {
+				this.hold = false;
+				throw err;
+			} finally {
+				this.settledAt = now();
+			}
+		})();
+	}
+};
+var SingleFlight = class {
+	holdMs;
+	holdWorthy;
+	now;
+	flights = /* @__PURE__ */ new Map();
+	/**
+	* @param holdMs      how long a settled hold-worthy result is reused
+	* @param holdWorthy  predicate deciding whether a settled value is worth holding
+	*                    (e.g. a successful capture with a real frame)
+	* @param now         clock injection for tests
+	*/
+	constructor(holdMs, holdWorthy, now = () => Date.now()) {
+		this.holdMs = holdMs;
+		this.holdWorthy = holdWorthy;
+		this.now = now;
+	}
+	run(key, factory) {
+		const existing = this.flights.get(key);
+		if (existing && this.isReusable(existing)) return existing.promise;
+		const flight = new Flight(factory, this.now, this.holdWorthy);
+		this.flights.set(key, flight);
+		return flight.promise;
+	}
+	/** Drop every held flight whose key starts with `prefix` (e.g. `"<deviceId>:"`). */
+	invalidatePrefix(prefix) {
+		for (const key of [...this.flights.keys()]) if (key.startsWith(prefix)) this.flights.delete(key);
+	}
+	clear() {
+		this.flights.clear();
+	}
+	isReusable(flight) {
+		if (flight.settledAt === null) return true;
+		if (!flight.hold) return false;
+		return this.now() - flight.settledAt < this.holdMs;
+	}
+};
+/**
+* Race `promise` against a `timeoutMs` bound WITHOUT cancelling it — on timeout
+* the promise keeps running (its result lands in the cache for the next poll).
+* Rejections propagate: if `promise` rejects before the timeout, this rejects.
+* The caller passes a promise that never rejects (a settled outcome union) when
+* background continuation must stay unhandled-safe.
+*/
+function raceForResult(promise, timeoutMs) {
+	let timer;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => resolve({ settled: false }), timeoutMs);
+	});
+	const settled = promise.then((value) => ({
+		settled: true,
+		value
+	}));
+	return Promise.race([settled, timeout]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+//#endregion
 //#region src/builtins/snapshot/snapshot.addon.ts
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
@@ -31,6 +226,16 @@ var BATTERY_DEFAULT_MAX_AGE_S = 3600;
 var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	cache = /* @__PURE__ */ new Map();
 	/**
+	* De-dupes concurrent captures per `${deviceId}:${streamId}` and holds a
+	* settled SUCCESS for COALESCE_MS so a grid-mount burst (and a row of refresh
+	* buttons) collapses into one capture instead of one dial per tile.
+	*/
+	captureFlight = new SingleFlight(COALESCE_MS, (outcome) => outcome.ok && outcome.image !== null);
+	/** Bounds simultaneous ffmpeg keyframe grabs (the wrapper path — common case). */
+	grabPool = new Semaphore(3);
+	/** Bounds simultaneous native (vendor HTTP/ONVIF) snapshot fetches. */
+	nativePool = new Semaphore(6);
+	/**
 	* Cached resolution of `pipelineOrchestrator.getIngestOwner` — SnapshotAddon
 	* has no per-request attach hook to resolve this fresh, so it's cached with
 	* a short TTL and invalidated on `onConfigChanged` (covers the common case
@@ -53,12 +258,14 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 				getDeviceSettingsContribution: (input) => this.buildDeviceSettingsContribution(input.deviceId),
 				getDeviceLiveContribution: async () => null,
 				applyDeviceSettingsPatch: (input) => this.saveDeviceSettingsPatch(input.deviceId, input.patch),
-				getStatus: async (input) => this.getStatus(input.deviceId)
+				getStatus: async (input) => this.getStatus(input.deviceId),
+				getSnapshotOverview: (input) => this.getSnapshotOverview(input)
 			}
 		}];
 	}
 	async onShutdown() {
 		this.cache.clear();
+		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
 	/**
@@ -91,7 +298,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}] });
 	}
 	async getSnapshot(input) {
-		const { deviceId, force } = input;
+		const { deviceId } = input;
+		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
 		const deviceName = meta?.name;
 		const isBatteryDevice = meta?.isBattery ?? false;
@@ -110,8 +318,14 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		});
 		const defaultMaxAgeS = isBatteryDevice ? BATTERY_DEFAULT_MAX_AGE_S : NON_BATTERY_DEFAULT_MAX_AGE_S;
 		const effectiveMaxAgeMs = (typeof prefs.snapshotMaxAgeS === "number" && prefs.snapshotMaxAgeS >= 0 ? prefs.snapshotMaxAgeS : defaultMaxAgeS) * 1e3;
-		if (!force && hit && now - hit.ts < effectiveMaxAgeMs) {
-			if (prefs.snapshotDebug) log.debug("snapshot: cache hit", {
+		const decision = decideSnapshotServe({
+			now,
+			cachedAt: hit?.ts ?? null,
+			effectiveMaxAgeMs,
+			force
+		});
+		if (decision.kind === "serve-cache") {
+			if (prefs.snapshotDebug && hit) log.debug("snapshot: cache hit", {
 				tags: { deviceId },
 				meta: {
 					ageMs: now - hit.ts,
@@ -119,21 +333,97 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 					isBattery: isBatteryDevice
 				}
 			});
+			return hit ? hit.data : null;
+		}
+		const flightKey = `${deviceId}:${effectiveStreamId ?? "auto"}`;
+		const flight = this.captureFlight.run(flightKey, () => this.captureFresh({
+			deviceId,
+			input,
+			effectiveStreamId,
+			isBatteryDevice,
+			log
+		}));
+		flight.catch(() => void 0);
+		const raced = await raceForResult(flight, decision.waitMs);
+		if (raced.settled) return this.resolveOutcome(raced.value, deviceId, hit, log);
+		if (decision.staleFallback && hit) {
+			if (prefs.snapshotDebug) log.debug("snapshot: SWR — returning stale frame; refresh continues in background", {
+				tags: { deviceId },
+				meta: {
+					ageMs: now - hit.ts,
+					waitMs: decision.waitMs
+				}
+			});
+			return hit.data;
+		}
+		return null;
+	}
+	/**
+	* Map a settled capture outcome onto the response, preserving the legacy
+	* semantics: a fresh frame wins; a soft miss (native null + broker null)
+	* falls back to stale cache (or null); a HARD native error with no frame
+	* and no cache propagates.
+	*/
+	resolveOutcome(outcome, deviceId, hit, log) {
+		if (outcome.ok) {
+			if (outcome.image) return outcome.image;
+			if (hit) {
+				const ageMs = Date.now() - hit.ts;
+				if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
+					tags: { deviceId },
+					meta: { ageMs }
+				});
+				return hit.data;
+			}
+			return null;
+		}
+		if (hit) {
+			const ageMs = Date.now() - hit.ts;
+			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: native failed — serving stale cache", {
+				tags: { deviceId },
+				meta: { ageMs }
+			});
 			return hit.data;
 		}
+		throw outcome.error;
+	}
+	/**
+	* Run the capture ladder ONCE for a device: native provider first, then the
+	* stream-broker ffmpeg fallback. Never rejects — resolves a {@link
+	* CaptureOutcome}. On a produced frame it populates the cache (so a
+	* background SWR refresh lands for the next poll) and returns it. A hard
+	* native error with no broker frame resolves `{ ok:false }` so the caller
+	* can surface it; a soft miss resolves `{ ok:true, image:null }`.
+	*
+	* TODO(decoded-frame fast path): for a device whose detection pipeline is
+	* already decoding (the always-on subscription, see docs/design/decode-path.md),
+	* the freshest decoded frame is already in the shared-memory ring — a single
+	* JPEG encode of the latest FrameHandle would cost zero dials and beat the
+	* ffmpeg grab for the wrapper fleet. Slotting it as native -> latest-decoded
+	* -> broker needs cross-addon plumbing not cheaply reachable from the hub
+	* builtin today: frames are session-scoped (decoder `pullHandles`/`getFrame`
+	* need the device's active session id) and raw-pixel (need a JPEG encoder the
+	* builtin lacks). Deferred as its own slice.
+	*/
+	async captureFresh(args) {
+		const { deviceId, input, effectiveStreamId, isBatteryDevice, log } = args;
+		const now = Date.now();
 		let nativeError = null;
 		let nativeAbsent = false;
 		try {
 			const native = this.ctx.getNativeProvider(require_dist.snapshotCapability, deviceId);
 			if (native) {
-				const result = await native.getSnapshot(input);
+				const result = await this.nativePool.run(() => native.getSnapshot(input));
 				if (result) {
 					this.cache.set(deviceId, {
 						data: result,
 						ts: now,
 						streamId: effectiveStreamId ?? null
 					});
-					return result;
+					return {
+						ok: true,
+						image: result
+					};
 				}
 				log.debug("native snapshot returned null — falling through to broker", { tags: { deviceId } });
 			} else {
@@ -164,7 +454,10 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 					ts: now,
 					streamId: effectiveStreamId ?? null
 				});
-				return fallback;
+				return {
+					ok: true,
+					image: fallback
+				};
 			}
 		} catch (err) {
 			log.warn("stream-broker snapshot fallback failed", {
@@ -173,25 +466,16 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			});
 		}
 		else log.debug("snapshot: skipping broker fallback — battery device with absent native and no streaming broker", { tags: { deviceId } });
-		if (hit) {
-			const ageMs = now - hit.ts;
-			if (ageMs > this.config.staleTtlMs) log.warn("snapshot: all live paths failed — serving stale cache", {
-				tags: { deviceId },
-				meta: { ageMs }
-			});
-			return hit.data;
-		}
-		if (nativeError) throw nativeError;
-		if (nativeAbsent) return null;
-		return null;
+		if (nativeError) return {
+			ok: false,
+			error: nativeError
+		};
+		return {
+			ok: true,
+			image: null
+		};
 	}
 	/**
-	* Tell apart "native provider isn't registered for this device" from
-	* "native provider ran and threw a real error". The former is the steady
-	* state for cameras without a vendor snapshot endpoint and should not
-	* propagate as a 500; the latter should.
-	*/
-	/**
 	* Pull one JPEG from the device's stream-broker RTSP restream using
 	* a short-lived ffmpeg invocation.
 	*
@@ -296,12 +580,12 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	async runGrabWithResumeRetry(url, deviceId) {
 		let buf;
 		try {
-			buf = await runFfmpegFrameGrab(url, 15e3);
+			buf = await this.grabPool.run(() => runFfmpegFrameGrab(url, 15e3));
 		} catch (err) {
 			if (isBrokerColdError(require_dist.errMsg(err))) {
 				this.ctx.logger.debug("grabFrame: broker-resume race — retrying in 1500ms", { tags: { deviceId } });
 				await new Promise((r) => setTimeout(r, 1500));
-				buf = await runFfmpegFrameGrab(url, 15e3);
+				buf = await this.grabPool.run(() => runFfmpegFrameGrab(url, 15e3));
 			} else throw err;
 		}
 		if (buf.length === 0) return null;
@@ -312,6 +596,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	}
 	async invalidateCache(input) {
 		this.cache.delete(input.deviceId);
+		this.captureFlight.invalidatePrefix(`${input.deviceId}:`);
 	}
 	/**
 	* Non-throwing probe of the device's battery cap. Returns true only
@@ -351,6 +636,30 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 	}
 	/**
+	* Cache-only batch overview — O(n) over the in-memory cache, NEVER triggers
+	* a capture. Lets a grid skip requesting images for devices that never
+	* produced a frame, and hands each an ETag for conditional image fetches.
+	*/
+	getSnapshotOverview(input) {
+		const now = Date.now();
+		const rows = input.deviceIds.map((deviceId) => {
+			const hit = this.cache.get(deviceId);
+			if (!hit) return {
+				deviceId,
+				lastCapturedAt: null,
+				cacheAgeMs: null,
+				etag: null
+			};
+			return {
+				deviceId,
+				lastCapturedAt: hit.ts,
+				cacheAgeMs: now - hit.ts,
+				etag: `"${deviceId}-${hit.ts}"`
+			};
+		});
+		return Promise.resolve(rows);
+	}
+	/**
 	* Diagnostic status for the `status` auto-injected cap method. Reports
 	* the cache bookkeeping for this device — when the last snapshot was
 	* captured, how stale the cached image is, its size, and which stream
@@ -507,6 +816,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		}
 		await this.ctx.settings.writeDeviceStore(deviceId, next);
 		this.cache.delete(deviceId);
+		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 		return { success: true };
 	}
 };