Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
9.0 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import assert from 'node:assert/strict';
import type {VoiceEngineV2Command} from '@fluxer/voice_engine_v2/src/protocol/commands';
import type {VoiceEngineV2Event} from '@fluxer/voice_engine_v2/src/protocol/events';

export const VOICE_ENGINE_V2_EVENT_LOG_CAP = 4096;

export interface VoiceEngineV2EventLogEntry {
	sequence: number;
	atMs: number;
	event: VoiceEngineV2Event;
	commands: Array<VoiceEngineV2Command>;
}

export interface VoiceEngineV2EventLogSpillSink {
	write(entry: VoiceEngineV2EventLogEntry): Promise<void>;
}

const VOICE_ENGINE_V2_MEMORY_EVENT_LOG_SPILL_SINK_CAP = 8192;

export interface VoiceEngineV2MemoryEventLogSpillSink extends VoiceEngineV2EventLogSpillSink {
	readonly entries: ReadonlyArray<VoiceEngineV2EventLogEntry>;
	readonly droppedEntriesCount: number;
}

export function createVoiceEngineV2MemoryEventLogSpillSink(
	capacity: number = VOICE_ENGINE_V2_MEMORY_EVENT_LOG_SPILL_SINK_CAP,
): VoiceEngineV2MemoryEventLogSpillSink {
	assert.ok(Number.isInteger(capacity), 'memory event log spill sink capacity must be an integer');
	assert.ok(capacity >= 1, 'memory event log spill sink capacity must be at least 1');
	assert.ok(capacity <= 1_048_576, 'memory event log spill sink capacity must fit within a sane upper bound');
	const entries: Array<VoiceEngineV2EventLogEntry> = [];
	let droppedEntriesCount = 0;
	return {
		get entries(): ReadonlyArray<VoiceEngineV2EventLogEntry> {
			return entries.slice();
		},
		get droppedEntriesCount(): number {
			assert.ok(droppedEntriesCount >= 0, 'memory event log spill sink dropped count must be non-negative');
			return droppedEntriesCount;
		},
		write(entry: VoiceEngineV2EventLogEntry): Promise<void> {
			assert.ok(entry !== null && typeof entry === 'object', 'memory event log spill entry must be an object');
			assert.ok(Number.isInteger(entry.sequence), 'memory event log spill entry sequence must be an integer');
			assert.ok(entry.sequence >= 1, 'memory event log spill entry sequence must be >= 1');
			if (entries.length === capacity) {
				entries.shift();
				droppedEntriesCount += 1;
			}
			entries.push(entry);
			assert.ok(entries.length <= capacity, 'memory event log spill sink entries must stay bounded');
			return Promise.resolve();
		},
	};
}

export class VoiceEngineV2EventLogRing {
	private readonly capacity: number;
	private readonly slots: Array<VoiceEngineV2EventLogEntry | null>;
	private headSlot = 0;
	private storedCount = 0;
	private nextSequenceValue = 1;
	private droppedCount = 0;
	private evictedSequenceMinValue: number | null = null;

	constructor(capacity: number = VOICE_ENGINE_V2_EVENT_LOG_CAP) {
		assert.ok(Number.isInteger(capacity), 'event log capacity must be an integer');
		assert.ok(capacity >= 1, 'event log capacity must be at least 1');
		assert.ok(capacity <= 1_048_576, 'event log capacity must fit within a sane upper bound');
		this.capacity = capacity;
		this.slots = new Array<VoiceEngineV2EventLogEntry | null>(capacity).fill(null);
	}

	get size(): number {
		assert.ok(this.storedCount >= 0, 'stored count cannot be negative');
		assert.ok(this.storedCount <= this.capacity, 'stored count cannot exceed capacity');
		return this.storedCount;
	}

	get cap(): number {
		assert.ok(this.capacity >= 1, 'capacity must remain >= 1');
		return this.capacity;
	}

	get nextSequence(): number {
		assert.ok(this.nextSequenceValue >= 1, 'next sequence must remain >= 1');
		return this.nextSequenceValue;
	}

	get droppedEventsCount(): number {
		assert.ok(this.droppedCount >= 0, 'dropped count cannot be negative');
		return this.droppedCount;
	}

	get evictedSequenceMin(): number | null {
		if (this.droppedCount === 0)
			assert.equal(this.evictedSequenceMinValue, null, 'eviction min must be null when nothing dropped');
		if (this.droppedCount > 0)
			assert.ok(this.evictedSequenceMinValue !== null, 'eviction min must be set when drops occurred');
		return this.evictedSequenceMinValue;
	}

	allocateSequence(): number {
		const sequence = this.nextSequenceValue;
		assert.ok(sequence >= 1, 'allocated sequence must be >= 1');
		this.nextSequenceValue = sequence + 1;
		return sequence;
	}

