@stream-io/video-client 1.54.1-beta.0 → 1.55.1

package/src/stats/rtc/Tracer.ts

@@ -9,11 +9,13 @@ import type {
 export class Tracer {
   private buffer: TraceRecord[] = [];
   private enabled = true;
-  private readonly id: string | null;
+  readonly id: string | null;
+  private readonly maxBuffer: number;
   private keys?: Map<TraceKey, boolean>;
 
-  constructor(id: string | null) {
+  constructor(id: string | null, maxBuffer: number = 2500) {
     this.id = id;
+    this.maxBuffer = maxBuffer;
   }
 
   setEnabled = (enabled: boolean) => {
@@ -25,6 +27,7 @@ export class Tracer {
   trace: Trace = (tag, data) => {
     if (!this.enabled) return;
     this.buffer.push([tag, this.id, data, Date.now()]);
+    this.capBuffer();
   };
 
   traceOnce = (key: TraceKey, tag: string, data: RTCStatsDataType) => {
@@ -44,6 +47,7 @@ export class Tracer {
       snapshot,
       rollback: () => {
         this.buffer.unshift(...snapshot);
+        this.capBuffer();
       },
     };
   };
@@ -52,4 +56,21 @@ export class Tracer {
     this.buffer = [];
     this.keys?.clear();
   };
+
+  /**
+   * Bounds the buffer to 2500 records by dropping the oldest ones,
+   * leaving a single `traceBufferOverflow` breadcrumb at the front so the
+   * consumer knows records were dropped.
+   */
+  private capBuffer = () => {
+    const overflow = this.buffer.length - this.maxBuffer;
+    if (overflow <= 0) return;
+    this.buffer.splice(0, overflow);
+    this.buffer[0] = [
+      'traceBufferOverflow',
+      this.id,
+      { dropped: overflow },
+      Date.now(),
+    ];
+  };
 }

package/src/stats/rtc/__tests__/StatsTracer.test.ts

@@ -43,7 +43,8 @@ describe('StatsTracer timestamp drift correction', () => {
       THRESHOLD_MS,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     expect(delta.timestamp).toBe(WALL_NOW + 2000);
   });
@@ -60,7 +61,8 @@ describe('StatsTracer timestamp drift correction', () => {
       THRESHOLD_MS,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     expect(delta.timestamp).toBe(WALL_NOW);
   });
@@ -77,7 +79,8 @@ describe('StatsTracer timestamp drift correction', () => {
       THRESHOLD_MS,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     expect(delta['b'].timestamp).toBe(WALL_NOW);
     expect(delta.timestamp).toBe(WALL_NOW + 2000);
@@ -95,7 +98,8 @@ describe('StatsTracer timestamp drift correction', () => {
       THRESHOLD_MS,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     expect(delta.timestamp).toBe(WALL_NOW + THRESHOLD_MS);
   });
@@ -127,7 +131,8 @@ describe('StatsTracer timestamp drift correction', () => {
       THRESHOLD_MS,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     // both stale and future drift get clamped to wall time, while the
     // within-threshold anchor stays the delta's top-level timestamp.
@@ -148,8 +153,210 @@ describe('StatsTracer timestamp drift correction', () => {
       0,
     );
 
-    const { delta } = await tracer.get();
+    await tracer.takeSample();
+    const { delta } = tracer.getPendingDeltas().at(-1)!;
 
     expect(delta.timestamp).toBe(WALL_NOW + 99_999);
   });
 });
+
+// Builds an RTCStatsReport from rich per-report fields (id is added for you).
+const richReport = (
+  entries: Record<string, Record<string, unknown>>,
+): RTCStatsReport => {
+  const map = new Map<string, RTCStats>();
+  for (const [id, fields] of Object.entries(entries)) {
+    map.set(id, { id, ...fields } as unknown as RTCStats);
+  }
+  return map as unknown as RTCStatsReport;
+};
+
+// A pc mock whose getStats() returns a different report on each successive call.
+const makeSeqPc = (reports: RTCStatsReport[]): RTCPeerConnection => {
+  const getStats = vi.fn();
+  for (const r of reports) getStats.mockResolvedValueOnce(r);
+  return { getStats } as unknown as RTCPeerConnection;
+};
+
+// Mirrors the server-side accumulator: applies chained deltas in order,
+// un-zeroing each report's hoisted timestamp.
+const applyChain = (
+  baseline: Record<string, any>,
+  deltas: Array<Record<string, any>>,
+): Record<string, any> => {
+  const acc: Record<string, any> = JSON.parse(JSON.stringify(baseline));
+  for (const delta of deltas) {
+    const top = delta.timestamp;
+    for (const [id, report] of Object.entries(delta)) {
+      if (id === 'timestamp') continue;
+      const target = (acc[id] ??= {});
+      for (const [k, v] of Object.entries(report as Record<string, unknown>)) {
+        target[k] = k === 'timestamp' && v === 0 ? top : v;
+      }
+    }
+  }
+  return acc;
+};
+
+describe('StatsTracer pending delta chain', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(WALL_NOW);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('accumulates one delta per get() in the pending chain', async () => {
+    const pc = makeSeqPc([
+      makeReport([{ id: 'a', timestamp: WALL_NOW }]),
+      makeReport([{ id: 'a', timestamp: WALL_NOW + 1000 }]),
+    ]);
+    const tracer = new StatsTracer(pc, PeerType.SUBSCRIBER, new Map(), 0);
+
+    await tracer.takeSample();
+    await tracer.takeSample();
+
+    expect(tracer.getPendingDeltas()).toHaveLength(2);
+  });
+
+  it('commitDeltas removes exactly the committed deltas by identity', async () => {
+    const pc = makeSeqPc([
+      makeReport([{ id: 'a', timestamp: WALL_NOW }]),
+      makeReport([{ id: 'a', timestamp: WALL_NOW + 1000 }]),
+    ]);
+    const tracer = new StatsTracer(pc, PeerType.SUBSCRIBER, new Map(), 0);
+
+    await tracer.takeSample();
+    await tracer.takeSample();
+    const sent = tracer.getPendingDeltas();
+    tracer.commitDeltas(sent.slice(0, 1));
+
+    const remaining = tracer.getPendingDeltas();
+    expect(remaining).toHaveLength(1);
+    expect(remaining[0]).toBe(sent[1]);
+  });
+
+  it('clearPendingDeltas empties the chain', async () => {
+    const pc = makeSeqPc([
+      makeReport([{ id: 'a', timestamp: WALL_NOW }]),
+      makeReport([{ id: 'a', timestamp: WALL_NOW + 1000 }]),
+    ]);
+    const tracer = new StatsTracer(pc, PeerType.SUBSCRIBER, new Map(), 0);
+
+    await tracer.takeSample();
+    await tracer.takeSample();
+    tracer.clearPendingDeltas();
+
+    expect(tracer.getPendingDeltas()).toHaveLength(0);
+  });
+
+  it('reconstructs every sample by applying the un-acked chain in order', async () => {
+    const s0 = richReport({ a: { timestamp: WALL_NOW, bytes: 100 } });
+    const s1 = richReport({ a: { timestamp: WALL_NOW + 1000, bytes: 200 } });
+    const s2 = richReport({ a: { timestamp: WALL_NOW + 2000, bytes: 350 } });
+    const tracer = new StatsTracer(
+      makeSeqPc([s0, s1, s2]),
+      PeerType.SUBSCRIBER,
+      new Map(),
+      0,
+    );
+
+    await tracer.takeSample();
+    await tracer.takeSample();
+    await tracer.takeSample();
+    const chain = tracer.getPendingDeltas().map((p) => p.delta);
+
+    expect(applyChain({}, chain)).toEqual({
+      a: { timestamp: WALL_NOW + 2000, bytes: 350 },
+    });
+  });
+
+  it('re-anchors with a full snapshot when the chain exceeds the cap', async () => {
+    const s0 = richReport({ a: { timestamp: WALL_NOW, bytes: 100 } });
+    const s1 = richReport({ a: { timestamp: WALL_NOW + 1000, bytes: 200 } });
+    const s2 = richReport({ a: { timestamp: WALL_NOW + 2000, bytes: 350 } });
+    const tracer = new StatsTracer(
+      makeSeqPc([s0, s1, s2]),
+      PeerType.SUBSCRIBER,
+      new Map(),
+      0,
+      2, // maxPendingDeltas
+    );
+
+    await tracer.takeSample();
+    await tracer.takeSample(); // chain now at the cap
+    await tracer.takeSample(); // exceeds cap -> re-anchor
+
+    const chain = tracer.getPendingDeltas();
+    expect(chain).toHaveLength(1);
+    // the single re-anchored delta is a full snapshot of S2
+    expect(applyChain({}, [chain[0].delta])).toEqual({
+      a: { timestamp: WALL_NOW + 2000, bytes: 350 },
+    });
+  });
+
+  it('keeps a re-anchored keyframe when a stale commit lands afterwards', async () => {
+    const s0 = richReport({ a: { timestamp: WALL_NOW, bytes: 100 } });
+    const s1 = richReport({ a: { timestamp: WALL_NOW + 1000, bytes: 200 } });
+    const s2 = richReport({ a: { timestamp: WALL_NOW + 2000, bytes: 350 } });
+    const tracer = new StatsTracer(
+      makeSeqPc([s0, s1, s2]),
+      PeerType.SUBSCRIBER,
+      new Map(),
+      0,
+      2,
+    );
+
+    await tracer.takeSample();
+    await tracer.takeSample();
+    const sent = tracer.getPendingDeltas(); // captured before re-anchor
+    await tracer.takeSample(); // re-anchors, dropping `sent`
+    tracer.commitDeltas(sent); // stale commit, must be a no-op
+
+    expect(tracer.getPendingDeltas()).toHaveLength(1);
+  });
+});
+
+const deferred = <T>() => {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+};
+
+describe('StatsTracer concurrent sampling', () => {
+  it('serializes overlapping get() calls so the chain stays in call order', async () => {
+    const dA = deferred<RTCStatsReport>();
+    const dB = deferred<RTCStatsReport>();
+    const getStats = vi
+      .fn()
+      .mockReturnValueOnce(dA.promise)
+      .mockReturnValueOnce(dB.promise);
+    const pc = { getStats } as unknown as RTCPeerConnection;
+    const tracer = new StatsTracer(pc, PeerType.SUBSCRIBER, new Map(), 0);
+
+    const pA = tracer.takeSample();
+    const pB = tracer.takeSample();
+
+    // the second sample must not start until the first completes
+    expect(getStats).toHaveBeenCalledTimes(1);
+
+    // resolve the first sample; only then should the second getStats fire
+    dA.resolve(richReport({ a: { timestamp: 1000, bytes: 100 } }));
+    await pA;
+    expect(getStats).toHaveBeenCalledTimes(2);
+
+    dB.resolve(richReport({ a: { timestamp: 2000, bytes: 200 } }));
+    await pB;
+
+    // chain applied in call order reconstructs the second (newer) sample
+    const chain = tracer.getPendingDeltas().map((p) => p.delta);
+    expect(chain).toHaveLength(2);
+    expect(applyChain({}, chain)).toEqual({
+      a: { timestamp: 2000, bytes: 200 },
+    });
+  });
+});

package/src/stats/rtc/__tests__/Tracer.test.ts

@@ -54,4 +54,38 @@ describe('Tracer', () => {
     const slice = tracer.take();
     expect(slice.snapshot.length).toBe(0);
   });
+
+  it('exposes its id via .id', () => {
+    expect(new Tracer('abc').id).toBe('abc');
+    expect(new Tracer(null).id).toBeNull();
+  });
+
+  it('caps the buffer, dropping oldest and leaving an overflow marker', () => {
+    const capped = new Tracer('id', 3);
+    capped.trace('e', { n: 1 });
+    capped.trace('e', { n: 2 });
+    capped.trace('e', { n: 3 });
+    capped.trace('e', { n: 4 }); // overflows the cap of 3
+
+    const slice = capped.take();
+    expect(slice.snapshot.length).toBe(3);
+    expect(slice.snapshot[0][0]).toBe('traceBufferOverflow');
+    // newest record is retained
+    expect(slice.snapshot[slice.snapshot.length - 1][2]).toEqual({ n: 4 });
+  });
+
+  it('caps the buffer on rollback too', () => {
+    const capped = new Tracer('id', 3);
+    capped.trace('e', { n: 1 });
+    const slice = capped.take();
+
+    capped.trace('e', { n: 2 });
+    capped.trace('e', { n: 3 });
+    capped.trace('e', { n: 4 }); // buffer now at the cap of 3
+    slice.rollback(); // prepends the old record, exceeding the cap
+
+    const after = capped.take();
+    expect(after.snapshot.length).toBe(3);
+    expect(after.snapshot[0][0]).toBe('traceBufferOverflow');
+  });
 });

package/src/stats/rtc/types.ts

@@ -40,12 +40,19 @@ export type ComputedStats = {
    * Current stats from the RTCPeerConnection.
    */
   stats: RTCStatsReport;
-  /**
-   * Delta between the current stats and the previous stats.
-   */
-  delta: Record<any, any>;
   /**
    * The current iteration of the stats.
    */
   performanceStats: PerformanceStats[];
 };
+
+/**
+ * A single, not-yet-delivered delta-compressed stats sample.
+ * The `delta` is computed against the immediately preceding sample, so a
+ * sequence of `PendingDelta`s forms a chain that the server applies in order
+ * onto its running accumulator. `ts` is the wall-clock time the sample was taken.
+ */
+export type PendingDelta = {
+  delta: Record<any, any>;
+  ts: number;
+};