@camstack/system 1.2.102 → 1.2.103

package/dist/builtins/snapshot/index.mjs

@@ -1,4 +1,4 @@
-import { Ct as DeviceFeature, Gt as EventCategory, M as deriveBatteryPresence, Rt as nodePin, T as batteryCapability, Tt as DeviceType, i as BatteryStatusSchema, mt as streamQualityLabel, ut as snapshotCapability, vt as errMsg, w as bareAddonId, yt as BaseAddon } from "../../dist-3wh5LCad.mjs";
+import { Ct as DeviceFeature, Gt as EventCategory, M as deriveBatteryPresence, Rt as nodePin, T as batteryCapability, Tt as DeviceType, i as BatteryStatusSchema, mt as streamQualityLabel, ut as snapshotCapability, vt as errMsg, w as bareAddonId, yt as BaseAddon } from "../../dist-DHKXob1m.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { signExpiringUrl, verifyExpiringUrl } from "@camstack/types/node";
@@ -16,25 +16,94 @@ var SnapshotCache = class {
 	byKey = /* @__PURE__ */ new Map();
 	/** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
 	keysByDevice = /* @__PURE__ */ new Map();
+	maxBytes;
+	idleTtlMs;
+	now;
+	onEvict;
+	totalBytes = 0;
+	constructor(options = {}) {
+		this.maxBytes = options.maxBytes ?? 67108864;
+		this.idleTtlMs = options.idleTtlMs ?? 36e5;
+		this.now = options.now ?? (() => Date.now());
+		this.onEvict = options.onEvict;
+	}
 	get(deviceId, streamId) {
-		return this.byKey.get(keyOf(deviceId, streamId));
+		return this.read(keyOf(deviceId, streamId));
 	}
 	set(deviceId, streamId, entry) {
 		const key = keyOf(deviceId, streamId);
-		this.byKey.set(key, entry);
+		this.forget(key);
+		this.byKey.set(key, {
+			entry,
+			deviceId,
+			bytes: entry.data.base64.length,
+			lastAccessAt: this.now()
+		});
+		this.totalBytes += entry.data.base64.length;
 		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
 		keys.add(key);
 		this.keysByDevice.set(deviceId, keys);
+		this.enforceBudget(key);
 	}
 	/** 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);
+		for (const key of [...this.keysByDevice.get(deviceId) ?? []]) {
+			const entry = this.read(key);
 			if (entry !== void 0 && (newest === void 0 || entry.ts > newest.ts)) newest = entry;
 		}
 		return newest;
 	}
+	/** Base64 bytes currently retained. The number the budget is enforced on. */
+	sizeBytes() {
+		return this.totalBytes;
+	}
+	/** Entries currently retained. */
+	entryCount() {
+		return this.byKey.size;
+	}
+	/** Read through the idle timeout: an entry nobody has touched inside
+	*  `idleTtlMs` is dropped here rather than on a sweep, so the cost is paid by
+	*  the caller that proves it was not wanted. */
+	read(key) {
+		const slot = this.byKey.get(key);
+		if (slot === void 0) return void 0;
+		const at = this.now();
+		if (at - slot.lastAccessAt > this.idleTtlMs) {
+			this.evict(key, "idle");
+			return;
+		}
+		slot.lastAccessAt = at;
+		return slot.entry;
+	}
+	/** Evict least-recently-ACCESSED first until the budget holds. `protectedKey`
+	*  is the entry just written — evicting it would make `set` a no-op. */
+	enforceBudget(protectedKey) {
+		if (this.totalBytes <= this.maxBytes) return;
+		const coldestFirst = [...this.byKey.entries()].filter(([key]) => key !== protectedKey).toSorted((a, b) => a[1].lastAccessAt - b[1].lastAccessAt);
+		for (const [key] of coldestFirst) {
+			if (this.totalBytes <= this.maxBytes) return;
+			this.evict(key, "budget");
+		}
+	}
+	evict(key, reason) {
+		const slot = this.byKey.get(key);
+		if (slot === void 0) return;
+		this.forget(key);
+		this.onEvict?.(slot.deviceId, slot.entry.streamId, reason);
+	}
+	/** Remove a key and everything that indexes or accounts for it. */
+	forget(key) {
+		const slot = this.byKey.get(key);
+		if (slot === void 0) return;
+		this.totalBytes -= slot.bytes;
+		this.byKey.delete(key);
+		const keys = this.keysByDevice.get(slot.deviceId);
+		if (keys !== void 0) {
+			keys.delete(key);
+			if (keys.size === 0) this.keysByDevice.delete(slot.deviceId);
+		}
+	}
 	/**
 	* Drop every stream of one device.
 	*
@@ -43,12 +112,13 @@ var SnapshotCache = class {
 	* serving the pre-change frame from the other key.
 	*/
 	deleteDevice(deviceId) {
-		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		for (const key of [...this.keysByDevice.get(deviceId) ?? []]) this.forget(key);
 		this.keysByDevice.delete(deviceId);
 	}
 	clear() {
 		this.byKey.clear();
 		this.keysByDevice.clear();
+		this.totalBytes = 0;
 	}
 };
 //#endregion