	push(entry: VoiceEngineV2EventLogEntry): VoiceEngineV2EventLogEntry | null {
		assert.ok(Number.isInteger(entry.sequence), 'entry sequence must be an integer');
		assert.ok(entry.sequence >= 1, 'entry sequence must be >= 1');
		assert.equal(entry.sequence + 1, this.nextSequenceValue, 'entry sequence must match allocated sequence');
		let evicted: VoiceEngineV2EventLogEntry | null = null;
		if (this.storedCount === this.capacity) {
			evicted = this.evictOldest();
		}
		const insertIndex = (this.headSlot + this.storedCount) % this.capacity;
		assert.equal(this.slots[insertIndex], null, 'insert slot must be empty before writing');
		this.slots[insertIndex] = entry;
		this.storedCount += 1;
		assert.ok(this.storedCount <= this.capacity, 'stored count must remain bounded by capacity');
		return evicted;
	}

	get tailEntry(): VoiceEngineV2EventLogEntry | null {
		assert.ok(this.storedCount >= 0, 'stored count cannot be negative');
		if (this.storedCount === 0) return null;
		const tailIndex = (this.headSlot + this.storedCount - 1) % this.capacity;
		const entry = this.slots[tailIndex];
		assert.ok(entry !== null, 'tail slot must contain an entry when entries are stored');
		assert.ok(entry !== undefined, 'tail slot index must stay within the slot array');
		return entry;
	}

	replaceTail(entry: VoiceEngineV2EventLogEntry): void {
		assert.ok(this.storedCount >= 1, 'replaceTail requires at least one stored entry');
		const tailIndex = (this.headSlot + this.storedCount - 1) % this.capacity;
		const current = this.slots[tailIndex];
		assert.ok(current !== null, 'tail slot must contain an entry before replacement');
		assert.ok(current !== undefined, 'tail slot index must stay within the slot array');
		assert.equal(entry.sequence, current.sequence, 'replaceTail must preserve the tail sequence');
		this.slots[tailIndex] = entry;
	}

	snapshotEntries(): ReadonlyArray<VoiceEngineV2EventLogEntry> {
		assert.ok(this.storedCount <= this.capacity, 'stored count must remain bounded by capacity');
		const result: Array<VoiceEngineV2EventLogEntry> = new Array<VoiceEngineV2EventLogEntry>(this.storedCount);
		const limit = this.storedCount;
		for (let cursor = 0; cursor < limit; cursor += 1) {
			const slotIndex = (this.headSlot + cursor) % this.capacity;
			const entry = this.slots[slotIndex];
			assert.ok(entry !== null, 'snapshotEntries must not encounter empty slots within stored range');
			result[cursor] = entry;
		}
		return result;
	}

	clear(): void {
		assert.ok(this.capacity >= 1, 'capacity must remain >= 1 before clearing');
		const limit = this.capacity;
		for (let index = 0; index < limit; index += 1) {
			this.slots[index] = null;
		}
		this.headSlot = 0;
		this.storedCount = 0;
		this.nextSequenceValue = 1;
		this.droppedCount = 0;
		this.evictedSequenceMinValue = null;
		assert.equal(this.storedCount, 0, 'clear must leave stored count at zero');
		assert.equal(this.nextSequenceValue, 1, 'clear must reset the sequence allocator to one');
	}

	private evictOldest(): VoiceEngineV2EventLogEntry {
		assert.equal(this.storedCount, this.capacity, 'evictOldest must only run when full');
		const head = this.slots[this.headSlot];
		assert.ok(head !== null, 'head slot must contain an entry when evicting');
		this.slots[this.headSlot] = null;
		this.headSlot = (this.headSlot + 1) % this.capacity;
		this.storedCount -= 1;
		this.droppedCount += 1;
		if (this.evictedSequenceMinValue === null) {
			this.evictedSequenceMinValue = head.sequence;
		}
		assert.ok(this.droppedCount >= 1, 'dropped count must be >= 1 after eviction');
		return head;
	}
}

export function assertEventLogRingInvariants(ring: VoiceEngineV2EventLogRing): void {
	const entries = ring.snapshotEntries();
	const observedSize = entries.length;
	assert.equal(observedSize, ring.size, 'ring size must match snapshot length');
	assert.ok(observedSize <= ring.cap, 'ring size must remain bounded by cap');
	const droppedCount = ring.droppedEventsCount;
	const evictedMin = ring.evictedSequenceMin;
	if (droppedCount === 0) {
		assert.equal(evictedMin, null, 'no drops implies evicted min is null');
	}
	if (droppedCount > 0) {
		assert.ok(evictedMin !== null, 'drops imply evicted min is set');
		assert.equal(evictedMin, 1, 'oldest evicted sequence must be 1 because sequences start at 1 and drop oldest');
	}
	if (observedSize >= 1) {
		const firstSequence = entries[0]?.sequence ?? 0;
		const lastSequence = entries[observedSize - 1]?.sequence ?? 0;
		assert.equal(lastSequence - firstSequence + 1, observedSize, 'sequences must form a contiguous window');
		const expectedFirstSequence = droppedCount + 1;
		assert.equal(firstSequence, expectedFirstSequence, 'first sequence must equal dropped count + 1');
		const cursorLimit = observedSize;
		for (let cursor = 1; cursor < cursorLimit; cursor += 1) {
			const previousSequence = entries[cursor - 1]?.sequence ?? 0;
			const currentSequence = entries[cursor]?.sequence ?? 0;
			assert.equal(currentSequence, previousSequence + 1, 'sequences must increase by exactly one across the window');
		}
	}
}