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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ required for the default simulations.
- [Architecture](docs/reference/sfv_reference_architecture_summary.md): implementation boundaries and shared execution rules.
- [Technical plan](docs/reference/sfv_technical_implementation_plan.md): implemented functionality and current work items.
- [Validation](docs/VALIDATION.md): repeatable scenarios, distinct replay and independent-prediction claims, and cache tests.
- [Co-simulation](docs/CO_SIMULATION.md): run SFV sessions against an external network simulator over JSON lines.

The included media fixtures and dash.js-derived patch need a separate
provenance/licensing review before redistribution. Raw browser recordings,
Expand Down
82 changes: 82 additions & 0 deletions docs/CO_SIMULATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Co-simulation with an external network

An external harness can run SFV sessions against its own network simulator, for example the [VQEG CAP–CSP collaboration pilot](https://github.com/VQEG/cap-csp-collaboration-test-pilot) with the FikoRE 5G emulator. The harness owns simulation time and byte delivery. SFV owns playback, ABR decisions, swipes and session records.

The harness starts `scripts/cosim-network-step-worker.mjs` as a child process and exchanges one JSON object per line on stdin and stdout. Every request gets exactly one reply. A failure is answered with `{"type": "error", "message": "..."}` and leaves the process running.

## Components

The worker wraps two classes in `src/cosim/`, both exported from `src/index.js`:

- `SFVNetworkStepHarness` runs one `SFVSimulationController` per UE on a shared clock, applies each network step to all UEs, collects their network actions, and drains CAP reports.
- `SFVExternalTransport` is the transport of each controller. It turns requests and aborts into `submit_request` and `cancel_request` actions and keeps the media metadata of each request on the player side. The external network only sees an opaque request ID and a byte count.

## Messages

`initialize` creates the harness and is answered with `{"type": "initialized"}`:

```json
{
"type": "initialize",
"config": {
"dataset": { "videos": [] },
"sessions": [
{
"ue_id": 0,
"player_behavior": "simple",
"config": { "sessionStartTimeS": 0, "sessionEndTimeS": 30 },
"rule_config": {}
}
],
"timingDefaults": {},
"duration_s": 30,
"network_backend": "transport_fikore",
"run_id": "example",
"signaling_level": "L0",
"condition": "C1",
"swipe_profile": "scripted"
}
}
```

`player_behavior` selects `SFVCurrentVideoRule` (`simple`, B1) or `SFVMultiVideoPrefetchRule` (`preload`, B2). `duration_s` and `network_backend` are required.

`network_step` advances all sessions to `step.time_s` and applies the step's download events. The first step must be at `t = 0`, times must increase, and the step with `is_final: true` must be at `duration_s`:

```json
{
"type": "network_step",
"step": {
"time_s": 0.5,
"is_final": false,
"events": [
{
"event_type": "DownloadProgress",
"ue_id": 0,
"request_id": "ue0-r1",
"time_s": 0.5,
"bytes_delivered": 12000
}
],
"collaboration": { "csp_by_ue": { "0": { "plan_downlink_mbps": 10 } } }
}
}
```

Event types are `DownloadProgress` and `DownloadCancelled` (with cumulative `bytes_delivered`) and `DownloadCompleted`. The optional `collaboration.csp_by_ue` object carries the CSP fields each UE may see at the current signaling level. The harness passes them to `applyCspUpdate` only when a UE's fields change.

A non-final step is answered with the network actions to execute before the next step:

```json
{
"type": "player_actions",
"actions": [
{ "op": "submit_request", "ue_id": 0, "request_id": "ue0-r2", "bytes_total": 52129 },
{ "op": "cancel_request", "ue_id": 0, "request_id": "ue0-r1" }
]
}
```

The final step is answered with `{"type": "player_step_result", "actions": [], "result": {...}}`, where `result.sessions` holds the session record of each UE. Requests still open at that point are recorded as cancelled.

`cap_reports` is answered with `{"type": "cap_reports", "reports": {"0": {...}}}`. A UE appears only when `drainCapReports` has a report due: on a stall edge, a video switch or a buffer change of at least 1.0 s, at most once per second of session time. After the final step the rate limit does not apply, so the terminal state is always reported.
28 changes: 28 additions & 0 deletions scripts/cosim-network-step-worker.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
#!/usr/bin/env node
// Co-simulation player process: one JSON message per line on stdin, one reply per line on stdout.
// The protocol is described in docs/CO_SIMULATION.md.
import readline from 'node:readline';
import { SFVNetworkStepHarness } from '../src/cosim/SFVNetworkStepHarness.js';

const input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
let harness;
for await (const line of input) {
try {
const message = JSON.parse(line);
let reply;
if (message.type === 'initialize') {
if (harness) throw new Error('Player already initialized');
harness = new SFVNetworkStepHarness(message.config);
reply = { type: 'initialized' };
} else if (!harness) throw new Error('Player not initialized');
else if (message.type === 'network_step') reply = harness.onStep(message.step);
else if (message.type === 'cap_reports')
reply = { type: 'cap_reports', reports: harness.getCapReports() };
else throw new Error(`Unknown IPC message ${message.type}`);
process.stdout.write(JSON.stringify(reply) + '\n');
} catch (error) {
process.stdout.write(
JSON.stringify({ type: 'error', message: String(error.message ?? error) }) + '\n'
);
}
}
152 changes: 152 additions & 0 deletions src/cosim/SFVExternalTransport.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
import { REQUEST_STATE } from '../core/constants.js';

const ID = /^[A-Za-z0-9_.-]{1,64}$/;

/** The player-facing transport knows only the generic NetworkBackend contract.
* Media metadata stays in this registry; only opaque request identifiers and byte
* counts are returned to the external harness. It never advances global time.
*/
export class SFVExternalTransport {
constructor({ ue_id, queueAction, now }) {
if (
!Number.isSafeInteger(ue_id) ||
ue_id < 0 ||
typeof queueAction !== 'function' ||
typeof now !== 'function'
) {
throw new TypeError('Invalid external transport configuration');
}
this.ue_id = ue_id;
this.queueAction = queueAction;
this.now = now;
this.requests = new Map();
this.used = new Set();
}

start(request, now = this.now()) {
const { requestId, bytesTotal } = request;
if (
!ID.test(requestId) ||
this.used.has(requestId) ||
!Number.isSafeInteger(bytesTotal) ||
bytesTotal <= 0
) {
throw new TypeError('Invalid or reused player request ID');
}
const entry = {
...structuredClone(request),
state: REQUEST_STATE.ACTIVE,
startTime: now,
firstByteTime: null,
endTime: null,
bytesDelivered: 0,
finalBytesDelivered: null,
abortRequestedAt: null,
bytesDeliveredAtAbort: null
};
this.used.add(requestId);
this.requests.set(requestId, entry);
this.queueAction({
op: 'submit_request',
ue_id: this.ue_id,
request_id: requestId,
bytes_total: bytesTotal
});
return structuredClone(entry);
}

abort(requestId, now = this.now()) {
const request = this.requests.get(requestId);
if (!request || ![REQUEST_STATE.ACTIVE, REQUEST_STATE.CANCELLING].includes(request.state))
return false;
if (request.state === REQUEST_STATE.CANCELLING) return true;
request.state = REQUEST_STATE.CANCELLING;
request.abortRequestedAt = now;
request.bytesDeliveredAtAbort = request.bytesDelivered;
this.queueAction({ op: 'cancel_request', ue_id: this.ue_id, request_id: requestId });
return true;
}

get(requestId) {
const entry = this.requests.get(requestId);
return entry ? structuredClone(entry) : null;
}

list() {
return [...this.requests.values()].map(entry => structuredClone(entry));
}

/** Apply an event from NetworkStep; completion and cancellation are terminal. */
receiveEvent(event, dispatch) {
const { event_type: kind, request_id: requestId, time_s: time } = event;
const entry = this.requests.get(requestId);
if (!entry || ![REQUEST_STATE.ACTIVE, REQUEST_STATE.CANCELLING].includes(entry.state)) {
throw new Error(`Unknown or terminal network request ${requestId}`);
}
if (kind === 'DownloadProgress') {
this.#progress(entry, event.bytes_delivered, time, dispatch);
} else if (kind === 'DownloadCompleted') {
this.#progress(entry, entry.bytesTotal, time, dispatch);
entry.state = REQUEST_STATE.COMPLETED;
entry.endTime = time;
entry.finalBytesDelivered = entry.bytesTotal;
dispatch({ eventType: 'REQUEST_COMPLETED', requestId, time, totalBytes: entry.bytesTotal });
} else if (kind === 'DownloadCancelled') {
if (entry.state !== REQUEST_STATE.CANCELLING)
throw new Error(`Unexpected cancellation of ${requestId}`);
this.#progress(entry, event.bytes_delivered, time, dispatch);
entry.state = REQUEST_STATE.CANCELLED;
entry.endTime = time;
entry.finalBytesDelivered = event.bytes_delivered;
dispatch({
eventType: 'REQUEST_CANCELLED',
requestId,
time,
totalBytes: event.bytes_delivered
});
} else {
throw new Error(`Unsupported request event ${kind}`);
}
}

#progress(entry, amount, time, dispatch) {
if (
!Number.isSafeInteger(amount) ||
amount < entry.bytesDelivered ||
amount > entry.bytesTotal
) {
throw new Error(`Invalid cumulative bytes for ${entry.requestId}`);
}
const delta = amount - entry.bytesDelivered;
if (delta && entry.firstByteTime === null) {
entry.firstByteTime = time;
dispatch({ eventType: 'REQUEST_FIRST_BYTE', requestId: entry.requestId, time });
}
entry.bytesDelivered = amount;
if (delta)
dispatch({
eventType: 'REQUEST_PROGRESS',
requestId: entry.requestId,
time,
deltaBytes: delta,
totalBytes: amount
});
}

finish(time) {
const events = [];
for (const entry of this.requests.values()) {
if (![REQUEST_STATE.ACTIVE, REQUEST_STATE.CANCELLING].includes(entry.state)) continue;
entry.state = REQUEST_STATE.CANCELLED;
entry.endTime = time;
entry.finalBytesDelivered = entry.bytesDelivered;
events.push({
eventType: 'REQUEST_CANCELLED',
requestId: entry.requestId,
time,
totalBytes: entry.bytesDelivered
});
}
return events;
}
}
Loading
Loading