@trillboards/edge-platform-rtsp 0.2.14 → 0.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
23
23
  return result;
24
24
  };
25
25
  Object.defineProperty(exports, "__esModule", { value: true });
26
- exports.RTSPStreamCameraProvider = exports.volumeFreeBytes = exports.buildSegmentOutputArgs = exports.readVideoStartSec = exports.videoStartSecFromMoov = exports.audioPlanFor = exports.describeAudioSource = exports.aacBitrateFor = exports.InputStreamProbe = exports.parseInputAudioStreamLine = exports.parseInputVideoStreamLine = exports.parseSegmentListCsv = exports.AUDIO_SUSPEND_MAX_MS = exports.AUDIO_SUSPEND_BASE_MS = exports.AUDIO_START_DEADLINE_MS = exports.RING_FREE_FRACTION = exports.SEGMENT_SUSPEND_MAX_MS = exports.SEGMENT_SUSPEND_BASE_MS = exports.CLOSED_SEGMENTS_DIRNAME = exports.RECORDABLE_CODECS = exports.streamSessionStatsFor = exports.__resetStreamAdmissionForTests = exports.FrameRing = exports.MjpegFrameSplitter = exports.jpegFrameEnd = exports.JPEG_MALFORMED = exports.JPEG_NEED_MORE = exports.DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE = exports.RtspStreamStaleError = exports.RtspStreamAdmissionError = void 0;
26
+ exports.RTSPStreamCameraProvider = exports.volumeFreeBytes = exports.buildSegmentOutputArgs = exports.readVideoStartSec = exports.videoStartSecFromMoov = exports.audioPlanFor = exports.describeAudioSource = exports.aacBitrateFor = exports.InputStreamProbe = exports.parseInputAudioStreamLine = exports.parseInputVideoStreamLine = exports.parseSegmentListCsv = exports.AUDIO_SUSPEND_MAX_MS = exports.AUDIO_SUSPEND_BASE_MS = exports.AUDIO_START_DEADLINE_MS = exports.RETAKE_BACKOFF_MAX_MS = exports.RETAKE_BACKOFF_BASE_MS = exports.RING_RESYNC_MS = exports.RING_FREE_FRACTION = exports.SEGMENT_SUSPEND_MAX_MS = exports.SEGMENT_SUSPEND_BASE_MS = exports.CLOSED_SEGMENTS_DIRNAME = exports.RECORDABLE_CODECS = exports.streamSessionStatsFor = exports.__resetStreamAdmissionForTests = exports.FrameRing = exports.MjpegFrameSplitter = exports.jpegFrameEnd = exports.JPEG_MALFORMED = exports.JPEG_NEED_MORE = exports.DEFAULT_MAX_STREAM_SESSIONS_PER_SOURCE = exports.RtspStreamStaleError = exports.RtspStreamAdmissionError = void 0;
27
27
  const child_process_1 = require("child_process");
28
28
  const events_1 = require("events");
29
29
  const fs = __importStar(require("fs"));
@@ -613,37 +613,26 @@ class FrameRing {
613
613
  }
614
614
  }
615
615
  exports.FrameRing = FrameRing;
