@camstack/system 1.2.38 → 1.2.40

package/dist/builtins/snapshot/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CFinlH7b.js");
+const require_dist = require("../../dist-Cj0LAuXi.js");
 let node_child_process = require("node:child_process");
 //#region src/builtins/snapshot/snapshot-coalescing.ts
 /**
@@ -202,6 +202,32 @@ function raceForResult(promise, timeoutMs) {
 //#endregion
 //#region src/builtins/snapshot/snapshot-media-handler.ts
 /**
+* The widths a thumbnail may be served at.
+*
+* A ladder, not a free integer: the width is a cache key AND an ffmpeg run, so
+* honouring `?w=` verbatim would let any caller mint unbounded work and
+* unbounded memory. Twelve tiles measured at 181–240 px collapse onto one
+* variant instead of twelve.
+*
+* Rungs are chosen for the card sizes the viewer actually renders (180–390 px)
+* with headroom for a 2× device pixel ratio.
+*/
+var SNAPSHOT_WIDTH_LADDER = [
+	160,
+	240,
+	320,
+	480,
+	640,
+	960
+];
+/** Snap UP to the next rung — never below what was asked, so the client is not
+*  handed an image it has to upscale. Above the ladder, the largest rung: the
+*  point is to stop serving the 4K original. */
+function snapSnapshotWidth(requested) {
+	for (const rung of SNAPSHOT_WIDTH_LADDER) if (requested <= rung) return rung;
+	return SNAPSHOT_WIDTH_LADDER[SNAPSHOT_WIDTH_LADDER.length - 1] ?? requested;
+}
+/**
 * Parse the handler-relative path (`/<deviceId>.jpg?query`) into a request.
 * Returns null for a malformed / nested / non-numeric id so the handler answers
 * 404 without ever reaching `getMedia`.
@@ -220,13 +246,33 @@ function parseSnapshotMediaRequest(url) {
 	const rawStream = params.get("streamId");
 	const streamId = rawStream !== null && rawStream.length > 0 ? rawStream : void 0;
 	const rawForce = params.get("force");
+	const force = rawForce === "1" || rawForce === "true";
+	const rawWidth = params.get("w");
 	return {
 		deviceId,
 		streamId,
-		force: rawForce === "1" || rawForce === "true"
+		force,
+		width: rawWidth !== null && /^\d+$/.test(rawWidth) && Number.parseInt(rawWidth, 10) > 0 ? snapSnapshotWidth(Number.parseInt(rawWidth, 10)) : void 0
 	};
 }
 /**
+* The response's entity tag.
+*
+* It has to identify the VARIANT, not just the frame: the same capture can now
+* be served at several widths and from several streams, and a plain
+* `"<device>-<capturedAt>"` would let a client that fetched `?w=320` receive a
+* 304 for `?w=960` and render the small image at full size. The base form is
+* unchanged for a plain request, so the identity
+* `snapshot.getSnapshotOverview` advertises still matches the frame nobody
+* asked to resize.
+*/
+function snapshotEtag(request, capturedAt) {
+	const parts = [`${String(request.deviceId)}-${String(capturedAt)}`];
+	if (request.streamId !== void 0) parts.push(`s${request.streamId}`);
+	if (request.width !== void 0) parts.push(`w${String(request.width)}`);
+	return `"${parts.join("-")}"`;
+}
+/**
 * Create a data-plane handler that serves per-device snapshots as JPEG images.
 * `deps.getMedia` is called once per request; null → 404, throw → 500. A
 * conditional GET with a matching `If-None-Match` produces a 304.
@@ -244,7 +290,7 @@ function createSnapshotMediaHandler(deps) {
 		}
 		let media;
 		try {
-			media = await deps.getMedia(parsed.deviceId, parsed.streamId, parsed.force);
+			media = await deps.getMedia(parsed.deviceId, parsed.streamId, parsed.force, parsed.width);
 		} catch {
 			const body = "Internal server error";
 			res.writeHead(500, {
@@ -259,7 +305,7 @@ function createSnapshotMediaHandler(deps) {
 			res.writeHead(404).end();
 			return;
 		}
-		const etag = `"${parsed.deviceId}-${media.capturedAt}"`;
+		const etag = snapshotEtag(parsed, media.capturedAt);
 		const cacheControl = `private, max-age=${Math.max(0, Math.floor(media.maxAgeS))}`;
 		if (req.headers["if-none-match"] === etag) {
 			res.writeHead(304, {
@@ -279,6 +325,182 @@ function createSnapshotMediaHandler(deps) {
 	};
 }
 //#endregion
+//#region src/builtins/snapshot/snapshot-cache.ts
+/** A request with no explicit stream is its OWN entry, not a wildcard: the
+*  per-device preference decides what it captures, and conflating it with an
+*  explicit request is how the original bug read. */
+var AUTO = "auto";
+function keyOf(deviceId, streamId) {
+	return `${deviceId}:${streamId ?? AUTO}`;
+}
+var SnapshotCache = class {
+	byKey = /* @__PURE__ */ new Map();
+	/** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
+	keysByDevice = /* @__PURE__ */ new Map();
+	get(deviceId, streamId) {
+		return this.byKey.get(keyOf(deviceId, streamId));
+	}
+	set(deviceId, streamId, entry) {
+		const key = keyOf(deviceId, streamId);
+		this.byKey.set(key, entry);
+		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
+		keys.add(key);
+		this.keysByDevice.set(deviceId, keys);
+	}
+	/** The newest entry for a device, whichever stream produced it. */
+	latest(deviceId) {
+		let newest;
+		for (const key of this.keysByDevice.get(deviceId) ?? []) {
+			const entry = this.byKey.get(key);
+			if (entry !== void 0 && (newest === void 0 || entry.ts > newest.ts)) newest = entry;
+		}
+		return newest;
+	}
+	/**
+	* Drop every stream of one device.
+	*
+	* Device-wide on purpose: a settings change or an operator refresh
+	* invalidates the CAMERA, and leaving a sibling entry behind would keep
+	* serving the pre-change frame from the other key.
+	*/
+	deleteDevice(deviceId) {
+		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		this.keysByDevice.delete(deviceId);
+	}
+	clear() {
+		this.byKey.clear();
+		this.keysByDevice.clear();
+	}
+};
+//#endregion
+//#region src/builtins/snapshot/snapshot-resize.ts
+/**
+* Downscaling a captured frame to a card-sized thumbnail.
+*
+* Applied AFTER capture rather than during it, and that is deliberate: the two
+* capture paths (the vendor's native HTTP snapshot and the ffmpeg keyframe
+* grab) produce a JPEG by different routes, and only one of them has an
+* ffmpeg filter chain to hook into. Resizing the finished bytes gives both the
+* same behaviour with one implementation.
+*
+* The cost is one ffmpeg run per (device, stream, width) per cache window — not
+* one per request. A camera whose card is on screen pays it once every
+* `snapshotMaxAgeS`.
+*
+* `ffmpeg` is already this addon's dependency (the keyframe grab shells out to
+* it), so this adds no new one.
+*/
+var RESIZE_TIMEOUT_MS = 1e4;
+/**
+* Scale to `width`, preserving aspect ratio (`-2` keeps the height even, which
+* mjpeg requires).
+*
+* Rejects on a non-zero exit or a timeout. It NEVER falls back to the original
+* silently — a caller that quietly served the 4K frame when the resize failed
+* would reproduce exactly the bug this whole change exists to fix, and nobody
+* would see it. The caller decides, and logs.
+*/
+function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
+	return new Promise((resolve, reject) => {
+		const child = (0, node_child_process.spawn)("ffmpeg", [
+			"-loglevel",
+			"error",
+			"-f",
+			"image2pipe",
+			"-i",
+			"pipe:0",
+			"-vf",
+			`scale=${String(width)}:-2:flags=bilinear`,
+			"-frames:v",
+			"1",
+			"-q:v",
+			"5",
+			"-f",
+			"image2pipe",
+			"-vcodec",
+			"mjpeg",
+			"pipe:1"
+		], { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		const out = [];
+		let err = "";
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			child.kill("SIGKILL");
+			reject(/* @__PURE__ */ new Error(`snapshot resize timed out after ${String(timeoutMs)}ms`));
+		}, timeoutMs);
+		child.stdout.on("data", (chunk) => out.push(chunk));
+		child.stderr.on("data", (chunk) => {
+			err += chunk.toString();
+		});
+		child.on("error", (e) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(e);
+		});
+		child.on("close", (code) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			const buf = Buffer.concat(out);
+			if (code !== 0 || buf.length === 0) {
+				reject(/* @__PURE__ */ new Error(`snapshot resize failed (code ${String(code)}): ${err.trim() || "no output"}`));
+				return;
+			}
+			resolve(buf);
+		});
+		child.stdin.on("error", () => {});
+		child.stdin.end(bytes);
+	});
+}
+/**
+* Resized frames, keyed by (device, stream, width) AND validated against the
+* source frame's timestamp.
+*
+* The timestamp is the whole correctness argument: a variant outlives nothing.
+* When the underlying frame is recaptured its `capturedAt` moves, every variant
+* derived from the old one stops matching, and the next request re-derives.
+* Without that check a card would keep showing a thumbnail of a frame the
+* full-size view had already replaced.
+*/
+var SnapshotVariantCache = class SnapshotVariantCache {
+	byKey = /* @__PURE__ */ new Map();
+	keysByDevice = /* @__PURE__ */ new Map();
+	static key(deviceId, streamId, width) {
+		return `${deviceId}:${streamId ?? "auto"}:${width}`;
+	}
+	/** The variant for this exact frame, or undefined when it is missing or was
+	*  derived from an older capture. */
+	get(deviceId, streamId, width, sourceTs) {
+		const entry = this.byKey.get(SnapshotVariantCache.key(deviceId, streamId, width));
+		return entry !== void 0 && entry.sourceTs === sourceTs ? entry.bytes : void 0;
+	}
+	set(deviceId, streamId, width, sourceTs, bytes) {
+		const key = SnapshotVariantCache.key(deviceId, streamId, width);
+		this.byKey.set(key, {
+			bytes,
+			sourceTs
+		});
+		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
+		keys.add(key);
+		this.keysByDevice.set(deviceId, keys);
+	}
+	deleteDevice(deviceId) {
+		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		this.keysByDevice.delete(deviceId);
+	}
+	clear() {
+		this.byKey.clear();
+		this.keysByDevice.clear();
+	}
+};
+//#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;
@@ -314,7 +536,10 @@ function effectiveMaxAgeS(prefs, isBattery) {
 * publishes stream endpoints.
 */
 var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
-	cache = /* @__PURE__ */ new Map();
+	cache = new SnapshotCache();
+	/** Card-sized derivatives of the frames above, keyed by width and validated
+	*  against the source frame's timestamp. */
+	variants = new SnapshotVariantCache();
 	/**
 	* 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
@@ -372,7 +597,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	* base64 path.
 	*/
 	async serveMediaDataPlane() {
-		const handler = createSnapshotMediaHandler({ getMedia: (deviceId, streamId, force) => this.resolveSnapshotMedia(deviceId, streamId, force) });
+		const handler = createSnapshotMediaHandler({ getMedia: (deviceId, streamId, force, width) => this.resolveSnapshotMedia(deviceId, streamId, force, width) });
 		try {
 			this.mediaDataPlane = await this.ctx.dataPlane?.serve({
 				prefix: "media",
@@ -393,29 +618,67 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	* the cache entry (matching the ETag `getSnapshotOverview` advertises) and the
 	* effective per-device `maxAgeS` for `Cache-Control`. Null → 404.
 	*/
-	async resolveSnapshotMedia(deviceId, streamId, force) {
+	async resolveSnapshotMedia(deviceId, streamId, force, width) {
 		const image = await this.getSnapshot({
 			deviceId,
 			...streamId !== void 0 ? { streamId } : {},
 			force
 		});
 		if (!image) return null;
-		const capturedAt = this.cache.get(deviceId)?.ts ?? Date.now();
+		const capturedAt = this.cache.get(deviceId, streamId)?.ts ?? Date.now();
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
 		const isBattery = (await this.lookupDeviceMeta(deviceId))?.isBattery ?? false;
 		return {
-			bytes: Buffer.from(image.base64, "base64"),
+			bytes: width === void 0 ? Buffer.from(image.base64, "base64") : await this.thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs),
 			contentType: image.contentType,
 			capturedAt,
 			maxAgeS: effectiveMaxAgeS(prefs, isBattery)
 		};
 	}
+	/**
+	* The frame at a card-sized width, derived once per (device, stream, width)
+	* per capture.
+	*
+	* A failed resize falls back to the FULL frame — a visible card beats a
+	* broken one — but never silently: the card would otherwise keep costing a
+	* megabyte with nothing anywhere saying why, which is the shape of the bug
+	* this whole change came from.
+	*/
+	async thumbnailBytes(deviceId, streamId, width, capturedAt, image, prefs) {
+		const cached = this.variants.get(deviceId, streamId, width, capturedAt);
+		if (cached !== void 0) return cached;
+		const full = Buffer.from(image.base64, "base64");
+		try {
+			const resized = await resizeJpeg(full, width);
+			this.variants.set(deviceId, streamId, width, capturedAt, resized);
+			if (prefs.snapshotDebug) this.ctx.logger.info("snapshot: thumbnail derived", {
+				tags: { deviceId },
+				meta: {
+					width,
+					fullBytes: full.length,
+					thumbBytes: resized.length
+				}
+			});
+			return resized;
+		} catch (err) {
+			this.ctx.logger.warn("snapshot: resize failed — serving the full frame", {
+				tags: { deviceId },
+				meta: {
+					width,
+					bytes: full.length,
+					error: require_dist.errMsg(err)
+				}
+			});
+			return full;
+		}
+	}
 	async onShutdown() {
 		if (this.mediaDataPlane) {
 			await this.mediaDataPlane.dispose().catch(() => void 0);
 			this.mediaDataPlane = null;
 		}
 		this.cache.clear();
+		this.variants.clear();
 		this.captureFlight.clear();
 		this.ownerCache = null;
 	}
@@ -459,7 +722,6 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			...deviceName ? { deviceName } : {}
 		});
 		const now = Date.now();
-		const hit = this.cache.get(deviceId);
 		const prefs = await this.readDeviceSettings(deviceId).catch(() => ({}));
 		const rawPref = prefs.snapshotStreamId;
 		const effectiveStreamId = input.streamId ?? (rawPref && rawPref !== "auto" ? rawPref : void 0);
@@ -467,6 +729,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			tags: { deviceId },
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
+		const hit = this.cache.get(deviceId, effectiveStreamId);
 		const effectiveMaxAgeMs = effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3;
 		const decision = decideSnapshotServe({
 			now,
@@ -575,7 +838,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			if (native) {
 				const result = await this.nativePool.run(() => native.getSnapshot(input));
 				if (result) {
-					this.cache.set(deviceId, {
+					this.cache.set(deviceId, effectiveStreamId, {
 						data: result,
 						ts: now,
 						streamId: effectiveStreamId ?? null
@@ -609,7 +872,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		if (!(isBatteryDevice && nativeAbsent && !await this.hasStreamingBrokerForDevice(deviceId))) try {
 			const fallback = await this.grabFrameFromBroker(deviceId, effectiveStreamId);
 			if (fallback) {
-				this.cache.set(deviceId, {
+				this.cache.set(deviceId, effectiveStreamId, {
 					data: fallback,
 					ts: now,
 					streamId: effectiveStreamId ?? null
@@ -755,7 +1018,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		};
 	}
 	async invalidateCache(input) {
-		this.cache.delete(input.deviceId);
+		this.cache.deleteDevice(input.deviceId);
+		this.variants.deleteDevice(input.deviceId);
 		this.captureFlight.invalidatePrefix(`${input.deviceId}:`);
 	}
 	/**
@@ -829,7 +1093,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	getSnapshotOverview(input) {
 		const now = Date.now();
 		const rows = input.deviceIds.map((deviceId) => {
-			const hit = this.cache.get(deviceId);
+			const hit = this.cache.latest(deviceId);
 			if (!hit) return {
 				deviceId,
 				lastCapturedAt: null,
@@ -853,7 +1117,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	* (cache miss) since the addon started.
 	*/
 	async getStatus(deviceId) {
-		const hit = this.cache.get(deviceId);
+		const hit = this.cache.latest(deviceId);
 		if (!hit) return null;
 		return {
 			lastCapturedAt: hit.ts,
@@ -1001,7 +1265,8 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			else delete next["snapshotMaxAgeS"];
 		}
 		await this.ctx.settings.writeDeviceStore(deviceId, next);
-		this.cache.delete(deviceId);
+		this.cache.deleteDevice(deviceId);
+		this.variants.deleteDevice(deviceId);
 		this.captureFlight.invalidatePrefix(`${deviceId}:`);
 		return { success: true };
 	}