Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion src/core/SFVCapReport.js
Original file line number Diff line number Diff line change
@@ -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(
Expand Down Expand Up @@ -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;
}
}
16 changes: 15 additions & 1 deletion src/dashjs/SFVBrowserController.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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() {
Expand All @@ -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,
Expand All @@ -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() });
Expand Down
21 changes: 19 additions & 2 deletions src/simulation/SFVSimulationController.js
Original file line number Diff line number Diff line change
Expand Up @@ -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' }) {
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand All @@ -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);
}
Expand Down
120 changes: 109 additions & 11 deletions test/cap-report.test.js
Original file line number Diff line number Diff line change
@@ -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',
Expand All @@ -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: [
{
Expand All @@ -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');
}
});
Loading