616
- // ---------------------------------------------------------------------------
617
- // Per-recorder admission for LONG-LIVED video sessions
618
- // ---------------------------------------------------------------------------
619
- /**
620
- * Deliberately a different pool from `CaptureAdmission` AND from
621
- * `AudioSessionAdmission`: same key, three separate budgets. `tryAcquire` only
622
- * — this lane never queues.
623
- *
624
- * ── THE LIMIT IS LEARNED FROM THE RECORDER, NOT DECLARED ──────────────────
625
- *
626
- * `maxStreamSessionsPerSource` is a POLICY CEILING on our own occupancy. The
627
- * recorder's ceiling is a property of the recorder, it is not discoverable
628
- * before you reach it, and it is not close to constant across recorders —
629
- * measured 2026-08-19 with `scripts/measure-rtsp-session-ceiling.mjs`:
630
- *
631
- * Happytime ONVIF/RTSP Server V8.1 4 (fixed RUA pool; no config key)
632
- * Nx Media Server 6.1.2.42921 >=160 (never refused)
633
- * mediamtx unbounded (which is why the original
634
- * validation could not see any
635
- * of this)
636
- *
637
- * So `learnCeiling` records what the recorder actually did the first time it
638
- * refused, and every later feed is refused by US — instantly, with no recorder
639
- * traffic — instead of by the recorder.
640
- */
641
616
  class StreamSessionAdmission {
642
617
  constructor(limit) {
643
618
  this.active = 0;
644
619
  this.learnedCeiling = null;
645
- /** Live holders, oldest first. Shedding pops the NEWEST — see `learnCeiling`. */
620
+ /**
621
+ * Live holders in admission order. Shedding takes the LOWEST priority, and
622
+ * among equals the NEWEST — see `learnCeiling` and `lowestHolder`.
623
+ */
646
624
  this.holders = [];
625
+ /**
626
+ * Feeds the lane refused (`session_limit`). Only a waiter ranked above 0 is
627
+ * ever offered a slot here — an ordinary feed keeps the reconnect path it
628
+ * always had — and it is offered one only when a slot is free or a holder
629
+ * ranks below it.
630
+ */
631
+ this.waiters = [];
632
+ this.seq = 0;
633
+ this.offerScheduled = false;
634
+ /** One retake at a time: a slot offered is a slot spoken for until it settles. */
635
+ this.retakeInFlight = false;
647
636
  this.limit = limit;
648
637
  }
649
638
  /** Tighten only, matching the other two lanes: the most cautious caller wins. */
@@ -726,24 +715,55 @@ class StreamSessionAdmission {
726
715
  */
727
716
  shedOverQuota() {
728
717
  while (this.active > this.limit && this.holders.length > 0) {
729
- const holder = this.holders.pop();
730
- // `shed` releases through the same closure `tryAcquire` handed out, so
731
- // `active` cannot drift no matter which side initiates the release.
732
- try {
733
- holder.shed();
734
- }
735
- catch {
736
- /* a provider that cannot shed must not wedge the pool */
718
+ this.shedHolder(this.lowestHolder());
719
+ }
720
+ }
721
+ /**
722
+ * The holder to give up first: the LOWEST priority, and among equals the
723
+ * NEWEST. With every holder at 0 this is exactly the newest-first rule
724
+ * above; a camera with an enabled alert (priority 1) keeps its session over
725
+ * every camera without one, because only a session camera can buffer the
726
+ * video an alert window is cut from.
727
+ */
728
+ lowestHolder() {
729
+ let pick = null;
730
+ for (const holder of this.holders) {
731
+ if (!pick || holder.priority < pick.priority || (holder.priority === pick.priority && holder.seq > pick.seq)) {
732
+ pick = holder;
737
733
  }
738
- holder.release();
739
734
  }
735
+ return pick;
740
736
  }
741
- tryAcquire(shed = () => undefined) {
742
- if (this.active >= this.limit)
743
- return null;
737
+ shedHolder(holder) {
738
+ // `shed` releases through the same closure `tryAcquire` handed out, so
739
+ // `active` cannot drift no matter which side initiates the release.
740
+ try {
741
+ holder.shed();
742
+ }
743
+ catch {
744
+ /* a provider that cannot shed must not wedge the pool */
745
+ }
746
+ holder.release();
747
+ }
748
+ /**
749
+ * Take a slot at `priority`. A full lane admits the caller only by shedding
750
+ * a holder ranked strictly BELOW it (lowest, then newest) — equals keep the
751
+ * first-come rule, so ordinary feeds behave exactly as before.
752
+ */
753
+ tryAcquire(shed = () => undefined, priority = 0) {
754
+ if (this.active >= this.limit) {
755
+ const victim = this.lowestHolder();
756
+ if (!victim || victim.priority >= priority)
757
+ return null;
758
+ this.shedHolder(victim);
759
+ if (this.active >= this.limit)
760
+ return null;
761
+ }
744
762
  this.active += 1;
745
763
  let released = false;
746
764
  const entry = {
765
+ priority,
766
+ seq: (this.seq += 1),
747
767
  shed,
748
768
  release: () => {
749
769
  if (released)
@@ -753,10 +773,93 @@ class StreamSessionAdmission {
753
773
  const i = this.holders.indexOf(entry);
754
774
  if (i >= 0)
755
775
  this.holders.splice(i, 1);
776
+ this.scheduleOffer();
756
777
  },
757
778
  };
758
779
  this.holders.push(entry);
759
- return entry.release;
780
+ return {
781
+ release: entry.release,
782
+ setPriority: (next) => {
783
+ if (released || next === entry.priority)
784
+ return;
785
+ entry.priority = next;
786
+ this.scheduleOffer();
787
+ },
788
+ };
789
+ }
790
+ /** Queue a refused feed. `retake` must call its `done` once the attempt settles. */
791
+ addWaiter(priority, retake) {
792
+ const waiter = { priority, seq: (this.seq += 1), retake };
793
+ this.waiters.push(waiter);
794
+ this.scheduleOffer();
795
+ return {
796
+ remove: () => {
797
+ const i = this.waiters.indexOf(waiter);
798
+ if (i >= 0)
799
+ this.waiters.splice(i, 1);
800
+ },
801
+ setPriority: (next) => {
802
+ if (next === waiter.priority)
803
+ return;
804
+ waiter.priority = next;
805
+ this.scheduleOffer();
806
+ },
807
+ };
808
+ }
809
+ getWaiting() {
810
+ return this.waiters.length;
811
+ }
812
+ /**
813
+ * Deferred and coalesced: a release or a re-rank can happen inside a
814
+ * provider's own close/shed path, and offering synchronously would re-enter
815
+ * it.
816
+ */
817
+ scheduleOffer() {
818
+ if (this.offerScheduled || this.waiters.length === 0)
819
+ return;
820
+ this.offerScheduled = true;
821
+ const timer = setImmediate(() => {
822
+ this.offerScheduled = false;
823
+ this.offerOnce();
824
+ });
825
+ if (typeof timer.unref === 'function')
826
+ timer.unref();
827
+ }
828
+ /** Offer one slot to the top waiter: a free one, or one a lower-ranked holder gives up. */
829
+ offerOnce() {
830
+ if (this.retakeInFlight)
831
+ return;
832
+ let top = null;
833
+ for (const waiter of this.waiters) {
834
+ if (!top || waiter.priority > top.priority || (waiter.priority === top.priority && waiter.seq < top.seq))
835
+ top = waiter;
836
+ }
837
+ if (!top || top.priority <= 0)
838
+ return;
839
+ if (this.active >= this.limit) {
840
+ const victim = this.lowestHolder();
841
+ if (!victim || victim.priority >= top.priority)
842
+ return;
843
+ // Nothing is shed here: the retake's own tryAcquire takes the victim's
844
+ // slot only after its checks pass, so a feed that is still pausing
845
+ // after a refusal never costs another feed its session.
846
+ }
847
+ this.waiters.splice(this.waiters.indexOf(top), 1);
848
+ this.retakeInFlight = true;
849
+ let settled = false;
850
+ const done = () => {
851
+ if (settled)
852
+ return;
853
+ settled = true;
854
+ this.retakeInFlight = false;
855
+ this.scheduleOffer();
856
+ };
857
+ try {
858
+ top.retake(done);
859
+ }
860
+ catch {
861
+ done();
862
+ }
760
863
  }
761
864
  }
762
865
  const streamAdmissionBySource = new Map();
@@ -794,12 +897,15 @@ function streamSessionStatsFor(streamUrl) {
794
897
  };
795
898
  }
796
899
  exports.streamSessionStatsFor = streamSessionStatsFor;
900
+ const SEGMENT_LABEL_RE = /^[a-z0-9_]{1,32}$/;
797
901
  /** Codecs `video_segment` holds. Anything else is not recorded. */
798
902
  exports.RECORDABLE_CODECS = ['h264', 'hevc'];
799
903
  /** Closed segments, beside their sidecars, under the feed's directory. */
800
904
  exports.CLOSED_SEGMENTS_DIRNAME = 'closed';
801
905
  /** Session work directories are `rec-<startMs>-<sessionNumber>`. */
802
906
  const SESSION_WORKDIR_PREFIX = 'rec-';
907
+ /** The session's recording label, written into its work directory at start. */
908
+ const SESSION_LABEL_FILE = 'label.json';
803
909
  /**
804
910
  * How often the segment list is read. ffmpeg writes a line the moment it
805
911
  * closes a segment, so this is the whole detection latency, and it is also
@@ -816,8 +922,17 @@ exports.SEGMENT_SUSPEND_MAX_MS = 3600000;
816
922
  * reads "Failed reading RTSP data" / "End of file" and matches none of these.
817
923
  */
818
924
  const SEGMENT_OUTPUT_FAILURE_RE = /(Failed to open segment[^\n]*|No space left on device|Read-only file system|Disk quota exceeded|Could not write header[^\n]*|Error (?:muxing|submitting|writing) (?:a )?packet[^\n]*)/i;
819
- /** The ring may hold at most this fraction of the volume's free bytes. */
925
+ /** The ring may hold at most this fraction of the volume's free bytes (unless the caller sets `maxBytes`). */
820
926
  exports.RING_FREE_FRACTION = 0.1;
927
+ /**
928
+ * How often the ring's in-memory index is rebuilt from disk. Between rebuilds
929
+ * every close updates it, so a ring of thousands of short segments costs one
930
+ * statfs and no directory listing per close.
931
+ */
932
+ exports.RING_RESYNC_MS = 10 * 60000;
933
+ /** First wait before a feed the recorder refused retakes a session; doubles to the max. */
934
+ exports.RETAKE_BACKOFF_BASE_MS = 60000;
935
+ exports.RETAKE_BACKOFF_MAX_MS = 3600000;
821
936
  /**
822
937
  * A session that maps audio and has written no segment file this long after
823
938
  * its first frame is stalled on a microphone that sends nothing. Measured: with
@@ -1291,11 +1406,19 @@ function normalizeSegmentRecording(cfg) {
1291
1406
  return null;
1292
1407
  if (!Number.isFinite(ringSeconds) || ringSeconds < 0)
1293
1408
  return null;
1409
+ const rawMax = cfg.maxBytes === undefined || cfg.maxBytes === null ? null : Number(cfg.maxBytes);
1410
+ if (rawMax !== null && (!Number.isFinite(rawMax) || rawMax < 0))
1411
+ return null;
1412
+ const label = cfg.label === undefined || cfg.label === null ? null : cfg.label;
1413
+ if (label !== null && (typeof label !== 'string' || !SEGMENT_LABEL_RE.test(label)))
1414
+ return null;
1294
1415
  return {
1295
1416
  dir: path.resolve(cfg.dir),
1296
1417
  segmentSeconds: Math.max(1, Math.trunc(segmentSeconds)),
1297
1418
  ringSeconds: Math.trunc(ringSeconds),
1298
1419
  enabled: cfg.enabled !== false,
1420
+ maxBytes: rawMax === null ? null : Math.floor(rawMax),
1421
+ label,
1299
1422
  };
1300
1423
  }
1301
1424
  function writeFileAtomic(file, body) {
@@ -1316,7 +1439,12 @@ function readSidecar(file) {
1316
1439
  const stream = raw.stream && typeof raw.stream === 'object' && typeof raw.stream.codec === 'string'
1317
1440
  ? raw.stream
1318
1441
  : null;
1319
- return { ...raw, stream };
1442
+ const { label, ...rest } = raw;
1443
+ return {
1444
+ ...rest,
1445
+ stream,
1446
+ ...(typeof label === 'string' && SEGMENT_LABEL_RE.test(label) ? { label } : {}),
1447
+ };
1320
1448
  }
1321
1449
  catch {
1322
1450
  return null;
@@ -1361,15 +1489,46 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1361
1489
  * one frame later.
1362
1490
  */
1363
1491
  this.fallbackOpenError = null;
1492
+ /**
1493
+ * The per-grab fallback's open() while it runs. A feed that changes paths
1494
+ * mid-life (a live session handed back when the feed goes idle) is not a
1495
+ * closed camera: `getFrame()` waits for this instead of answering the
1496
+ * fallback's own "Camera not opened", which the manager reads as RTSP down
1497
+ * (the first Windows field run of this change logged exactly that, once per idle
1498
+ * camera, then a 10-s reconnect).
1499
+ */
1500
+ this.fallbackOpening = null;
1364
1501
  /** The live ffmpeg session, or null between sessions. */
1365
1502
  this.session = null;
1366
1503
  /** This recorder's persistent-session lane, for the learned ceiling. */
1367
1504
  this.admission = null;
1368
- this.releaseAdmission = null;
1505
+ this.admissionTicket = null;
1369
1506
  this.restartTimer = null;
1370
1507
  this.startingUp = false;
1371
1508
  // ── segment recording ────────────────────────────────────────────────────
1372
1509
  this.segmentConfig = null;
1510
+ /**
1511
+ * The ring's closed segments, oldest first: rebuilt from disk at most every
1512
+ * `RING_RESYNC_MS` and kept current by every move in between, so a ring of
1513
+ * thousands of 10-s segments is not re-listed and re-stat'ed at every close.
1514
+ * Files a consumer deleted since the last rebuild are dropped when the
1515
+ * eviction walk reaches them (ENOENT) and by the next rebuild.
1516
+ */
1517
+ this.ringIndex = null;
1518
+ /** 0 = an ordinary feed; higher holds its persistent session ahead of lower ones. */
1519
+ this.sessionPriority = 0;
1520
+ /** No live review needs this feed (setIdle); with no recording it runs per-grab. */
1521
+ this.idle = false;
1522
+ /** This feed's place in its recorder's queue for a session, while the lane refused it. */
1523
+ this.sessionWaiter = null;
1524
+ /** Earliest moment a refused retake may try again (capacity refusals back off). */
1525
+ this.retakeNotBeforeMs = 0;
1526
+ /** The pending rejoin after a refusal's pause (cleared by leaveSessionQueue). */
1527
+ this.retakeRejoinTimer = null;
1528
+ this.retakeBackoffMs = exports.RETAKE_BACKOFF_BASE_MS;
1529
+ /** A retake in flight: its token, so a close, a shed or a newer retake can disown it. */
1530
+ this.retake = null;
1531
+ this.retakeTokens = 0;
1373
1532
  /** The newest input description ffmpeg gave; decides the tag and the codec gate. */
1374
1533
  this.streamInfo = null;
1375
1534
  this.segmentsRecoveredFor = null;
@@ -1503,11 +1662,117 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1503
1662
  this.clearSegmentSuspension();
1504
1663
  }
1505
1664
  this.segmentConfig = normalized;
1665
+ // A lower byte cap (a buffer budget that shrank with the free space) is
1666
+ // enforced now, not at the next close. Reads the in-memory ring index:
1667
+ // no listing unless the index is due a rebuild.
1668
+ if (previous && previous.dir === normalized.dir && this.segmentsRecoveredFor === normalized.dir
1669
+ && (normalized.maxBytes ?? Infinity) < (previous.maxBytes ?? Infinity)) {
1670
+ this.enforceRing();
1671
+ }
1506
1672
  }
1507
1673
  if (this.opened && this.segmentConfig && this.segmentsRecoveredFor !== this.segmentConfig.dir) {
1508
1674
  this.recoverSegments();
1509
1675
  }
1510
1676
  this.reconcileRecording();
1677
+ // Recording needs the continuous stream: an idle feed that starts recording
1678
+ // retakes its session, and one that stops gives it back.
1679
+ this.reconcileIdle();
1680
+ }
1681
+ /**
1682
+ * Rank this feed for its recorder's persistent sessions. 0 is an ordinary
1683
+ * feed; the connector raises a camera with an enabled alert to 1, because
1684
+ * only a feed holding a persistent session records the local video an alert
1685
+ * window is cut from. When the recorder cannot serve every feed, a higher
1686
+ * rank keeps or TAKES a session from a lower one (lowest, then newest, gives
1687
+ * way), and a ranked feed the lane refused retakes one as soon as a slot is
1688
+ * free or a lower-ranked holder can give way. Equal ranks keep first come,
1689
+ * first served, so with every feed at 0 nothing changes.
1690
+ */
1691
+ setSessionPriority(priority) {
1692
+ const next = Number.isFinite(priority) ? Math.max(0, Math.trunc(priority)) : 0;
1693
+ if (next === this.sessionPriority)
1694
+ return;
1695
+ this.sessionPriority = next;
1696
+ this.admissionTicket?.setPriority(next);
1697
+ this.sessionWaiter?.setPriority(next);
1698
+ }
1699
+ getSessionPriority() {
1700
+ return this.sessionPriority;
1701
+ }
1702
+ /**
1703
+ * Whether anything is looking at this feed. A feed with no live review (a
1704
+ * camera with no alert profile: Texas had 27 of 32) reads one health frame a
1705
+ * minute, yet its persistent session decoded the camera at its full 6.6-25 fps
1706
+ * (~444 of the box's ~529 decoded frames a second, 2026-11-08). Idle and not
1707
+ * recording, the feed gives its session back and each `getFrame()` is one
1708
+ * per-grab pull, admitted by the same per-recorder bound as every pull.
1709
+ *
1710
+ * Leaving idle (or a recording that starts) retakes a session through the
1711
+ * same path a refused feed uses: the per-grab path keeps answering until the
1712
+ * new session's first frame, so a feed that becomes live never has a gap. A
1713
+ * recording feed always keeps its session: the local video an alert window is
1714
+ * cut from needs the continuous stream. Idempotent; called on every look.
1715
+ */
1716
+ setIdle(idle) {
1717
+ this.idle = idle === true;
1718
+ this.reconcileIdle();
1719
+ }
1720
+ isIdle() {
1721
+ return this.idle;
1722
+ }
1723
+ /** Recording needs the continuous stream whatever the review does. */
1724
+ needsSession() {
1725
+ return !this.idle || this.segmentConfig?.enabled === true;
1726
+ }
1727
+ reconcileIdle() {
1728
+ if (!this.persistentRequested)
1729
+ return;
1730
+ if (this.needsSession()) {
1731
+ if (this.degradedReason !== 'idle' || !this.fallback || this.retake)
1732
+ return;
1733
+ // Wanted again: retake a session while the per-grab path keeps serving.
1734
+ this.degradedReason = 'session_limit';
1735
+ const admission = streamAdmissionFor(this.rtspUrl, this.maxStreamSessionsPerSource);
1736
+ if (!admission)
1737
+ return;
1738
+ this.admission = admission;
1739
+ this.log('info', 'RTSP feed is watched again; retaking its persistent session');
1740
+ this.retakeSession(admission, () => undefined);
1741
+ return;
1742
+ }
1743
+ if (this.retake && this.opened && this.fallback) {
1744
+ // A retake in flight is abandoned: the per-grab path never stopped serving.
1745
+ this.retake = null;
1746
+ this.opened = false;
1747
+ this.startingUp = false;
1748
+ this.stopProcess();
1749
+ this.releaseSlot();
1750
+ }
1751
+ if (this.fallback) {
1752
+ // Already per-grab. A feed queued for a session no longer wants one.
1753
+ if (this.degradedReason === 'session_limit') {
1754
+ this.leaveSessionQueue();
1755
+ this.degradedReason = 'idle';
1756
+ }
1757
+ return;
1758
+ }
1759
+ // A live persistent session (never one still starting: the next call settles it).
1760
+ if (!this.opened || this.startingUp)
1761
+ return;
1762
+ this.opened = false;
1763
+ this.leaveSessionQueue();
1764
+ if (this.restartTimer) {
1765
+ clearTimeout(this.restartTimer);
1766
+ this.restartTimer = null;
1767
+ }
1768
+ this.stopProcess();
1769
+ this.releaseSlot();
1770
+ this.ring.clear();
1771
+ this.splitter.reset();
1772
+ this.wakeWaiters();
1773
+ void this.degradeTo('idle').catch((err) => {
1774
+ this.fallbackOpenError = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err instanceof Error ? err.message : String(err));
1775
+ });
1511
1776
  }