@@ -753,45 +823,89 @@ function resizeJpeg(bytes, width, timeoutMs = RESIZE_TIMEOUT_MS) {
 		if (timer !== void 0) clearTimeout(timer);
 	});
 }
-/**
-* Resized frames, keyed by (device, stream, width, state treatment) 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();
+	maxBytes;
+	now;
+	totalBytes = 0;
+	constructor(options = {}) {
+		this.maxBytes = options.maxBytes ?? 16777216;
+		this.now = options.now ?? (() => Date.now());
+	}
 	static key(deviceId, streamId, width, variantKey) {
 		return `${deviceId}:${streamId ?? "auto"}:${width}:${variantKey ?? "raw"}`;
 	}
 	/** The variant for this exact frame, or undefined when it is missing or was
-	*  derived from an older capture. */
+	*  derived from an older capture.
+	*
+	*  A superseded variant is DELETED here, not merely reported missing. It used
+	*  to be left in the map: unreachable by every future read (its `sourceTs` can
+	*  never match again) and removed by nothing, so every recapture added a dead
+	*  key. Returning `undefined` while retaining the bytes is the leak. */
 	get(deviceId, streamId, width, sourceTs, variantKey) {
-		const entry = this.byKey.get(SnapshotVariantCache.key(deviceId, streamId, width, variantKey));
-		return entry !== void 0 && entry.sourceTs === sourceTs ? entry.bytes : void 0;
+		const key = SnapshotVariantCache.key(deviceId, streamId, width, variantKey);
+		const slot = this.byKey.get(key);
+		if (slot === void 0) return void 0;
+		if (slot.sourceTs !== sourceTs) {
+			this.forget(key);
+			return;
+		}
+		slot.lastAccessAt = this.now();
+		return slot.bytes;
 	}
 	set(deviceId, streamId, width, sourceTs, bytes, variantKey) {
 		const key = SnapshotVariantCache.key(deviceId, streamId, width, variantKey);
+		this.forget(key);
 		this.byKey.set(key, {
 			bytes,
-			sourceTs
+			sourceTs,
+			deviceId,
+			lastAccessAt: this.now()
 		});
+		this.totalBytes += bytes.byteLength;
 		const keys = this.keysByDevice.get(deviceId) ?? /* @__PURE__ */ new Set();
 		keys.add(key);
 		this.keysByDevice.set(deviceId, keys);
+		this.enforceBudget(key);
+	}
+	/** Variant bytes currently retained. */
+	sizeBytes() {
+		return this.totalBytes;
+	}
+	/** Variants currently retained — including any that are no longer readable.
+	*  The number that used to only ever go up. */
+	entryCount() {
+		return this.byKey.size;
+	}
+	/** Evict least-recently-accessed first until the budget holds. */
+	enforceBudget(protectedKey) {
+		if (this.totalBytes <= this.maxBytes) return;
+		const coldestFirst = [...this.byKey.entries()].filter(([key]) => key !== protectedKey).toSorted((a, b) => a[1].lastAccessAt - b[1].lastAccessAt);
+		for (const [key] of coldestFirst) {
+			if (this.totalBytes <= this.maxBytes) return;
+			this.forget(key);
+		}
+	}
+	forget(key) {
+		const slot = this.byKey.get(key);
+		if (slot === void 0) return;
+		this.totalBytes -= slot.bytes.byteLength;
+		this.byKey.delete(key);
+		const keys = this.keysByDevice.get(slot.deviceId);
+		if (keys !== void 0) {
+			keys.delete(key);
+			if (keys.size === 0) this.keysByDevice.delete(slot.deviceId);
+		}
 	}
 	deleteDevice(deviceId) {
-		for (const key of this.keysByDevice.get(deviceId) ?? []) this.byKey.delete(key);
+		for (const key of [...this.keysByDevice.get(deviceId) ?? []]) this.forget(key);
 		this.keysByDevice.delete(deviceId);
 	}
 	clear() {
 		this.byKey.clear();
 		this.keysByDevice.clear();
+		this.totalBytes = 0;
 	}
 };
 //#endregion
