A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
// SPDX-License-Identifier: AGPL-3.0-or-later
import assert from 'node:assert/strict';
import {isVoiceEngineV2CommandCompletionStale, transitionVoiceEngineV2} from '@fluxer/voice_engine_v2/src/core/reducer';
import {
availableVoiceEngineV2Capabilities,
createVoiceEngineV2InitialSnapshot,
type VoiceEngineV2Snapshot,
type VoiceEngineV2Transition,
} from '@fluxer/voice_engine_v2/src/core/state';
import {
errorToVoiceEngineV2Error,
type VoiceEngineV2CommandResult,
type VoiceEngineV2Implementation,
} from '@fluxer/voice_engine_v2/src/implementations/VoiceEngineV2ImplementationBase';
import {
getVoiceEngineV2CommandResourceKey,
type VoiceEngineV2Command,
} from '@fluxer/voice_engine_v2/src/protocol/commands';
import type {VoiceEngineV2Event} from '@fluxer/voice_engine_v2/src/protocol/events';
import type {
VoiceEngineV2Capabilities,
VoiceEngineV2Error,
VoiceEngineV2ResourceKey,
} from '@fluxer/voice_engine_v2/src/protocol/types';
import {commandResultToEvent} from '@fluxer/voice_engine_v2/src/runtime/commandEvents';
import {
assertEventLogRingInvariants,
VOICE_ENGINE_V2_EVENT_LOG_CAP,
type VoiceEngineV2EventLogEntry,
VoiceEngineV2EventLogRing,
type VoiceEngineV2EventLogSpillSink,
} from '@fluxer/voice_engine_v2/src/runtime/eventLogRing';
import {
canCoalesceVoiceEngineV2Events,
isVoiceEngineV2FrameReceivedEvent,
VOICE_ENGINE_V2_COALESCED_TRACKS_CAP,
} from '@fluxer/voice_engine_v2/src/runtime/frameCoalescing';
import {
createVoiceEngineV2SystemClockPort,
type VoiceEngineV2ClockPort,
} from '@fluxer/voice_engine_v2/src/runtime/platformPort';
export type {
VoiceEngineV2EventLogEntry,
VoiceEngineV2EventLogSpillSink,
} from '@fluxer/voice_engine_v2/src/runtime/eventLogRing';
export const VOICE_ENGINE_V2_QUEUED_COMMANDS_CAP = 4096;
export const VOICE_ENGINE_V2_RESOURCE_QUEUES_CAP = 256;
export const VOICE_ENGINE_V2_CANCELLED_OPERATIONS_CAP = 4096;
export const VOICE_ENGINE_V2_LISTENERS_CAP = 256;
export const VOICE_ENGINE_V2_DIAGNOSTIC_LISTENERS_CAP = 256;
export type VoiceEngineV2RuntimeQueueKind = 'queuedCommands' | 'resourceQueues' | 'cancelledOperations';
export interface VoiceEngineV2RuntimeDiagnostic {
kind: 'voiceEngineV2.queueFull';
queue: VoiceEngineV2RuntimeQueueKind;
cap: number;
droppedCommandType: string;
droppedOperationId: number;
resourceKey: VoiceEngineV2ResourceKey;
}
export type VoiceEngineV2RuntimeDiagnosticListener = (diagnostic: VoiceEngineV2RuntimeDiagnostic) => void;
interface VoiceEngineV2RuntimeListenerPayload {
event: VoiceEngineV2Event;
transition: VoiceEngineV2Transition;
}
export type VoiceEngineV2RuntimeListener = (payload: VoiceEngineV2RuntimeListenerPayload) => void;
export interface VoiceEngineV2RuntimeOptions {
capabilities?: VoiceEngineV2Capabilities;
clock?: VoiceEngineV2ClockPort;
eventLogSpillSink: VoiceEngineV2EventLogSpillSink;
queuedCommandsCap?: number;
resourceQueuesCap?: number;
verifyEventLogInvariantsOnDispatch?: boolean;
}
export function isVoiceEngineV2ProgrammerError(error: unknown): boolean {
if (error instanceof assert.AssertionError) return true;
if (error instanceof Error) {
return (error as Error & {voiceEngineV2ProgrammerError?: unknown}).voiceEngineV2ProgrammerError === true;
}
return false;
}
export class VoiceEngineV2Runtime {
private snapshotValue: VoiceEngineV2Snapshot;
private readonly listeners = new Set<VoiceEngineV2RuntimeListener>();
private readonly diagnosticListeners = new Set<VoiceEngineV2RuntimeDiagnosticListener>();
private readonly unsubscribeImplementationEvents: () => void;
private readonly clock: VoiceEngineV2ClockPort;
private readonly eventLogRing: VoiceEngineV2EventLogRing;
private readonly eventLogSpillSink: VoiceEngineV2EventLogSpillSink;
private readonly queuedCommandsById = new Map<number, VoiceEngineV2Command>();
private readonly resourceQueues = new Map<VoiceEngineV2ResourceKey, Promise<void>>();
private readonly executingCommandsByResource = new Map<VoiceEngineV2ResourceKey, VoiceEngineV2Command>();
private readonly cancelledOperationIds = new Set<number>();
private readonly queuedCommandsCap: number;
private readonly resourceQueuesCap: number;
private readonly verifyEventLogInvariantsOnDispatch: boolean;
private readonly coalesceCandidatesByTrack = new Map<
string,
{sequence: number; snapshotBefore: VoiceEngineV2Snapshot}
>();
private queueFullDropCount = 0;
constructor(
private readonly implementation: VoiceEngineV2Implementation,
options: VoiceEngineV2RuntimeOptions,
) {
this.clock = options.clock ?? createVoiceEngineV2SystemClockPort();
this.eventLogRing = new VoiceEngineV2EventLogRing(VOICE_ENGINE_V2_EVENT_LOG_CAP);
assert.ok(
options.eventLogSpillSink !== null && typeof options.eventLogSpillSink === 'object',
'eventLogSpillSink is required',
);
assert.equal(typeof options.eventLogSpillSink.write, 'function', 'eventLogSpillSink.write must be a function');
this.eventLogSpillSink = options.eventLogSpillSink;
const queuedCommandsCap = options.queuedCommandsCap ?? VOICE_ENGINE_V2_QUEUED_COMMANDS_CAP;
assert.ok(Number.isInteger(queuedCommandsCap), 'queuedCommandsCap must be an integer');
assert.ok(queuedCommandsCap >= 1, 'queuedCommandsCap must be >= 1');
this.queuedCommandsCap = queuedCommandsCap;
const resourceQueuesCap = options.resourceQueuesCap ?? VOICE_ENGINE_V2_RESOURCE_QUEUES_CAP;
assert.ok(Number.isInteger(resourceQueuesCap), 'resourceQueuesCap must be an integer');
assert.ok(resourceQueuesCap >= 1, 'resourceQueuesCap must be >= 1');
this.resourceQueuesCap = resourceQueuesCap;
this.verifyEventLogInvariantsOnDispatch = options.verifyEventLogInvariantsOnDispatch === true;
this.snapshotValue = createVoiceEngineV2InitialSnapshot(
options.capabilities ?? availableVoiceEngineV2Capabilities(),
);
this.unsubscribeImplementationEvents =
implementation.subscribe?.((event) => {
this.dispatch(event);
}) ?? (() => {});
}
get snapshot(): VoiceEngineV2Snapshot {
return this.snapshotValue;
}
get eventLog(): ReadonlyArray<VoiceEngineV2EventLogEntry> {
return this.eventLogRing.snapshotEntries();
}
get droppedEventsCount(): number {
return this.eventLogRing.droppedEventsCount;
}
get commandQueue(): ReadonlyArray<VoiceEngineV2Command> {
return Array.from(this.queuedCommandsById.values());
}
get commandQueueSize(): number {
return this.queuedCommandsById.size;
}
get queueFullDropTotal(): number {
return this.queueFullDropCount;
}
getExecutingCommand(resourceKey: VoiceEngineV2ResourceKey): VoiceEngineV2Command | null {
assert.equal(typeof resourceKey, 'string', 'getExecutingCommand requires a string resourceKey');
assert.ok(resourceKey.length > 0, 'getExecutingCommand requires a non-empty resourceKey');
return this.executingCommandsByResource.get(resourceKey) ?? null;
}
isOperationPending(operationId: number): boolean {
assert.ok(Number.isInteger(operationId), 'isOperationPending requires an integer operationId');
assert.ok(operationId >= 0, 'isOperationPending requires a non-negative operationId');
if (this.queuedCommandsById.has(operationId)) return true;
for (const command of this.executingCommandsByResource.values()) {
if (command.operationId === operationId) return true;
}
return false;
}
subscribe(listener: VoiceEngineV2RuntimeListener): () => void {
assert.equal(typeof listener, 'function', 'subscribe requires a function listener');
this.listeners.add(listener);
assert.ok(this.listeners.size <= VOICE_ENGINE_V2_LISTENERS_CAP, 'runtime listeners exceeded cap');
return () => {
this.listeners.delete(listener);
};
}
subscribeDiagnostics(listener: VoiceEngineV2RuntimeDiagnosticListener): () => void {
assert.equal(typeof listener, 'function', 'subscribeDiagnostics requires a function listener');
this.diagnosticListeners.add(listener);
assert.ok(
this.diagnosticListeners.size <= VOICE_ENGINE_V2_DIAGNOSTIC_LISTENERS_CAP,
'runtime diagnostic listeners exceeded cap',
);
return () => {
this.diagnosticListeners.delete(listener);
};
}
dispatch(event: VoiceEngineV2Event): VoiceEngineV2Transition {
assert.ok(event !== null, 'dispatch requires a non-null event');
assert.equal(typeof event.type, 'string', 'dispatch requires an event with a string type');
const coalescedTransition = this.coalesceFrameReceivedDispatch(event);
if (coalescedTransition !== null) return coalescedTransition;
const snapshotBefore = this.snapshotValue;
const transition = transitionVoiceEngineV2(snapshotBefore, event);
this.snapshotValue = transition.snapshot;
const sequence = this.appendEventLog(event, transition.commands);
this.recordCoalesceCandidate(event, sequence, snapshotBefore);
if (this.verifyEventLogInvariantsOnDispatch) {
this.verifyEventLogInvariants();
}
this.enqueueTransitionCommands(transition.commands);
this.notify(event, transition);
return transition;
}
private coalesceFrameReceivedDispatch(event: VoiceEngineV2Event): VoiceEngineV2Transition | null {
if (!isVoiceEngineV2FrameReceivedEvent(event)) return null;
const candidate = this.coalesceCandidatesByTrack.get(event.frame.trackSid);
if (candidate === undefined) return null;
const tail = this.eventLogRing.tailEntry;
if (tail === null) return null;
if (tail.sequence !== candidate.sequence) return null;
if (tail.commands.length !== 0) return null;
assert.ok(canCoalesceVoiceEngineV2Events(tail.event, event), 'coalesce candidate must match the log tail frame');
const transition = transitionVoiceEngineV2(candidate.snapshotBefore, event);
this.snapshotValue = transition.snapshot;
this.eventLogRing.replaceTail({
sequence: tail.sequence,
atMs: this.clock.now(),
event,
commands: transition.commands,
});
if (this.verifyEventLogInvariantsOnDispatch) {
this.verifyEventLogInvariants();
}
this.enqueueTransitionCommands(transition.commands);
this.notify(event, transition);
return transition;
}
private recordCoalesceCandidate(
event: VoiceEngineV2Event,
sequence: number,
snapshotBefore: VoiceEngineV2Snapshot,
): void {
assert.ok(sequence >= 1, 'recordCoalesceCandidate requires a positive sequence');
if (!isVoiceEngineV2FrameReceivedEvent(event)) return;
const trackSid = event.frame.trackSid;
const alreadyTracked = this.coalesceCandidatesByTrack.delete(trackSid);
if (!alreadyTracked && this.coalesceCandidatesByTrack.size >= VOICE_ENGINE_V2_COALESCED_TRACKS_CAP) {
const oldest = this.coalesceCandidatesByTrack.keys().next();
assert.ok(oldest.done !== true, 'coalesce candidates at cap must yield an evictable track');
this.coalesceCandidatesByTrack.delete(oldest.value);
}
this.coalesceCandidatesByTrack.set(trackSid, {sequence, snapshotBefore});
assert.ok(
this.coalesceCandidatesByTrack.size <= VOICE_ENGINE_V2_COALESCED_TRACKS_CAP,
'coalesce candidates exceeded cap',
);
}
private enqueueTransitionCommands(commands: Array<VoiceEngineV2Command>): void {
const commandsLimit = commands.length;
for (let commandIndex = 0; commandIndex < commandsLimit; commandIndex += 1) {
const command = commands[commandIndex];
assert.ok(command !== undefined, 'command batch must not contain holes');
this.enqueueCommand(command);
}
}
verifyEventLogInvariants(): void {
assertEventLogRingInvariants(this.eventLogRing);
const entries = this.eventLogRing.snapshotEntries();
assert.ok(entries.length <= this.eventLogRing.cap, 'event log size must not exceed cap');
const droppedCount = this.eventLogRing.droppedEventsCount;
assert.ok(droppedCount >= 0, 'dropped count must be non-negative');
const evictedMin = this.eventLogRing.evictedSequenceMin;
if (droppedCount === 0) {
assert.equal(evictedMin, null, 'evicted min must be null when no drops occurred');
}
if (droppedCount > 0) {
assert.ok(evictedMin !== null, 'evicted min must be set when drops occurred');
}
}
dispose(): void {
this.unsubscribeImplementationEvents();
this.listeners.clear();
this.diagnosticListeners.clear();
this.coalesceCandidatesByTrack.clear();
}
private notify(event: VoiceEngineV2Event, transition: VoiceEngineV2Transition): void {
for (const listener of this.listeners) {
listener({event, transition});
}
}
private appendEventLog(event: VoiceEngineV2Event, commands: Array<VoiceEngineV2Command>): number {
const sequence = this.eventLogRing.allocateSequence();
const entry: VoiceEngineV2EventLogEntry = {
sequence,
atMs: this.clock.now(),
event,
commands,
};
const evicted = this.eventLogRing.push(entry);
if (evicted !== null) {
this.spillEvictedEntry(evicted);
}
return sequence;
}
private spillEvictedEntry(entry: VoiceEngineV2EventLogEntry): void {
assert.ok(entry.sequence >= 1, 'evicted entry must have a positive sequence');
const sink = this.eventLogSpillSink;
const writePromise = sink.write(entry);
assert.ok(writePromise !== null, 'event log spill sink must return a promise');
void writePromise.catch((error: unknown) => {
const normalisedError = errorToVoiceEngineV2Error(error);
queueMicrotask(() => {
throw new Error(
`voice engine v2 event log spill sink rejected sequence ${entry.sequence}: ${normalisedError.code}: ${normalisedError.message}`,
);
});
});
}
private enqueueCommand(command: VoiceEngineV2Command): void {
assert.ok(command !== undefined, 'enqueueCommand requires a non-undefined command');
assert.equal(typeof command.type, 'string', 'enqueueCommand requires a string command type');
const resourceKey = getVoiceEngineV2CommandResourceKey(command);
if (this.queuedCommandsById.size >= this.queuedCommandsCap) {
this.rejectCommandAtQueueCap('queuedCommands', this.queuedCommandsCap, command, resourceKey);
return;
}
const alreadyTracked = this.resourceQueues.has(resourceKey);
if (!alreadyTracked && this.resourceQueues.size >= this.resourceQueuesCap) {
this.rejectCommandAtQueueCap('resourceQueues', this.resourceQueuesCap, command, resourceKey);
return;
}
this.queuedCommandsById.set(command.operationId, command);
assert.ok(this.queuedCommandsById.size <= this.queuedCommandsCap, 'queuedCommands push exceeded cap');
const previous = this.resourceQueues.get(resourceKey) ?? Promise.resolve();
const next = previous.then(
() => this.executeQueuedCommand(command),
() => this.executeQueuedCommand(command),
);
this.resourceQueues.set(resourceKey, next);
assert.ok(this.resourceQueues.size <= this.resourceQueuesCap, 'resourceQueues set exceeded cap');
void next.finally(() => {
if (this.resourceQueues.get(resourceKey) === next) {
this.resourceQueues.delete(resourceKey);
}
});
}
private async executeQueuedCommand(command: VoiceEngineV2Command): Promise<void> {
this.consumeQueuedCommand(command);
if (this.cancelledOperationIds.has(command.operationId)) {
this.cancelledOperationIds.delete(command.operationId);
return;
}
const resourceKey = getVoiceEngineV2CommandResourceKey(command);
assert.ok(!this.executingCommandsByResource.has(resourceKey), 'resource queues execute one command at a time');
this.executingCommandsByResource.set(resourceKey, command);
assert.ok(
this.executingCommandsByResource.size <= this.resourceQueuesCap,
'executing commands exceeded resource queue cap',
);
try {
const result = await this.executeCommand(command);
if (isVoiceEngineV2CommandCompletionStale(this.snapshotValue, command)) {
this.dispatch({
type: 'command.staleCompletionRejected',
operationId: command.operationId,
commandType: command.type,
resourceKey,
});
return;
}
this.dispatch(commandResultToEvent(command, result));
} catch (error) {
if (isVoiceEngineV2ProgrammerError(error)) throw error;
this.dispatchTerminalFailure(command, error);
} finally {
if (this.executingCommandsByResource.get(resourceKey) === command) {
this.executingCommandsByResource.delete(resourceKey);
}
}
}
private async executeCommand(command: VoiceEngineV2Command): Promise<VoiceEngineV2CommandResult> {
try {
return await this.implementation.execute(command);
} catch (error) {
return {ok: false, error: errorToVoiceEngineV2Error(error)};
}
}
private consumeQueuedCommand(command: VoiceEngineV2Command): void {
assert.ok(command !== undefined, 'consumeQueuedCommand requires a command');
this.queuedCommandsById.delete(command.operationId);
assert.ok(
!this.queuedCommandsById.has(command.operationId),
'consumeQueuedCommand postcondition: id must not remain',
);
}
cancelOperation(operationId: number): void {
assert.ok(Number.isInteger(operationId), 'cancelOperation requires an integer operationId');
assert.ok(operationId >= 0, 'cancelOperation requires a non-negative operationId');
if (this.cancelledOperationIds.has(operationId)) return;
if (this.cancelledOperationIds.size >= VOICE_ENGINE_V2_CANCELLED_OPERATIONS_CAP) {
const oldest = this.cancelledOperationIds.values().next();
assert.ok(oldest.done !== true, 'cancelledOperationIds at cap must yield an evictable id');
this.cancelledOperationIds.delete(oldest.value);
this.emitCancelledOperationEvictionDiagnostic(oldest.value);
}
this.cancelledOperationIds.add(operationId);
assert.ok(this.cancelledOperationIds.has(operationId), 'cancelledOperationIds insert postcondition');
assert.ok(
this.cancelledOperationIds.size <= VOICE_ENGINE_V2_CANCELLED_OPERATIONS_CAP,
'cancelledOperationIds exceeded cap',
);
}
get cancelledOperationCount(): number {
return this.cancelledOperationIds.size;
}
private emitDiagnostic(diagnostic: VoiceEngineV2RuntimeDiagnostic): void {
assert.equal(diagnostic.kind, 'voiceEngineV2.queueFull', 'emitDiagnostic requires a known diagnostic kind');
assert.ok(diagnostic.cap >= 1, 'emitDiagnostic requires a positive cap');
for (const listener of this.diagnosticListeners) {
listener(diagnostic);
}
}
private emitCancelledOperationEvictionDiagnostic(evictedOperationId: number): void {
assert.ok(Number.isInteger(evictedOperationId), 'evicted cancellation id must be an integer');
assert.ok(!this.cancelledOperationIds.has(evictedOperationId), 'evicted cancellation id must be removed first');
const queuedCommand = this.queuedCommandsById.get(evictedOperationId) ?? null;
this.emitDiagnostic({
kind: 'voiceEngineV2.queueFull',
queue: 'cancelledOperations',
cap: VOICE_ENGINE_V2_CANCELLED_OPERATIONS_CAP,
droppedCommandType: queuedCommand === null ? 'operation.cancel' : queuedCommand.type,
droppedOperationId: evictedOperationId,
resourceKey: queuedCommand === null ? 'lifecycle' : getVoiceEngineV2CommandResourceKey(queuedCommand),
});
}
private rejectCommandAtQueueCap(
queue: VoiceEngineV2RuntimeQueueKind,
cap: number,
command: VoiceEngineV2Command,
resourceKey: VoiceEngineV2ResourceKey,
): void {
assert.ok(cap >= 1, 'rejectCommandAtQueueCap requires a positive cap');
assert.equal(typeof command.type, 'string', 'rejectCommandAtQueueCap requires a command type');
this.queueFullDropCount += 1;
this.emitDiagnostic({
kind: 'voiceEngineV2.queueFull',
queue,
cap,
droppedCommandType: command.type,
droppedOperationId: command.operationId,
resourceKey,
});
const overflowError: VoiceEngineV2Error = {
code: 'implementationError',
message: `Voice engine v2 command rejected: ${queue} queue overflow at cap ${cap}`,
};
queueMicrotask(() => {
if (isVoiceEngineV2CommandCompletionStale(this.snapshotValue, command)) {
this.dispatch({
type: 'command.staleCompletionRejected',
operationId: command.operationId,
commandType: command.type,
resourceKey,
});
return;
}
this.dispatchTerminalFailure(command, overflowError);
});
}
private dispatchTerminalFailure(command: VoiceEngineV2Command, error: unknown): void {
assert.ok(command !== undefined, 'dispatchTerminalFailure requires a command');
const normalised = errorToVoiceEngineV2Error(error);
const failureEvent = commandResultToEvent(command, {ok: false, error: normalised});
try {
this.dispatch(failureEvent);
} catch (cascadeError) {
const cascade = errorToVoiceEngineV2Error(cascadeError);
queueMicrotask(() => {
throw new Error(
`voice engine v2 terminal failure dispatch cascaded for operationId ${command.operationId} (${command.type}): ${cascade.code}: ${cascade.message}`,
);
});
}
}
}
export function assertEventLogInvariants(runtime: VoiceEngineV2Runtime): void {
assert.ok(runtime instanceof VoiceEngineV2Runtime, 'assertEventLogInvariants requires a runtime instance');
runtime.verifyEventLogInvariants();
}