1512
1777
  // ── CameraProvider ───────────────────────────────────────────────────────
1513
1778
  /**
@@ -1541,6 +1806,9 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1541
1806
  // provider that degraded once and could never come back would be the Ember
1542
1807
  // permanent-retirement shape (see handleSessionEnd) at the capture layer.
1543
1808
  // Drop the old provider rather than leaking one per reconnect.
1809
+ // This open() decides admission afresh: a queued or running retake from
1810
+ // the previous degrade is disowned first.
1811
+ this.leaveSessionQueue();
1544
1812
  if (this.fallback) {
1545
1813
  const previous = this.fallback;
1546
1814
  this.fallback = null;
@@ -1558,19 +1826,24 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1558
1826
  await this.degradeTo('disabled');
1559
1827
  return;
1560
1828
  }
1829
+ if (!this.needsSession()) {
1830
+ await this.degradeTo('idle');
1831
+ return;
1832
+ }
1561
1833
  const admission = streamAdmissionFor(this.rtspUrl, this.maxStreamSessionsPerSource);
1562
1834
  this.admission = admission;
1563
1835
  if (admission) {
1564
1836
  // The shed callback is how a LEARNED ceiling reaches a session that was
1565
1837
  // admitted before we knew it. It must not throw and must not await: the
1566
- // pool calls it while it is reconciling occupancy.
1567
- const release = admission.tryAcquire(() => this.shedPersistentSession());
1568
- if (!release) {
1838
+ // pool calls it while it is reconciling occupancy. A ranked feed (an
1839
+ // alert camera) may take the slot of a lower-ranked holder here.
1840
+ const ticket = admission.tryAcquire(() => this.shedPersistentSession(), this.sessionPriority);
1841
+ if (!ticket) {
1569
1842
  this.lastErrorMessage = new RtspStreamAdmissionError((0, RTSPCameraProvider_1.captureSourceKey)(this.rtspUrl) ?? 'unknown', admission.getLimit()).message;
1570
1843
  await this.degradeTo('session_limit');
1571
1844
  return;
1572
1845
  }
1573
- this.releaseAdmission = release;
1846
+ this.admissionTicket = ticket;
1574
1847
  }
1575
1848
  this.opened = true;
1576
1849
  this.mode = 'persistent';
@@ -1661,9 +1934,22 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1661
1934
  * its failure rather than the generic not-opened message.
1662
1935
  */
