@camstack/addon-pipeline 1.2.198 → 1.2.200

package/dist/stream-broker/{hostInit-C8tu7NS4.mjs → hostInit-D_cZQhBA.mjs}

@@ -36,7 +36,7 @@ async function r() {
 				}
 			},
 			"@camstack/types": {
-				version: "1.2.160",
+				version: "1.2.162",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,
@@ -45,7 +45,7 @@ async function r() {
 				}
 			},
 			"@camstack/sdk": {
-				version: "1.2.80",
+				version: "1.2.82",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,
@@ -81,7 +81,7 @@ async function r() {
 				}
 			},
 			"@camstack/ui-library": {
-				version: "1.2.128",
+				version: "1.2.130",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,

package/dist/stream-broker/index.js

@@ -2,12 +2,12 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-BxP0SvPz.js");
-const require_node = require("../node-BIKrNEtS.js");
-const require_restream_intent = require("../restream-intent-Cv9x3jmu.js");
+const require_dist = require("../dist-D2YTTkRf.js");
+const require_node = require("../node-x3YokJkD.js");
+const require_restream_intent = require("../restream-intent-B1Difcnq.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
-const require_prebuffer = require("../prebuffer-DqdeLSsk.js");
-const require_segment_demux_js = require("../segment-demux-js-DLwL1vmq.js");
+const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
+const require_segment_demux_js = require("../segment-demux-js-DUZVURQd.js");
 let node_os = require("node:os");
 node_os = require_dist.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -370,7 +370,7 @@ var BROKER_PROBE_SNAPSHOTS_SPEC = {
 	loadLimit: BROKER_ROWS_LIMIT
 };
 function probeSnapshotsStore(store, logger) {
-	return new require_prebuffer.RowMapStore({
+	return new require_retire_root_keys.RowMapStore({
 		spec: BROKER_PROBE_SNAPSHOTS_SPEC,
 		store,
 		logger
@@ -412,7 +412,7 @@ var BROKER_RTSP_TOKENS_SPEC = {
 	loadLimit: BROKER_ROWS_LIMIT
 };
 function rtspTokensStore(store, logger) {
-	return new require_prebuffer.RowMapStore({
+	return new require_retire_root_keys.RowMapStore({
 		spec: BROKER_RTSP_TOKENS_SPEC,
 		store,
 		logger
@@ -453,7 +453,7 @@ var BROKER_PROFILE_MAP_SPEC = {
 	loadLimit: BROKER_ROWS_LIMIT
 };
 function profileMapStore(store, logger) {
-	return new require_prebuffer.RowMapStore({
+	return new require_retire_root_keys.RowMapStore({
 		spec: BROKER_PROFILE_MAP_SPEC,
 		store,
 		logger
@@ -2070,7 +2070,7 @@ var NOTHING = {
 function usablePreRoll(value) {
 	if (value === void 0) return 0;
 	if (!Number.isFinite(value) || value <= 0) return 0;
-	return Math.min(require_prebuffer.PREBUFFER_MAX_MS, value);
+	return Math.min(require_restream_intent.PREBUFFER_MAX_MS, value);
 }
 /**
 * Choose the keyframe access unit a pre-roll burst starts at.
@@ -2583,6 +2583,18 @@ var DEFAULT_PRIME_BURST_BOUND = {
 /** Drop/withhold accounting is aggregated and reported at most this often. */
 var DROP_REPORT_INTERVAL_MS$1 = 3e4;
 /**
+* How often a HISTORY-FREE attach is reported per stream.
+*
+* The baseline population is large and uninteresting one line at a time — a
+* WebRTC bootstrap, a HomeKit leg, an ffprobe — but it is the control group the
+* pre-roll cost is measured against, so it cannot be silent either. Throttled
+* here and NOT throttled for an attach that carried history: that population is
+* rare (17 of ~130 agganci in the 2026-09-07 census) and it is the one the
+* question is about, so a rate limit sized for the common case would drop
+* exactly the samples nobody has.
+*/
+var PLAIN_ATTACH_REPORT_INTERVAL_MS = 1e4;
+/**
 * Defensive hard bound on the per-keyframe RTP/NAL cache (both the passthrough
 * `lastKeyframeRtpPackets` and the Annex-B `lastKeyframeNals`). A single
 * keyframe GOP is at most a few large NALs — well under a megabyte or two even
@@ -2732,6 +2744,8 @@ var RtspRestreamer = class {
 	dropsLiveLatched = 0;
 	dropsLiveClosed = 0;
 	dropReportMs = 0;
+	/** Last history-free attach reported — see {@link PLAIN_ATTACH_REPORT_INTERVAL_MS}. */
+	plainAttachReportMs = 0;
 	/** Numeric device id parsed once from the brokerId, for `tags.deviceId`. */
 	deviceId;
 	constructor(streamName) {
@@ -2991,7 +3005,7 @@ var RtspRestreamer = class {
 		if (primePackets.length === 0) return;
 		const firstTs = primePackets[0].data.readUInt32BE(4);
 		const spanMs = (primePackets[primePackets.length - 1].data.readUInt32BE(4) - firstTs | 0) / 90;
-		const preRollState = { plan: null };
+		const preRollPlans = /* @__PURE__ */ new Map();
 		const bound = this.currentPrimeBound();
 		/**
 		* Resolve (and memoize) the plan for one intent.
@@ -3003,28 +3017,33 @@ var RtspRestreamer = class {
 		* current GOP or a supplier bug can, and D57's remedy (join clean at the
 		* next live keyframe) is the right one for a burst nobody asked for.
 		*/
-		const planFor = () => {
-			if (preRollState.plan) return preRollState.plan;
+		const planFor = (requestedMs) => {
+			const memo = preRollPlans.get(requestedMs);
+			if (memo) return memo;
 			const burst = this.preRollSupplier?.();
-			const window = fromRing && burst && burst.preRollMs > 0 ? burst.packets() : [];
+			const window = fromRing && burst && burst.preRollMs > 0 && requestedMs > 0 ? burst.packets(requestedMs) : [];
 			const packets = window.length > primePackets.length ? window.map((data) => ({
 				data,
 				marker: (data[1] & 128) !== 0
 			})) : [];
 			const windowSpanMs = packets.length > 0 ? (packets[packets.length - 1].data.readUInt32BE(4) - packets[0].data.readUInt32BE(4) | 0) / 90 : 0;
-			const windowBound = packets.length > 0 ? preRollSpanBound(bound, burst?.preRollMs ?? 0) : bound;
+			const servableMs = Math.min(requestedMs, burst?.preRollMs ?? 0);
+			const windowBound = packets.length > 0 ? preRollSpanBound(bound, servableMs) : bound;
 			const plan = {
 				packets,
 				active: packets.length > 0,
-				configuredMs: burst?.preRollMs ?? 0,
+				retainedMs: burst?.preRollMs ?? 0,
+				requestedMs,
 				spanMs: windowSpanMs,
 				overBound: packets.length > 0 && (windowSpanMs > windowBound.maxSpanMs || packets.length > windowBound.maxPackets)
 			};
-			preRollState.plan = plan;
+			preRollPlans.set(requestedMs, plan);
 			return plan;
 		};
 		const served = [];
 		const servedPreRoll = /* @__PURE__ */ new Map();
+		/** The plan each pre-roll session was actually served, for its attach line. */
+		const servedPlan = /* @__PURE__ */ new Map();
 		let withheld = 0;
 		let detectionIntentServed = 0;
 		for (const sessionId of ready) {
@@ -3032,8 +3051,9 @@ var RtspRestreamer = class {
 			if (!session) continue;
 			const detectionIntent = session.isDetectionIntent();
 			const preRollIntent = session.preRollIntent();
-			if (preRollIntent !== null) {
-				const plan = planFor();
+			const requestedMs = session.preRollRequestMs();
+			if (preRollIntent !== null && requestedMs > 0) {
+				const plan = planFor(requestedMs);
 				if (plan.active) {
 					if (plan.overBound) {
 						this.dropsWithheldSpan++;
@@ -3041,6 +3061,7 @@ var RtspRestreamer = class {
 						continue;
 					}
 					servedPreRoll.set(sessionId, preRollIntent);
+					servedPlan.set(sessionId, plan);
 					served.push(sessionId);
 					this.logger?.info("restream pre-roll served", {
 						tags: { deviceId: this.deviceId },
@@ -3049,7 +3070,8 @@ var RtspRestreamer = class {
 							sessionId,
 							intent: preRollIntent,
 							consumer: session.getUserAgent() ?? "unknown",
-							configuredMs: plan.configuredMs,
+							requestedMs: plan.requestedMs,
+							retainedMs: plan.retainedMs,
 							spanMs: Math.round(plan.spanMs),
 							packets: plan.packets.length
 						}
@@ -3078,8 +3100,16 @@ var RtspRestreamer = class {
 		}
 		if (withheld > 0) this.reportDrops(false);
 		if (served.length === 0) return;
-		/** Media actually delivered, or `-1` when nobody asked for history at all. */
-		const servedSpanMs = preRollState.plan === null ? -1 : Math.round(preRollState.plan.spanMs);
+		/**
+		* Media actually delivered — the WIDEST window any session took, or `-1`
+		* when nobody asked for history at all.
+		*
+		* A max and not a single plan's span since D382: two sessions on the same
+		* keyframe can be served different windows, and the number this aggregate
+		* line owes its reader is the largest burst this stream let out. The
+		* per-attach truth is on `restream attach live-edge`, one line per session.
+		*/
+		const servedSpanMs = preRollPlans.size === 0 ? -1 : Math.round(Math.max(...[...preRollPlans.values()].map((p) => p.spanMs)));
 		/** Which declared intents joined this burst — `0` is "none", not "off". */
 		const intentsServed = new Set(servedPreRoll.values());
 		this.logger?.info("restream prime (lat-probe)", {
@@ -3106,15 +3136,30 @@ var RtspRestreamer = class {
 			prime: true,
 			keyframeAuStart: false
 		}));
-		const preRollItems = servedPreRoll.size > 0 ? (preRollState.plan?.packets ?? []).map((packet) => ({
-			packet,
-			prime: true,
-			keyframeAuStart: false
-		})) : [];
+		const preRollItems = /* @__PURE__ */ new Map();
+		const itemsFor = (plan) => {
+			const memo = preRollItems.get(plan.requestedMs);
+			if (memo) return memo;
+			const built = plan.packets.map((packet) => ({
+				packet,
+				prime: true,
+				keyframeAuStart: false
+			}));
+			preRollItems.set(plan.requestedMs, built);
+			return built;
+		};
 		for (const sessionId of served) {
 			this.pendingKeyframe.delete(sessionId);
-			const intent = servedPreRoll.get(sessionId);
-			this.startPrimeReplay(sessionId, intent ? preRollItems : items, intent ?? null);
+			const intent = servedPreRoll.get(sessionId) ?? null;
+			const plan = servedPlan.get(sessionId) ?? null;
+			this.startPrimeReplay(sessionId, plan ? itemsFor(plan) : items, intent, {
+				intent,
+				requestedMs: plan?.requestedMs ?? 0,
+				retainedMs: plan?.retainedMs ?? this.preRollSupplier?.().preRollMs ?? 0,
+				preRollSpanMs: plan ? Math.round(plan.spanMs - spanMs) : 0,
+				burstSpanMs: Math.round(plan ? plan.spanMs : spanMs),
+				gopSpanMs: Math.round(spanMs)
+			});
 		}
 	}
 	/**
@@ -3127,7 +3172,7 @@ var RtspRestreamer = class {
 	* session that went away — aborts the whole replay rather than punching holes
 	* in the GOP: the session is left latched and rejoins at the next keyframe AU.
 	*/
-	startPrimeReplay(sessionId, items, preRollIntent) {
+	startPrimeReplay(sessionId, items, preRollIntent, attach) {
 		const replay = new PacedRtpReplay((item) => {
 			const session = this.sessions.get(sessionId);
 			if (!session) {
@@ -3157,6 +3202,7 @@ var RtspRestreamer = class {
 					durationMs: stats.durationMs
 				}
 			});
+			this.reportAttach(sessionId, attach, stats);
 			this.logger?.debug("restream prime drained", {
 				tags: { deviceId: this.deviceId },
 				meta: {
@@ -3175,6 +3221,58 @@ var RtspRestreamer = class {
 		this.activeReplays.set(sessionId, replay);
 		replay.start(items);
 	}
+	/**
+	* ONE LINE PER ATTACH: what this session asked for, what it was handed, and
+	* how long it took to reach the live edge.
+	*
+	* The question this exists to answer is "does the pre-roll delay the first
+	* inference, and by how much" — and it could not be answered before. The only
+	* measurement in reach was `pipeline stats`, a 10 s window whose averages
+	* dissolve a 4 s transient by construction, and the broker's own lines were
+	* per-STREAM aggregates that named a window without naming a session or a
+	* duration. Seventeen served bursts inside ninety minutes of ten-second
+	* averages is not a measurement, it is a hope.
+	*
+	* `liveEdgeMs` is measured from PLAY, the first instant the restreamer owes
+	* this session bytes, to the moment its burst has drained and it is on the
+	* live feed. It therefore contains the wait for a keyframe AND the paced
+	* drain — the two things a burst can cost a joiner on this side of the
+	* socket. What it deliberately does NOT contain is the consumer's own decode
+	* of that burst: that is measured where it happens, on
+	* `session-decode: detection first frame`, and the two lines are joined by
+	* `deviceId` plus the per-attach `consumer` tag.
+	*
+	* `aborted` is on the line because a burst that never reached the socket is
+	* not a burst this session paid for, and averaging those in would understate
+	* the cost of the ones that did.
+	*/
+	reportAttach(sessionId, attach, stats) {
+		const session = this.sessions.get(sessionId);
+		const playAt = session?.getPlayAt() ?? 0;
+		if (!(attach.preRollSpanMs > 0)) {
+			const now = Date.now();
+			if (now - this.plainAttachReportMs < PLAIN_ATTACH_REPORT_INTERVAL_MS) return;
+			this.plainAttachReportMs = now;
+		}
+		this.logger?.info("restream attach live-edge", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				streamName: this.streamName,
+				sessionId,
+				consumer: session?.getUserAgent() ?? "unknown",
+				intent: attach.intent ?? "none",
+				requestedMs: attach.requestedMs,
+				retainedMs: attach.retainedMs,
+				preRollSpanMs: attach.preRollSpanMs,
+				burstSpanMs: attach.burstSpanMs,
+				gopSpanMs: attach.gopSpanMs,
+				liveEdgeMs: playAt > 0 ? Date.now() - playAt : -1,
+				drainMs: Math.round(stats.durationMs),
+				packets: stats.sent,
+				aborted: stats.aborted
+			}
+		});
+	}
 	/** Cancel a session's in-flight join replay (teardown / stream reset). */
 	abortReplay(sessionId) {
 		const replay = this.activeReplays.get(sessionId);
@@ -3457,15 +3555,31 @@ var RtspSession = class {
 	/** When true, this session receives video-only (no audio RTP). */
 	muted;
 	/**
-	* The consumer purpose this session DECLARED on its dial path (see
-	* `restream-intent.ts`), or `null` when it declared none — which is every
-	* consumer except the per-session detection decode.
+	* What this session DECLARED on its dial path (see `restream-intent.ts`): its
+	* consumer purpose, and how many ms of retained history it asked for.
+	* {@link NO_DECLARATION} when it declared nothing — which is every consumer
+	* except the per-session detection decode and the recorder's writer.
 	*
 	* Kept separate from {@link muted} deliberately: `isMuted()` is shared by the
 	* WebRTC/HomeKit loopback legs, and the join rule that keys on it must stay
 	* true for them. Only an explicit declaration changes behaviour.
+	*
+	* One field and not two, because the purpose and the amount are one
+	* statement (D382): a session that names a purpose without naming an amount
+	* is asking for nothing, and that has to be as unmistakable here as it is on
+	* the wire.
 	*/
-	intent;
+	declaration;
+	/**
+	* Epoch ms at which this session reached PLAY, or `0` before it does.
+	*
+	* The clock the join is measured against. `connectedAt` is the TCP accept,
+	* which includes DESCRIBE/SETUP and, for a cold broker, the whole upstream
+	* dial — so it answers "how slow was the camera", not "what did the burst
+	* cost this session". Time to the live edge is measured from PLAY, because
+	* PLAY is the first instant at which the restreamer owes this session bytes.
+	*/
+	playAt = 0;
 	/**
 	* Latch for ANY session that has started dropping video packets on socket
 	* backlog — it was written for the `muted` decoder loopback, which was the
@@ -3479,12 +3593,12 @@ var RtspSession = class {
 	/** Consecutive keyframe AUs at which this session was still unwritable.
 	*  Reset by any successful write — the bound is CONSECUTIVE misses. */
 	missedKeyframes = 0;
-	constructor(socket, sdp, onClose, muted, intent) {
+	constructor(socket, sdp, onClose, muted, declaration) {
 		this.socket = socket;
 		this.sdp = sdp;
 		this.onClose = onClose;
 		this.muted = muted ?? false;
-		this.intent = intent ?? null;
+		this.declaration = declaration ?? require_restream_intent.NO_DECLARATION;
 		this.sessionId = (0, node_crypto.randomUUID)().replace(/-/g, "").slice(0, 16);
 		socket.on("data", (chunk) => {
 			if (this.closed) return;
@@ -3528,7 +3642,23 @@ var RtspSession = class {
 	* construction and drains the burst instead of accumulating it.
 	*/
 	isDetectionIntent() {
-		return this.intent === "detection";
+		return this.declaration.intent === "detection";
+	}
+	/**
+	* Ms of retained history this session ASKED for on its dial. `0` = none.
+	*
+	* Read by `RtspRestreamer.servePendingSessionsRtp`, which serves the smaller
+	* of this and what the ring holds. A session that declared an intent and no
+	* amount takes the ordinary current-GOP burst — the intent still buys it
+	* whatever else the intent buys (for detection, the live-edge exemption), and
+	* nothing more.
+	*/
+	preRollRequestMs() {
+		return this.declaration.preRollRequestMs;
+	}
+	/** Epoch ms at which this session reached PLAY; `0` if it has not. */
+	getPlayAt() {
+		return this.playAt;
 	}
 	/**
 	* Does this session get the PRE-ROLL window instead of the current GOP?
@@ -3545,12 +3675,14 @@ var RtspSession = class {
 	* WHICH pre-roll window this session gets, or `null` when it declared no
 	* intent and takes the ordinary current-GOP join burst.
 	*
-	* The two windows are two numbers (D193), so the restreamer needs the intent
-	* and not just the bit: a recorder handed detection's window would carry the
-	* pre-roll of a feature it is not, and on this fleet detection's is 0.
+	* There is ONE window now (D381) and one ASK per session (D382), so what the
+	* restreamer still needs from this is WHO joined — the identity it prints
+	* beside the window it served, and the reason a recorder and a detector are
+	* distinguishable on a line that reports one number.
 	*/
 	preRollIntent() {
-		return this.intent === "detection" || this.intent === "recording" ? this.intent : null;
+		const intent = this.declaration.intent;
+		return intent === "detection" || intent === "recording" ? intent : null;
 	}
 	/**
 	* Diagnostic snapshot consumed by `StreamBroker.listClients` (Phase 10).
@@ -3771,6 +3903,7 @@ var RtspSession = class {
 	}
 	handlePlay(req) {
 		this.playing = true;
+		if (this.playAt === 0) this.playAt = Date.now();
 		this.respond(req, 200, "OK", {
 			Session: this.sessionId,
 			Range: "npt=0.000-"
@@ -3927,7 +4060,7 @@ var RtspListenServer = class RtspListenServer {
 	async dispatch(socket, requestBuffer) {
 		const uriMatch = (requestBuffer.split("\r\n")[0] ?? "").match(/\s(rtsp:\/\/[^\s]+)\s/);
 		const pathMatch = (uriMatch ? uriMatch[1] : "").match(/rtsp:\/\/[^/]+(\/.*?)(?:\s|$)/);
-		const { lookupPath, muted: isMuted, intent } = require_restream_intent.parseRestreamPath(pathMatch ? pathMatch[1].replace(/^\//, "").replace(/\/trackID=\d+$/, "") : "");
+		const { lookupPath, muted: isMuted, declaration } = require_restream_intent.parseRestreamPath(pathMatch ? pathMatch[1].replace(/^\//, "").replace(/\/trackID=\d+$/, "") : "");
 		const restreamer = this.restreamers.get(lookupPath);
 		if (!restreamer) {
 			socket.write(`RTSP/1.0 404 Not Found\r\nCSeq: 1\r\n\r\n`);
@@ -3956,7 +4089,7 @@ var RtspListenServer = class RtspListenServer {
 		const session = new RtspSession(socket, isMuted ? restreamer.getMutedSdp() ?? restreamer.getSdp() ?? "" : restreamer.getSdp() ?? "", () => {
 			restreamer.removeSession(session.getSessionId());
 			releaseOnce();
-		}, isMuted, intent);
+		}, isMuted, declaration);
 		restreamer.addSession(session);
 		releaseOnce();
 		socket.unshift(Buffer.from(requestBuffer, "ascii"));
@@ -11701,7 +11834,7 @@ var StreamBroker = class StreamBroker {
 		this.rtspRestreamer.setPrimeBoundSupplier(() => this.joinBurstBound);
 		this.rtspRestreamer.setPreRollSupplier(() => {
 			return {
-				packets: () => this.getRtpPreRollBuffer(),
+				packets: (requestedMs) => this.getRtpPreRollBuffer(requestedMs),
 				preRollMs: this.prebufferMs
 			};
 		});
@@ -12778,7 +12911,7 @@ var StreamBroker = class StreamBroker {
 	* other numbers quietly sized the history that did exist.
 	*/
 	setPrebuffer(config) {
-		const next = require_prebuffer.prebufferRetentionMs(config);
+		const next = require_restream_intent.prebufferRetentionMs(config);
 		this.setPreBufferEnabled(config.enabled);
 		this.setPreBufferDuration(config.seconds);
 		if (next === this.prebufferMs) return;
@@ -12913,7 +13046,7 @@ var StreamBroker = class StreamBroker {
 	*/
 	getRtpPreRollBuffer(requestedMs) {
 		if (!this.rtpRingHasKeyframe) return [];
-		const windowMs = require_prebuffer.capPreRollRequestMs(requestedMs, this.prebufferMs);
+		const windowMs = require_restream_intent.capPreRollRequestMs(requestedMs, this.prebufferMs);
 		if (windowMs <= 0 || this.rtpRing.length === 0) return this.getRtpPreBuffer();
 		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
 		const selection = selectPreRollStart(this.rtpPreRollMarks(newestTs), windowMs);
@@ -18295,7 +18428,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				};
 				nextOverride.preBuffer = pb;
 				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-				if (broker) broker.setPrebuffer(require_prebuffer.resolvePrebuffer({
+				if (broker) broker.setPrebuffer(require_restream_intent.resolvePrebuffer({
 					camStreamId,
 					clusterSeconds: this.defaultPreBufferSec,
 					overrides: pb,
@@ -19238,7 +19371,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* broker's own flag shipped `true`.
 	*/
 	effectivePrebuffer(deviceId, camStreamId) {
-		return require_prebuffer.resolvePrebuffer({
+		return require_restream_intent.resolvePrebuffer({
 			camStreamId,
 			clusterSeconds: this.defaultPreBufferSec,
 			overrides: this.deviceOverrides.get(deviceId)?.preBuffer,
@@ -30154,7 +30287,7 @@ var StreamBrokerAddon = class extends require_dist.BaseAddon {
 	*/
 	async purgeFlattenedSettingsKeys() {
 		try {
-			await require_prebuffer.retireRootKeys({
+			await require_retire_root_keys.retireRootKeys({
 				store: this.ctx.api.settingsStore,
 				addonId: STREAM_BROKER_ADDON_ID,
 				logger: this.ctx.logger,