From aca0b9b14e7d013e017506dfc4e25b90498f5cc6 Mon Sep 17 00:00:00 2001 From: pablop Date: Wed, 11 Nov 2026 12:33:17 +0100 Subject: [PATCH] feat(collaboration): add event-driven drainCapReports, deprecate buildCapReport Add SFVCapReportEmitter, which emits a CAP report on stall edges, video switches and playable-buffer changes of at least 1.0 s, rate-limited to one report per second of session time per UE. Changes suppressed by the rate limit are coalesced into the next allowed report. The final drain bypasses the rate limit so terminal state is not lost. Both controllers expose drainCapReports(timeS, { final }). The per-call snapshot buildCapReport is kept unchanged and marked deprecated. Co-authored-by: Cursor --- src/core/SFVCapReport.js | 50 ++++++++- src/dashjs/SFVBrowserController.js | 16 ++- src/simulation/SFVSimulationController.js | 21 +++- test/cap-report.test.js | 120 ++++++++++++++++++++-- 4 files changed, 192 insertions(+), 15 deletions(-) diff --git a/src/core/SFVCapReport.js b/src/core/SFVCapReport.js index 319e42b..4b57982 100644 --- a/src/core/SFVCapReport.js +++ b/src/core/SFVCapReport.js @@ -1,10 +1,14 @@ /** * VQEG CAP telemetry report (pilot ``CapReport`` / ``cap_reports`` IPC). - * Co-sim today: one snapshot per collaboration tick; event-driven 1/s is future work. + * Reports are event-driven: ``SFVCapReportEmitter`` emits on stall edges, video switches and + * buffer threshold crossings, at most once per ``minIntervalS`` of session time per UE. */ const EPS = 1e-8; +export const DEFAULT_CAP_BUFFER_DELTA_S = 1.0; +export const DEFAULT_CAP_MIN_INTERVAL_S = 1.0; + export function countSwipesInWindow(userEvents, timeS, windowS = 1, eps = EPS) { if (!Array.isArray(userEvents)) return 0; return userEvents.filter( @@ -60,3 +64,47 @@ export function buildCapReportFromSession({ timeS, playback, userEvents = [], sw swipe_rate_per_s: countSwipesInWindow(userEvents, timeS, swipeWindowS) }); } + +/** + * Per-UE CAP report gate. Changes are compared with the last emitted report, so a transition + * suppressed by the rate limit is emitted (coalesced) at the first poll after the window reopens. + */ +export class SFVCapReportEmitter { + constructor({ + bufferDeltaS = DEFAULT_CAP_BUFFER_DELTA_S, + minIntervalS = DEFAULT_CAP_MIN_INTERVAL_S + } = {}) { + if (!Number.isFinite(bufferDeltaS) || bufferDeltaS <= 0) { + throw new TypeError('SFVCapReportEmitter: bufferDeltaS must be positive'); + } + if (!Number.isFinite(minIntervalS) || minIntervalS < 0) { + throw new TypeError('SFVCapReportEmitter: minIntervalS must be non-negative'); + } + this.bufferDeltaS = bufferDeltaS; + this.minIntervalS = minIntervalS; + this.lastReport = null; + } + + hasTransition(report) { + const last = this.lastReport; + if (last == null) return true; + return ( + report.is_stalled !== last.is_stalled || + report.current_video_id !== last.current_video_id || + Math.abs(report.playable_buffer_s - last.playable_buffer_s) >= this.bufferDeltaS - EPS + ); + } + + /** Returns the report to emit, or null. ``force`` bypasses the rate limit (final drain). */ + poll(report, { force = false } = {}) { + if (!this.hasTransition(report)) return null; + if ( + !force && + this.lastReport != null && + report.time_s - this.lastReport.time_s < this.minIntervalS - EPS + ) + return null; + this.lastReport = report; + return report; + } +} diff --git a/src/dashjs/SFVBrowserController.js b/src/dashjs/SFVBrowserController.js index 84ec80a..61cdf63 100644 --- a/src/dashjs/SFVBrowserController.js +++ b/src/dashjs/SFVBrowserController.js @@ -14,7 +14,7 @@ import { normalizeSchedulingConfig } from '../core/SFVConfig.js'; import { ACTION, MANIFEST_STATE } from '../core/constants.js'; import { SFVSessionRecordBuilder } from '../output/SFVSessionRecordBuilder.js'; import { cspFieldsEqual, normalizeCspFields } from '../core/SFVCspFields.js'; -import { buildCapReportFromSession } from '../core/SFVCapReport.js'; +import { SFVCapReportEmitter, buildCapReportFromSession } from '../core/SFVCapReport.js'; /** One browser feed/UE; B1 and B2 run unmodified against the same rules context as DES. */ export class SFVBrowserController { @@ -114,6 +114,7 @@ export class SFVBrowserController { this.seekPending = false; this.listeners = []; this.cspFields = null; + this.capEmitter = new SFVCapReportEmitter(this.config.capReport ?? {}); this.#bindPlaybackEvents(); } time() { @@ -138,6 +139,10 @@ export class SFVBrowserController { return this.cspFields == null ? null : structuredClone(this.cspFields); } + /** + * VQEG CAP report snapshot at ``timeS``, built on every call. + * @deprecated Use ``drainCapReports``, which only returns a report when one is due. + */ buildCapReport(timeS = this.time()) { return buildCapReportFromSession({ timeS, @@ -146,6 +151,15 @@ export class SFVBrowserController { }); } + /** Pending VQEG CAP reports (0 or 1) since the last drain; see ``SFVCapReportEmitter``. */ + drainCapReports(timeS = this.time(), { final = false } = {}) { + const report = this.capEmitter.poll( + buildCapReportFromSession({ timeS, playback: this.playback, userEvents: this.userEvents }), + { force: final } + ); + return report == null ? [] : [report]; + } + #observe(event) { if (this.stopped) return; const e = this.abr.observe({ ...event, time: event.time ?? this.time() }); diff --git a/src/simulation/SFVSimulationController.js b/src/simulation/SFVSimulationController.js index 67295ca..078071a 100644 --- a/src/simulation/SFVSimulationController.js +++ b/src/simulation/SFVSimulationController.js @@ -15,7 +15,7 @@ import { normalizeSchedulingConfig } from '../core/SFVConfig.js'; import { resolveSessionTiming } from './SFVSessionTiming.js'; import { resolveUserInteractions, resolveCapacityGenerator } from './generators/SFVGenerators.js'; import { cspFieldsEqual, normalizeCspFields } from '../core/SFVCspFields.js'; -import { buildCapReportFromSession } from '../core/SFVCapReport.js'; +import { SFVCapReportEmitter, buildCapReportFromSession } from '../core/SFVCapReport.js'; export class SFVSimulationController { constructor({ dataset, rule, config = {}, transport = null, requestIdPrefix = 'r' }) { @@ -122,6 +122,7 @@ export class SFVSimulationController { this.sampleStart = null; this.lastObservedPlaybackPosition = 0; this.cspFields = null; + this.capEmitter = new SFVCapReportEmitter(this.config.capReport ?? {}); this.requestManager = new SFVRequestManager({ catalog: this.catalog, @@ -302,7 +303,10 @@ export class SFVSimulationController { return this.cspFields == null ? null : structuredClone(this.cspFields); } - /** VQEG ``cap_reports`` payload for one UE at ``timeS`` (pilot co-sim: per network step). */ + /** + * VQEG ``cap_reports`` snapshot for one UE at ``timeS``, built on every call. + * @deprecated Use ``drainCapReports``, which only returns a report when one is due. + */ buildCapReport(timeS = this.clock.now()) { return buildCapReportFromSession({ timeS, @@ -311,6 +315,19 @@ export class SFVSimulationController { }); } + /** + * Pending VQEG ``cap_reports`` for this UE since the last drain (0 or 1 reports). Event-driven + * via ``SFVCapReportEmitter``: stall edges, video switches and buffer threshold crossings, at + * most one per second of session time. ``final`` flushes pending state past the rate limit. + */ + drainCapReports(timeS = this.clock.now(), { final = false } = {}) { + const report = this.capEmitter.poll( + buildCapReportFromSession({ timeS, playback: this.playback, userEvents: this.userEvents }), + { force: final } + ); + return report == null ? [] : [report]; + } + stopQueuedRequests(timeS, sessionEnded) { return this.requestManager.stopQueued(timeS, sessionEnded); } diff --git a/test/cap-report.test.js b/test/cap-report.test.js index eb8536c..cf80ba4 100644 --- a/test/cap-report.test.js +++ b/test/cap-report.test.js @@ -1,11 +1,25 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { buildCapReportFromSession } from '../src/core/SFVCapReport.js'; +import { + DEFAULT_CAP_BUFFER_DELTA_S, + SFVCapReportEmitter, + buildCapReportFromSession +} from '../src/core/SFVCapReport.js'; import { SFVSimulationController } from '../src/simulation/SFVSimulationController.js'; import { SFVCurrentVideoRule } from '../src/rules/SFVCurrentVideoRule.js'; +function report(timeS, { stalled = false, bufferS = 3, videoId = 'v1' } = {}) { + return Object.freeze({ + time_s: timeS, + is_stalled: stalled, + playable_buffer_s: bufferS, + current_video_id: videoId, + swipe_rate_per_s: 0 + }); +} + test('buildCapReportFromSession matches pilot co-sim snapshot fields', () => { - const report = buildCapReportFromSession({ + const snapshot = buildCapReportFromSession({ timeS: 1.0, playback: { videoId: 'v1', @@ -15,14 +29,47 @@ test('buildCapReportFromSession matches pilot co-sim snapshot fields', () => { }, userEvents: [{ eventType: 'SWIPE', time: 0.5 }] }); - assert.equal(report.time_s, 1); - assert.equal(report.is_stalled, true); - assert.equal(report.playable_buffer_s, 3); - assert.equal(report.current_video_id, 'v1'); - assert.equal(report.swipe_rate_per_s, 1); + assert.equal(snapshot.time_s, 1); + assert.equal(snapshot.is_stalled, true); + assert.equal(snapshot.playable_buffer_s, 3); + assert.equal(snapshot.current_video_id, 'v1'); + assert.equal(snapshot.swipe_rate_per_s, 1); +}); + +test('emitter emits first report and ignores steady state', () => { + const emitter = new SFVCapReportEmitter(); + assert.equal(DEFAULT_CAP_BUFFER_DELTA_S, 1.0); + assert.ok(emitter.poll(report(0))); + assert.equal(emitter.poll(report(2, { bufferS: 3 + DEFAULT_CAP_BUFFER_DELTA_S / 2 })), null); + assert.ok(emitter.poll(report(3, { bufferS: 3 + DEFAULT_CAP_BUFFER_DELTA_S }))); +}); + +test('emitter emits on stall edges and video switches', () => { + const emitter = new SFVCapReportEmitter(); + emitter.poll(report(0)); + assert.equal(emitter.poll(report(1.5, { stalled: true }))?.is_stalled, true); + assert.equal(emitter.poll(report(3, { stalled: false }))?.is_stalled, false); + assert.equal(emitter.poll(report(4.5, { videoId: 'v2' }))?.current_video_id, 'v2'); }); -test('SFVSimulationController.buildCapReport delegates to core helper', () => { +test('emitter rate-limits to one report per second and coalesces suppressed changes', () => { + const emitter = new SFVCapReportEmitter(); + emitter.poll(report(0)); + assert.equal(emitter.poll(report(0.4, { stalled: true })), null); + assert.equal(emitter.poll(report(0.9, { stalled: true })), null); + const late = emitter.poll(report(1.0, { stalled: true })); + assert.equal(late?.time_s, 1.0); + assert.equal(late?.is_stalled, true); +}); + +test('emitter force bypasses the rate limit but not the change check', () => { + const emitter = new SFVCapReportEmitter(); + emitter.poll(report(0)); + assert.equal(emitter.poll(report(0.2), { force: true }), null); + assert.equal(emitter.poll(report(0.3, { stalled: true }), { force: true })?.is_stalled, true); +}); + +test('SFVSimulationController.drainCapReports emits once until state changes', () => { const dataset = { videos: [ { @@ -39,7 +86,58 @@ test('SFVSimulationController.buildCapReport delegates to core helper', () => { config: { sessionStartTimeS: 0, sessionEndTimeS: 6, swipeTimesS: [] } }); controller.startAt(0); - const report = controller.buildCapReport(0.01); - assert.equal(report.current_video_id, 'v1'); - assert.equal(typeof report.playable_buffer_s, 'number'); + const [first, ...rest] = controller.drainCapReports(0.01); + assert.equal(rest.length, 0); + assert.equal(first.current_video_id, 'v1'); + assert.equal(typeof first.playable_buffer_s, 'number'); + assert.deepEqual(controller.drainCapReports(0.02), []); + // Deprecated snapshot API still answers on every call and does not consume pending state. + assert.equal(controller.buildCapReport(0.03).current_video_id, 'v1'); + assert.deepEqual(controller.drainCapReports(0.04), []); +}); + +test('SFVSimulationController.drainCapReports reports an induced stall within the rate limit', () => { + const segments = Array.from({ length: 6 }, (_, index) => ({ + index, + startS: index, + durationS: 1 + })); + const dataset = { + videos: [ + { + videoId: 'v1', + representations: { video: [{ id: 'r0', bitrateKbps: 4000, segments }] } + } + ] + }; + const controller = new SFVSimulationController({ + dataset, + rule: new SFVCurrentVideoRule(), + config: { + sessionStartTimeS: 0, + sessionEndTimeS: 20, + maxTimeS: 20, + swipeTimesS: [], + transport: { capacityMbps: 2, latencyMs: 0 } + } + }); + controller.startAt(0); + const stepS = 0.05; + const reports = []; + let drains = 0; + for (let t = stepS; t <= 12 + 1e-9; t += stepS) { + controller.advancePlaybackTo(t); + for (const event of controller.transport.advanceTo(t)) controller.applyNetworkEvent(event); + controller.decideAtEpoch(); + reports.push(...controller.drainCapReports(t)); + drains++; + } + assert.ok( + reports.some(r => r.is_stalled), + 'expected at least one stalled CAP report' + ); + assert.ok(reports.length < drains / 5, `${reports.length} reports for ${drains} drains`); + for (let i = 1; i < reports.length; i++) { + assert.ok(reports[i].time_s - reports[i - 1].time_s >= 1 - 1e-8, 'rate limit violated'); + } });