@@ -902,7 +1016,21 @@ function effectiveMaxAgeS(prefs, isBattery) {
 * publishes stream endpoints.
 */
 var SnapshotAddon = class SnapshotAddon extends BaseAddon {
-	cache = new SnapshotCache();
+	/**
+	* The frame cache. Bounded by a byte budget + an idle timeout — it used to be
+	* unbounded in both. Every eviction is logged with the device tag: a frame
+	* that silently left the cache is the reason a later capture had to happen,
+	* and per-camera is the only way that question is ever asked.
+	*/
+	cache = new SnapshotCache({ onEvict: (deviceId, streamId, reason) => {
+		this.ctx.logger.debug("snapshot cache evicted", {
+			tags: { deviceId },
+			meta: {
+				stream: streamId ?? "auto",
+				reason
+			}
+		});
+	} });
 	/** Card-sized derivatives of the frames above, keyed by width and validated
 	*  against the source frame's timestamp. */
 	variants = new SnapshotVariantCache();

package/dist/builtins/snapshot/snapshot-cache.d.ts

@@ -25,14 +25,77 @@ export interface SnapshotCacheEntry {
     /** Stream id resolved at capture time — 'high' | 'mid' | 'low' | custom | null. */
     readonly streamId: string | null;
 }
+/**
+ * Byte budget across every cached frame.
+ *
+ * The cache shipped with NO bound of any kind: no TTL, no LRU, no size cap. It
+ * holds base64 JPEG payloads — a 4K main-stream frame is ~1.6 MB as base64 —
+ * keyed by (device, stream), so the ceiling was "every camera × every stream it
+ * was ever asked for", which is not a ceiling.
+ *
+ * 64 MiB is roughly 40 main-stream frames, comfortably above the live 27-camera
+ * roster's working set (the whole `snapshot` runner measures 185 MB RSS, of
+ * which the node baseline is ~130 MB), so nothing an operator does today starts
+ * evicting. It exists so a roster that grows, or a device that gets probed on
+ * many stream ids, cannot walk this structure into the OOM.
+ */
+export declare const SNAPSHOT_CACHE_MAX_BYTES: number;
+/**
+ * Drop an entry nobody has READ for this long.
+ *
+ * Deliberately an IDLE timeout and not a capture-age one. Capture age is
+ * already governed per device by `snapshotMaxAgeS` (default 15s, but one HOUR
+ * for battery cameras), so a TTL on age would either fight those rules or have
+ * to sit above the largest of them and bound nothing. "Nobody has looked at
+ * this in an hour" is orthogonal to freshness and is the actual condition under
+ * which the bytes are dead weight — a removed camera, an unreachable one, a
+ * stream id probed once by a debug view.
+ */
+export declare const SNAPSHOT_CACHE_IDLE_TTL_MS = 3600000;
+/** Why an entry was dropped. `budget` = the byte ceiling; `idle` = unread for
+ *  {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
+export type SnapshotCacheEvictReason = 'budget' | 'idle';
+/** Notified for every eviction so the owner can put it on the record with the
+ *  device tag. A cached frame that vanishes is the explanation for a later
+ *  capture that did not have to happen; silence reads as "never happened". */
+export type SnapshotCacheEvictListener = (deviceId: number, streamId: string | null, reason: SnapshotCacheEvictReason) => void;
+export interface SnapshotCacheOptions {
+    /** Total base64 bytes held across all entries. Default {@link SNAPSHOT_CACHE_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Idle timeout. Default {@link SNAPSHOT_CACHE_IDLE_TTL_MS}. */
+    readonly idleTtlMs?: number;
+    /** Injected clock — the bounds must be testable without waiting an hour. */
+    readonly now?: () => number;
+    readonly onEvict?: SnapshotCacheEvictListener;
+}
 export declare class SnapshotCache {
     private readonly byKey;
     /** deviceId → its live keys, so invalidation is O(streams) not O(cache). */
     private readonly keysByDevice;
+    private readonly maxBytes;
+    private readonly idleTtlMs;
+    private readonly now;
+    private readonly onEvict;
+    private totalBytes;
+    constructor(options?: SnapshotCacheOptions);
     get(deviceId: number, streamId: string | undefined): SnapshotCacheEntry | undefined;
     set(deviceId: number, streamId: string | undefined, entry: SnapshotCacheEntry): void;
     /** The newest entry for a device, whichever stream produced it. */
     latest(deviceId: number): SnapshotCacheEntry | undefined;
+    /** Base64 bytes currently retained. The number the budget is enforced on. */
+    sizeBytes(): number;
+    /** Entries currently retained. */
+    entryCount(): number;
+    /** Read through the idle timeout: an entry nobody has touched inside
+     *  `idleTtlMs` is dropped here rather than on a sweep, so the cost is paid by
+     *  the caller that proves it was not wanted. */
+    private read;
+    /** Evict least-recently-ACCESSED first until the budget holds. `protectedKey`
+     *  is the entry just written — evicting it would make `set` a no-op. */
+    private enforceBudget;
+    private evict;
+    /** Remove a key and everything that indexes or accounts for it. */
+    private forget;
     /**
      * Drop every stream of one device.
      *

package/dist/builtins/snapshot/snapshot-resize.d.ts

@@ -69,14 +69,46 @@ export declare function resizeJpeg(bytes: Buffer, width: number, timeoutMs?: num
  * Without that check a card would keep showing a thumbnail of a frame the
  * full-size view had already replaced.
  */
+/**
+ * Byte budget across every retained variant.
+ *
+ * Variants are small individually (a card-sized JPEG is tens of KB) but the key
+ * space is a product — device × stream × width × state treatment — and the map
+ * had no cap at all. 16 MiB is hundreds of thumbnails, far beyond any real
+ * roster's working set, and turns an unbounded product into a ceiling.
+ */
+export declare const SNAPSHOT_VARIANT_CACHE_MAX_BYTES: number;
+export interface SnapshotVariantCacheOptions {
+    /** Total variant bytes retained. Default {@link SNAPSHOT_VARIANT_CACHE_MAX_BYTES}. */
+    readonly maxBytes?: number;
+    /** Injected clock, so LRU order is testable without real time passing. */
+    readonly now?: () => number;
+}
 export declare class SnapshotVariantCache {
     private readonly byKey;
     private readonly keysByDevice;
+    private readonly maxBytes;
+    private readonly now;
+    private totalBytes;
+    constructor(options?: SnapshotVariantCacheOptions);
     private static key;
     /** The variant for this exact frame, or undefined when it is missing or was
-     *  derived from an older capture. */
+     *  derived from an older capture.
+     *
+     *  A superseded variant is DELETED here, not merely reported missing. It used
+     *  to be left in the map: unreachable by every future read (its `sourceTs` can
+     *  never match again) and removed by nothing, so every recapture added a dead
+     *  key. Returning `undefined` while retaining the bytes is the leak. */
     get(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, variantKey?: string): Buffer | undefined;
     set(deviceId: number, streamId: string | undefined, width: number, sourceTs: number, bytes: Buffer, variantKey?: string): void;
+    /** Variant bytes currently retained. */
+    sizeBytes(): number;
+    /** Variants currently retained — including any that are no longer readable.
+     *  The number that used to only ever go up. */
+    entryCount(): number;
+    /** Evict least-recently-accessed first until the budget holds. */
+    private enforceBudget;
+    private forget;
     deleteDevice(deviceId: number): void;
     clear(): void;
 }

package/dist/builtins/snapshot/snapshot.addon.d.ts

@@ -30,6 +30,12 @@ interface SnapshotAddonConfig {
  * publishes stream endpoints.
  */
 export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
+    /**
+     * The frame cache. Bounded by a byte budget + an idle timeout — it used to be
+     * unbounded in both. Every eviction is logged with the device tag: a frame
+     * that silently left the cache is the reason a later capture had to happen,
+     * and per-camera is the only way that question is ever asked.
+     */
     private readonly cache;
     /** Card-sized derivatives of the frames above, keyed by width and validated
      *  against the source frame's timestamp. */

package/dist/builtins/sqlite-storage/filesystem-storage.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-9sC0wZw6.js");
+const require_dist = require("../../dist-qnwy_iWM.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");

package/dist/builtins/sqlite-storage/filesystem-storage.addon.mjs

@@ -1,4 +1,4 @@
-import { V as filesystemBrowseCapability, pt as storageProviderCapability, yt as BaseAddon } from "../../dist-3wh5LCad.mjs";
+import { V as filesystemBrowseCapability, pt as storageProviderCapability, yt as BaseAddon } from "../../dist-DHKXob1m.mjs";
 import { randomUUID } from "node:crypto";
 import { mkdir, readdir, realpath, statfs } from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/sqlite-storage/sqlite-settings.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-9sC0wZw6.js");
+const require_dist = require("../../dist-qnwy_iWM.js");
 let node_crypto = require("node:crypto");
 let node_fs = require("node:fs");
 let node_module = require("node:module");

package/dist/builtins/sqlite-storage/sqlite-settings.addon.mjs

@@ -1,4 +1,4 @@
-import { A as dataStoreProviderCapability, Bt as parseJsonUnknown, _t as vectorStoreCapability, f as RUNTIME_DEFAULTS, gt as vectorDimFromBase64, j as decodeVectorBase64, kt as asJsonObject, vt as errMsg, w as bareAddonId, yt as BaseAddon } from "../../dist-3wh5LCad.mjs";
+import { A as dataStoreProviderCapability, Bt as parseJsonUnknown, _t as vectorStoreCapability, f as RUNTIME_DEFAULTS, gt as vectorDimFromBase64, j as decodeVectorBase64, kt as asJsonObject, vt as errMsg, w as bareAddonId, yt as BaseAddon } from "../../dist-DHKXob1m.mjs";
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-9sC0wZw6.js");
+const require_dist = require("../../dist-qnwy_iWM.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);

package/dist/builtins/storage-orchestrator/storage-orchestrator.addon.mjs

@@ -1,4 +1,4 @@
-import { dt as storageCapability, ft as storageMigrationCapability, g as StorageMigrationJobSchema, h as StorageLocationTypeSchema, lt as settingsStoreCapability, yt as BaseAddon, zt as parseJsonObject } from "../../dist-3wh5LCad.mjs";
+import { dt as storageCapability, ft as storageMigrationCapability, g as StorageMigrationJobSchema, h as StorageLocationTypeSchema, lt as settingsStoreCapability, yt as BaseAddon, zt as parseJsonObject } from "../../dist-DHKXob1m.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/system-config/system-config.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-9sC0wZw6.js");
+const require_dist = require("../../dist-qnwy_iWM.js");
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/system-config/system-config.addon.mjs

@@ -1,4 +1,4 @@
-import { It as hydrateSchema, vt as errMsg, yt as BaseAddon } from "../../dist-3wh5LCad.mjs";
+import { It as hydrateSchema, vt as errMsg, yt as BaseAddon } from "../../dist-DHKXob1m.mjs";
 //#region src/builtins/system-config/system-config.addon.ts
 /**
 * Built-in `system-config` addon — Phase 4 of the settings redesign.

package/dist/builtins/winston-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-9sC0wZw6.js");
+const require_dist = require("../../dist-qnwy_iWM.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/builtins/winston-logging/index.mjs

@@ -1,4 +1,4 @@
-import { X as logDestinationCapability, yt as BaseAddon } from "../../dist-3wh5LCad.mjs";
+import { X as logDestinationCapability, yt as BaseAddon } from "../../dist-DHKXob1m.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 import * as path$1 from "node:path";
 import path from "node:path";