1663
1936
  shedPersistentSession() {
1937
+ if (this.retake && this.opened && this.fallback) {
1938
+ // Shed mid-retake: the fallback never stopped serving, so abandon the
1939
+ // new session and queue again. The pool releases the ticket on return.
1940
+ this.retake = null;
1941
+ this.opened = false;
1942
+ this.startingUp = false;
1943
+ this.stopProcess();
1944
+ this.admissionTicket = null;
1945
+ this.joinSessionQueue();
1946
+ return;
1947
+ }
1664
1948
  if (!this.opened || this.fallback)
1665
1949
  return;
1666
1950
  this.opened = false;
1951
+ // The pool releases this ticket as soon as this returns.
1952
+ this.admissionTicket = null;
1667
1953
  if (this.restartTimer) {
1668
1954
  clearTimeout(this.restartTimer);
1669
1955
  this.restartTimer = null;
@@ -1693,23 +1979,17 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1693
1979
  * permanently.
1694
1980
  */
1695
1981
  async getFrame() {
1696
- if (this.fallback) {
1697
- // A fallback that never opened cannot answer, and the reason it could not
1698
- // is the one thing worth saying. Re-throwing the recorder's own words
1699
- // keeps `classifyRtspFailureClass` looking at evidence instead of at a
1700
- // message about how this API is called.
1701
- if (this.fallbackOpenError !== null) {
1702
- throw new Error(`RTSP per-grab fallback is not open for ${(0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(this.rtspUrl)}: ` +
1703
- this.fallbackOpenError);
1704
- }
1705
- return this.fallback.getFrame();
1706
- }
1982
+ if (this.fallback)
1983
+ return this.fallbackFrame();
1707
1984
  if (!this.opened)
1708
1985
  throw new Error('Camera not opened. Call open() first.');
1709
1986
  const fresh = this.takeFreshFrame();
1710
1987
  if (fresh)
1711
1988
  return fresh;
1712
1989
  const arrived = await this.waitForFrame(this.frameWaitMs);
1990
+ // The session was handed back (the feed went idle) while this call waited.
1991
+ if (this.fallback)
1992
+ return this.fallbackFrame();
1713
1993
  if (arrived) {
1714
1994
  const next = this.takeFreshFrame();
1715
1995
  if (next)
@@ -1720,6 +2000,31 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1720
2000
  const ageMs = newest ? this.now() - newest.atMs : this.frameWaitMs;
1721
2001
  throw new RtspStreamStaleError(this.rtspUrl, ageMs, this.restarts);
1722
2002
  }
2003
+ /** A frame from the per-grab path, once a fallback still opening has opened. */
2004
+ async fallbackFrame() {
2005
+ const opening = this.fallbackOpening;
2006
+ if (opening) {
2007
+ try {
2008
+ await opening;
2009
+ }
2010
+ catch {
2011
+ /* its reason is in fallbackOpenError, reported below */
2012
+ }
2013
+ }
2014
+ const fallback = this.fallback;
2015
+ // A session replaced the fallback, or close() ran, while this call waited.
2016
+ if (!fallback)
2017
+ return this.getFrame();
2018
+ // A fallback that never opened cannot answer, and the reason it could not
2019
+ // is the one thing worth saying. Re-throwing the recorder's own words
2020
+ // keeps `classifyRtspFailureClass` looking at evidence instead of at a
2021
+ // message about how this API is called.
2022
+ if (this.fallbackOpenError !== null) {
2023
+ throw new Error(`RTSP per-grab fallback is not open for ${(0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(this.rtspUrl)}: ` +
2024
+ this.fallbackOpenError);
2025
+ }
2026
+ return fallback.getFrame();
2027
+ }
1723
2028
  getResolution() {
1724
2029
  return { width: this.width, height: this.height };
1725
2030
  }
@@ -1727,14 +2032,18 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1727
2032
  return this.streamFps;
1728
2033
  }
1729
2034
  isOpen() {
2035
+ // A fallback still opening is a feed changing paths; getFrame() waits for it.
1730
2036
  if (this.fallback)
1731
- return this.fallback.isOpen();
2037
+ return this.fallbackOpening !== null || this.fallback.isOpen();
1732
2038
  return this.opened;
1733
2039
  }
1734
2040
  async close() {
1735
2041
  this.openGeneration += 1;
1736
2042
  this.startingUp = false;
1737
2043
  this.opened = false;
2044
+ this.leaveSessionQueue();
2045
+ // A re-open rebuilds the ring index from disk once.
2046
+ this.ringIndex = null;
1738
2047
  if (this.restartTimer) {
1739
2048
  clearTimeout(this.restartTimer);
1740
2049
  this.restartTimer = null;
@@ -1797,7 +2106,10 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1797
2106
  const generation = this.openGeneration;
1798
2107
  this.mode = 'per_grab';
1799
2108
  this.degradedReason = reason;
1800
- if (reason !== 'disabled') {
2109
+ if (reason === 'idle') {
2110
+ this.log('info', 'RTSP feed idle (no live review, no recording): one per-grab pull per frame');
2111
+ }
2112
+ else if (reason !== 'disabled') {
1801
2113
  this.log('warn', `RTSP persistent session unavailable (${reason}); falling back to per-grab capture` +
1802
2114
  (this.lastErrorMessage ? `: ${this.lastErrorMessage}` : ''));
1803
2115
  }
@@ -1807,8 +2119,19 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1807
2119
  // which is exactly what a connector sees today.
1808
2120
  this.fallback = fallback;
1809
2121
  this.fallbackOpenError = null;
2122
+ // Refused by our own lane, not by the camera: wait for a slot (a ranked
2123
+ // feed takes one when it frees or a lower-ranked holder can give way).
2124
+ if (reason === 'session_limit')
2125
+ this.joinSessionQueue();
2126
+ const opening = fallback.open();
2127
+ this.fallbackOpening = opening;
2128
+ const settled = () => {
2129
+ if (this.fallbackOpening === opening)
2130
+ this.fallbackOpening = null;
2131
+ };
1810
2132
  try {
1811
- await fallback.open();
2133
+ await opening;
2134
+ settled();
1812
2135
  if (generation !== this.openGeneration || this.fallback !== fallback) {
1813
2136
  try {
1814
2137
  await fallback.close();
@@ -1818,6 +2141,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1818
2141
  }
1819
2142
  catch (err) {
1820
2143
  if (generation !== this.openGeneration || this.fallback !== fallback) {
2144
+ settled();
1821
2145
  try {
1822
2146
  await fallback.close();
1823
2147
  }
@@ -1826,17 +2150,154 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
1826
2150
  }
1827
2151
  // KEEP the reason. It is the only description of what the recorder did,
1828
2152
  // and without it `getFrame()` falls back to a message about how the
1829
- // caller used the API — see `fallbackOpenError`.
2153
+ // caller used the API — see `fallbackOpenError`. Set before the opening
2154
+ // is marked settled, so a frame call waiting on it reads the reason.
1830
2155
  this.fallbackOpenError = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err instanceof Error ? err.message : String(err));
1831
2156
  this.lastErrorMessage = this.fallbackOpenError;
2157
+ settled();
1832
2158
  throw err;
1833
2159
  }
1834
2160
  }
1835
2161
  releaseSlot() {
1836
- if (this.releaseAdmission) {
1837
- this.releaseAdmission();
1838
- this.releaseAdmission = null;
2162
+ if (this.admissionTicket) {
2163
+ this.admissionTicket.release();
2164
+ this.admissionTicket = null;
2165
+ }
2166
+ }
2167
+ // ── retaking a session the lane refused ────────────────────────────────────
2168
+ /**
2169
+ * Queue this feed for a session after the lane refused it (`session_limit`).
2170
+ * The lane offers a slot only to a waiter ranked above 0 (see
2171
+ * `StreamSessionAdmission.offerOnce`), so an ordinary feed keeps exactly the
2172
+ * reconnect path it always had; registering one costs nothing.
2173
+ */
2174
+ joinSessionQueue() {
2175
+ if (this.sessionWaiter || this.degradedReason !== 'session_limit' || !this.persistentRequested)
2176
+ return;
2177
+ // Pausing after a recorder refusal: queue once the pause is over, never
2178
+ // sooner, so an offer cannot reach a feed that would only decline it.
2179
+ if (this.now() < this.retakeNotBeforeMs) {
2180
+ this.rejoinSessionQueueAt(this.retakeNotBeforeMs);
2181
+ return;
2182
+ }
2183
+ const admission = streamAdmissionFor(this.rtspUrl, this.maxStreamSessionsPerSource);
2184
+ if (!admission)
2185
+ return;
2186
+ const generation = this.openGeneration;
2187
+ this.sessionWaiter = admission.addWaiter(this.sessionPriority, (done) => {
2188
+ this.sessionWaiter = null;
2189
+ if (generation !== this.openGeneration) {
2190
+ done();
2191
+ return;
2192
+ }
2193
+ this.retakeSession(admission, done);
2194
+ });
2195
+ }
2196
+ /** Join the queue at `atMs`; one pending rejoin per feed, owned by this open. */
2197
+ rejoinSessionQueueAt(atMs) {
2198
+ if (this.retakeRejoinTimer)
2199
+ clearTimeout(this.retakeRejoinTimer);
2200
+ const generation = this.openGeneration;
2201
+ this.retakeRejoinTimer = setTimeout(() => {
2202
+ this.retakeRejoinTimer = null;
2203
+ if (generation === this.openGeneration)
2204
+ this.joinSessionQueue();
2205
+ }, Math.max(0, atMs - this.now()));
2206
+ if (typeof this.retakeRejoinTimer.unref === 'function')
2207
+ this.retakeRejoinTimer.unref();
2208
+ }
2209
+ /** Disown any queued, pending or running retake: close(), a fresh open(), a shed. */
2210
+ leaveSessionQueue() {
2211
+ this.sessionWaiter?.remove();
2212
+ this.sessionWaiter = null;
2213
+ this.retake = null;
2214
+ if (this.retakeRejoinTimer) {
2215
+ clearTimeout(this.retakeRejoinTimer);
2216
+ this.retakeRejoinTimer = null;
2217
+ }
2218
+ }
2219
+ /**
2220
+ * Take a persistent session for a feed running the per-grab fallback,
2221
+ * WITHOUT a gap: the fallback answers every look until the new session's
2222
+ * first frame, then the session replaces it. A refusal by the recorder
2223
+ * teaches the lane its ceiling exactly as `open()` does and queues the feed
2224
+ * again after a doubling pause; any other failure leaves the feed on the
2225
+ * fallback, like any feed that could not hold a session.
2226
+ */
2227
+ retakeSession(admission, done) {
2228
+ const now = this.now();
2229
+ if (!this.fallback || this.opened || this.degradedReason !== 'session_limit' || this.retake) {
2230
+ done();
2231
+ return;
2232
+ }
2233
+ if (now < this.retakeNotBeforeMs) {
2234
+ // Too soon after a refusal: queue again once the pause is over.
2235
+ this.rejoinSessionQueueAt(this.retakeNotBeforeMs);
2236
+ done();
2237
+ return;
2238
+ }
2239
+ const ticket = admission.tryAcquire(() => this.shedPersistentSession(), this.sessionPriority);
2240
+ if (!ticket) {
2241
+ this.joinSessionQueue();
2242
+ done();
2243
+ return;
1839
2244
  }
2245
+ const generation = this.openGeneration;
2246
+ const token = (this.retakeTokens += 1);
2247
+ this.retake = { token };
2248
+ this.admissionTicket = ticket;
2249
+ this.admission = admission;
2250
+ this.opened = true;
2251
+ this.startingUp = true;
2252
+ this.currentRestartDelay = this.restartDelayMs;
2253
+ this.log('info', `RTSP persistent session retaken ahead of a lower-ranked feed (priority ${this.sessionPriority})`);
2254
+ const owned = () => generation === this.openGeneration && this.retake?.token === token;
2255
+ const outputFailuresBefore = this.segCounters.outputFailures;
2256
+ this.startSession().then(async () => {
2257
+ if (!owned())
2258
+ return; // closed, re-opened or shed meanwhile: they own the cleanup
2259
+ const previous = this.fallback;
2260
+ this.retake = null;
2261
+ this.fallback = null;
2262
+ this.fallbackOpenError = null;
2263
+ this.mode = 'persistent';
2264
+ this.degradedReason = null;
2265
+ this.lastErrorMessage = null;
2266
+ this.startingUp = false;
2267
+ this.retakeBackoffMs = exports.RETAKE_BACKOFF_BASE_MS;
2268
+ this.reconcileRecording();
2269
+ if (previous) {
2270
+ try {
2271
+ await previous.close();
2272
+ }
2273
+ catch {
2274
+ /* the session is already serving; a stuck fallback close cannot undo that */
2275
+ }
2276
+ }
2277
+ }, (err) => {
2278
+ if (!owned())
2279
+ return;
2280
+ this.retake = null;
2281
+ this.startingUp = false;
2282
+ this.opened = false;
2283
+ this.stopProcess();
2284
+ this.releaseSlot();
2285
+ const message = (0, RTSPCameraProvider_1.sanitizeStreamUrlForLog)(err instanceof Error ? err.message : String(err));
2286
+ const recorderRefused = err instanceof RtspStreamStartupError && !err.inputAccepted && err.reason === 'ended';
2287
+ this.log('warn', `RTSP session retake failed; staying on per-grab capture: ${message}`);
2288
+ if (this.segCounters.outputFailures > outputFailuresBefore) {
2289
+ // The recording output failed the session, not the recorder: that
2290
+ // output is paused now, so the next attempt runs without it (open()
2291
+ // grants the same extra attempt).
2292
+ this.joinSessionQueue();
2293
+ }
2294
+ else if (recorderRefused) {
2295
+ admission.learnCeiling(admission.getActive(), message);
2296
+ this.retakeNotBeforeMs = this.now() + this.retakeBackoffMs;
2297
+ this.retakeBackoffMs = Math.min(exports.RETAKE_BACKOFF_MAX_MS, this.retakeBackoffMs * 2);
2298
+ this.rejoinSessionQueueAt(this.retakeNotBeforeMs);
2299
+ }
2300
+ }).finally(done);
1840
2301
  }
1841
2302
  /** The newest frame if it has not been served yet, else null. */
1842
2303
  takeFreshFrame() {
@@ -2235,6 +2696,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2235
2696
  // Present since ffmpeg 5; an older binary gets the bare segment_time.
2236
2697
  minSegDuration: this.ffmpegMajorVersion >= 5,
2237
2698
  audio: this.planAudio(),
2699
+ label: cfg.label,
2238
2700
  };
2239
2701
  if (this.segmentSuspension && this.now() < this.segmentSuspension.untilMs)
2240
2702
  return null;
@@ -2262,6 +2724,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2262
2724
  if (have.dir !== want.dir ||
2263
2725
  have.segmentSeconds !== want.segmentSeconds ||
2264
2726
  have.minSegDuration !== want.minSegDuration ||
2727
+ have.label !== want.label ||
2265
2728
  !sameAudioPlan(have.audio, want.audio)) {
2266
2729
  return false;
2267
2730
  }
@@ -2319,6 +2782,10 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2319
2782
  try {
2320
2783
  fs.mkdirSync(path.join(plan.dir, exports.CLOSED_SEGMENTS_DIRNAME), { recursive: true });
2321
2784
  fs.mkdirSync(workDir, { recursive: true });
2785
+ // The label is on disk before ffmpeg writes a byte, so a crash before the
2786
+ // first anchor still recovers every segment under its own label.
2787
+ if (plan.label)
2788
+ writeFileAtomic(path.join(workDir, SESSION_LABEL_FILE), JSON.stringify({ label: plan.label }));
2322
2789
  }
2323
2790
  catch (err) {
2324
2791
  // A directory we cannot create is the second output's failure, never the
@@ -2552,7 +3019,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2552
3019
  }
2553
3020
  const anchor = this.anchorFor(rec, entry, session.firstFrameAtMs, session.streamInfo);
2554
3021
  const captureStartMs = Math.round(anchor.wallMs + (entry.startSec - anchor.startSec) * 1000);
2555
- const moved = this.moveIntoRing(rec.plan.dir, src, path.basename(rec.workDir), entry, captureStartMs, size, session.streamInfo, false);
3022
+ const moved = this.moveIntoRing(rec.plan.dir, src, path.basename(rec.workDir), entry, captureStartMs, size, session.streamInfo, false, rec.plan.label);
2556
3023
  if (!moved)
2557
3024
  return 'retry';
2558
3025
  rec.closedCount += 1;
@@ -2614,7 +3081,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2614
3081
  if (!rec.anchor)
2615
3082
  return;
2616
3083
  try {
2617
- writeFileAtomic(path.join(rec.workDir, 'anchor.json'), JSON.stringify({ ...rec.anchor, stream }));
3084
+ writeFileAtomic(path.join(rec.workDir, 'anchor.json'), JSON.stringify({ ...rec.anchor, stream, ...(rec.plan.label ? { label: rec.plan.label } : {}) }));
2618
3085
  }
2619
3086
  catch {
2620
3087
  /* recovery falls back to the file's own last write */
@@ -2625,7 +3092,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2625
3092
  * when the move must be retried (Windows refuses to rename a file ffmpeg
2626
3093
  * still holds; the next poll asks again).
2627
3094
  */
2628
- moveIntoRing(dir, src, tag, entry, captureStartMs, bytes, stream, recovered) {
3095
+ moveIntoRing(dir, src, tag, entry, captureStartMs, bytes, stream, recovered, label) {
2629
3096
  const durationMs = Math.max(0, Math.round((entry.endSec - entry.startSec) * 1000));
2630
3097
  // Zero-padded capture start first, so a name sort is a time sort — the
2631
3098
  // ring evicts oldest-first by name.
@@ -2641,6 +3108,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2641
3108
  captureEndMs: captureStartMs + durationMs,
2642
3109
  bytes,
2643
3110
  stream,
3111
+ ...(label ? { label } : {}),
2644
3112
  };
2645
3113
  try {
2646
3114
  fs.mkdirSync(closedDir, { recursive: true });
@@ -2674,7 +3142,9 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2674
3142
  bytes,
2675
3143
  stream,
2676
3144
  recovered,
3145
+ label,
2677
3146
  };
3147
+ this.noteRingFile(dir, file, bytes);
2678
3148
  this.countSegment(segment);
2679
3149
  this.emitSegment(segment);
2680
3150
  return segment;
@@ -2870,6 +3340,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2870
3340
  bytes,
2871
3341
  stream: sidecar.stream,
2872
3342
  recovered: true,
3343
+ label: sidecar.label ?? null,
2873
3344
  };
2874
3345
  this.countSegment(segment);
2875
3346
  this.emitSegment(segment);
@@ -2901,6 +3372,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2901
3372
  const { entries } = parseSegmentListCsv(text);
2902
3373
  let anchor = null;
2903
3374
  let stream = null;
3375
+ let label = null;
2904
3376
  try {
2905
3377
  const raw = JSON.parse(fs.readFileSync(path.join(workDir, 'anchor.json'), 'utf8'));
2906
3378
  if (Number.isFinite(raw?.wallMs) && Number.isFinite(raw?.startSec)) {
@@ -2908,10 +3380,22 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2908
3380
  }
2909
3381
  if (raw?.stream && typeof raw.stream.codec === 'string')
2910
3382
  stream = raw.stream;
3383
+ if (typeof raw?.label === 'string' && SEGMENT_LABEL_RE.test(raw.label))
3384
+ label = raw.label;
2911
3385
  }
2912
3386
  catch {
2913
3387
  anchor = null;
2914
3388
  }
3389
+ if (label === null) {
3390
+ try {
3391
+ const raw = JSON.parse(fs.readFileSync(path.join(workDir, SESSION_LABEL_FILE), 'utf8'));
3392
+ if (typeof raw?.label === 'string' && SEGMENT_LABEL_RE.test(raw.label))
3393
+ label = raw.label;
3394
+ }
3395
+ catch {
3396
+ /* an unlabelled session, or one from before the label file */
3397
+ }
3398
+ }
2915
3399
  const tag = path.basename(workDir);
2916
3400
  let leftBehind = false;
2917
3401
  for (const entry of entries) {
@@ -2929,30 +3413,21 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2929
3413
  const captureStartMs = anchor
2930
3414
  ? Math.round(anchor.wallMs + (entry.startSec - anchor.startSec) * 1000)
2931
3415
  : Math.round(st.mtimeMs - (entry.endSec - entry.startSec) * 1000);
2932
- if (!this.moveIntoRing(dir, src, tag, entry, captureStartMs, st.size, stream, true))
3416
+ if (!this.moveIntoRing(dir, src, tag, entry, captureStartMs, st.size, stream, true, label))
2933
3417
  leftBehind = true;
2934
3418
  }
2935
3419
  if (!leftBehind)
2936
3420
  this.removeWorkDir(workDir, true);
2937
3421
  }
2938
- /**
2939
- * Hold the closed segments to min(ringSeconds x measured bytes/s, 10% of the
2940
- * volume's free bytes), deleting oldest first. A file the OS will not let us
2941
- * delete (Windows, mid-upload) is skipped, never waited on.
2942
- */
2943
- enforceRing() {
2944
- const cfg = this.segmentConfig;
2945
- if (!cfg)
2946
- return;
2947
- const closedDir = path.join(cfg.dir, exports.CLOSED_SEGMENTS_DIRNAME);
3422
+ /** List and stat the ring once; every close until the next rebuild updates the result in memory. */
3423
+ rebuildRingIndex(dir) {
3424
+ const closedDir = path.join(dir, exports.CLOSED_SEGMENTS_DIRNAME);
2948
3425
  let names;
2949
3426
  try {
2950
3427
  names = fs.readdirSync(closedDir).filter((n) => n.toLowerCase().endsWith('.mp4')).sort();
2951
3428
  }
2952
3429
  catch {
2953
- this.segCounters.ringSegments = 0;
2954
- this.segCounters.ringBytes = 0;
2955
- return;
3430
+ names = [];
2956
3431
  }
2957
3432
  const items = [];
2958
3433
  for (const name of names) {
@@ -2964,32 +3439,79 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
2964
3439
  /* delivered and deleted under us */
2965
3440
  }
2966
3441
  }
3442
+ this.ringIndex = { dir, items, rebuiltAtMs: this.now() };
3443
+ return items;
3444
+ }
3445
+ /** A file just moved into `closed/`: keep the index in name (= capture time) order. */
3446
+ noteRingFile(dir, file, bytes) {
3447
+ const index = this.ringIndex;
3448
+ if (!index || index.dir !== dir)
3449
+ return;
3450
+ const items = index.items;
3451
+ if (!items.length || items[items.length - 1].file < file) {
3452
+ items.push({ file, bytes });
3453
+ return;
3454
+ }
3455
+ if (items.some((item) => item.file === file))
3456
+ return;
3457
+ const at = items.findIndex((item) => item.file > file);
3458
+ items.splice(at < 0 ? items.length : at, 0, { file, bytes });
3459
+ }
3460
+ /**
3461
+ * Hold the closed segments to min(ringSeconds x measured bytes/s, the cap),
3462
+ * deleting oldest first. The cap is the caller's `maxBytes` when it set one
3463
+ * (its share of a buffer sized across every feed on the volume), else 10% of
3464
+ * the volume's free bytes. A file the OS will not let us delete (Windows,
3465
+ * mid-upload) is skipped, never waited on; a file already gone (its consumer
3466
+ * delivered and deleted it) leaves the index without counting as evicted.
3467
+ */
3468
+ enforceRing() {
3469
+ const cfg = this.segmentConfig;
3470
+ if (!cfg)
3471
+ return;
3472
+ const index = this.ringIndex;
3473
+ const items = !index || index.dir !== cfg.dir || this.now() - index.rebuiltAtMs >= exports.RING_RESYNC_MS
3474
+ ? this.rebuildRingIndex(cfg.dir)
3475
+ : index.items;
2967
3476
  let total = items.reduce((n, item) => n + item.bytes, 0);
2968
- let remaining = items.length;
2969
3477
  const freeBytes = this.freeBytesFn(cfg.dir);
2970
3478
  const bytesPerSec = this.measuredBytesPerSec();
2971
3479
  const byRing = bytesPerSec === null ? null : Math.floor(cfg.ringSeconds * bytesPerSec);
2972
- const byFree = freeBytes === null ? null : Math.floor(exports.RING_FREE_FRACTION * freeBytes);
3480
+ const byFree = cfg.maxBytes !== null
3481
+ ? cfg.maxBytes
3482
+ : freeBytes === null ? null : Math.floor(exports.RING_FREE_FRACTION * freeBytes);
2973
3483
  const limit = byRing === null ? byFree : byFree === null ? byRing : Math.min(byRing, byFree);
2974
3484
  if (limit !== null) {
2975
- for (const item of items) {
2976
- if (total <= limit)
2977
- break;
3485
+ let i = 0;
3486
+ while (total > limit && i < items.length) {
3487
+ const item = items[i];
3488
+ const metaFile = item.file.replace(/\.mp4$/i, '.json');
2978
3489
  try {
2979
3490
  fs.unlinkSync(item.file);
2980
3491
  }
2981
- catch {
3492
+ catch (err) {
3493
+ if (err?.code === 'ENOENT') {
3494
+ total -= item.bytes;
3495
+ items.splice(i, 1);
3496
+ try {
3497
+ fs.unlinkSync(metaFile);
3498
+ }
3499
+ catch {
3500
+ /* its consumer took both */
3501
+ }
3502
+ continue;
3503
+ }
3504
+ i += 1;
2982
3505
  continue;
2983
3506
  }
2984
- const metaFile = item.file.replace(/\.mp4$/i, '.json');
2985
3507
  try {
2986
3508
  fs.unlinkSync(metaFile);
2987
3509
  }
2988
3510
  catch {
2989
3511
  /* best-effort */
2990
3512
  }
3513
+ items.splice(i, 1);
2991
3514
  total -= item.bytes;
2992
- remaining -= 1;
2993
3515
  this.segCounters.evicted += 1;
2994
3516
  this.segCounters.evictedBytes += item.bytes;
2995
3517
  try {
@@ -3000,7 +3522,7 @@ class RTSPStreamCameraProvider extends events_1.EventEmitter {
3000
3522
  }
3001
3523
  }
3002
3524
  }
3003
- this.segCounters.ringSegments = remaining;
3525
+ this.segCounters.ringSegments = items.length;
3004
3526
  this.segCounters.ringBytes = total;
3005
3527
  this.segCounters.ringLimitBytes = limit;
3006
3528
  this.segCounters.freeBytes = freeBytes;