@camstack/system 1.2.79 → 1.2.81

package/dist/builtins/snapshot/snapshot-keep-warm.d.ts

@@ -1,86 +0,0 @@
-/**
- * Subscription bookkeeping for the snapshot keep-warm loop.
- *
- * The snapshot cache has exactly one writer — a successful capture — and every
- * capture is triggered by somebody asking. Nothing refreshes a frame on its own,
- * so with no viewer open every thumbnail in the system is as old as the last
- * time somebody looked. Measured on the live hub: 15 of 16 cameras cached, all
- * captured in one 55 ms burst, all 10 minutes old and not moving.
- *
- * The fix is a warm loop — but a blind one would dial 16 cameras forever for
- * nobody. This module holds the thing that makes it bounded: a warm tick only
- * touches cameras SOMEBODY IS LOOKING AT, and "looking at" is inferred from the
- * requests themselves. One data-plane request for a device makes it an observer
- * for {@link WARM_WINDOW_MS}; when the last viewer closes, the loop goes quiet
- * on its own after that window and costs exactly nothing.
- *
- * Pure and side-effect-free (no timer, no I/O, `now` injected) — the addon owns
- * the timer, this owns the decision. Unit-tested in
- * `__tests__/snapshot-keep-warm.spec.ts`.
- */
-/**
- * How often the warm loop runs. Chosen so a tile is perceptibly fresh while
- * watched; it is also the single biggest cost lever in the design (16 cameras ×
- * 12 ticks/min against a pool of 3 ffmpeg). A chained timer, not `setInterval` —
- * the next tick is scheduled only after the previous one settles, so a slow
- * fleet cannot stack ticks on top of each other.
- */
-export declare const WARM_INTERVAL_MS = 5000;
-/**
- * How long one request keeps a device warm. Two minutes of inertia after the
- * last observer goes away: long enough that flipping between screens (or a
- * phone locking briefly) does not go cold, short enough that a closed app stops
- * costing captures well before anyone notices.
- */
-export declare const WARM_WINDOW_MS = 120000;
-/**
- * Hard bound on tracked subscriptions. The map is keyed by whatever device ids
- * arrive over HTTP, so it is attacker-influenced: a sweep over ids must not be
- * able to grow it without limit, nor make a warm tick dial an unbounded fleet.
- * Well above any real install's simultaneously-watched camera count.
- */
-export declare const MAX_WARM_TARGETS = 64;
-/** One (device, stream) the warm loop should refresh, plus the widths a client
- *  actually asked for — so the tick can pre-derive exactly those variants and
- *  leave the next real request a hit at BOTH cache levels. */
-export interface SnapshotWarmTarget {
-    readonly deviceId: number;
-    readonly streamId: string | undefined;
-    /** Requested widths still inside the window, ascending. Empty = full frame only. */
-    readonly widths: readonly number[];
-}
-/**
- * Who is being watched right now, and at what sizes.
- *
- * `note` on every data-plane request; `active` on every warm tick. `active`
- * PRUNES as it walks rather than merely filtering — the map is fed by request
- * traffic, so a filter-only read would leave every device ever requested in
- * memory for the life of the process.
- */
-export declare class SnapshotSubscriptions {
-    private readonly entries;
-    /** Record that somebody asked for this (device, stream) — at `width`, when the
-     *  request carried one. */
-    note(deviceId: number, streamId: string | undefined, width: number | undefined, nowMs: number): void;
-    /**
-     * Refresh the window on subscriptions that ALREADY exist. Never creates one.
-     *
-     * This is what stops the design deadlocking, and the deadlock was measured on
-     * the live hub before it existed. The client re-requests an image only when
-     * the frame identity changes, and the identity changes only because the warm
-     * loop captured — so 120 s after the last image request the subscription
-     * expired, warming stopped, the identity froze, the client never asked again,
-     * and the tile was stuck. Ages went 13 s → 49.7 s at exactly t+120 s.
-     *
-     * The client's `getSnapshotOverview` poll is the heartbeat: asking "what is
-     * the state of these cameras" IS the statement that somebody is looking. It
-     * deliberately cannot CREATE a subscription, because that poll is app-wide —
-     * if it did, opening the app would warm every camera on the install, which is
-     * the blind poll this whole design avoids. Only a rendered surface subscribes.
-     */
-    renew(deviceIds: readonly number[], nowMs: number): void;
-    /** The (device, stream) pairs still inside the warm window, dropping the rest. */
-    active(nowMs: number, windowMs?: number): readonly SnapshotWarmTarget[];
-    get size(): number;
-    clear(): void;
-}