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'); + } });