@blockcast/mmt-base 0.1.0

package/src/alfec.test.ts

@@ -0,0 +1,176 @@
+/** Strict ISO/IEC 23008-1:2023/Amd 1:2025 Table C.3 RaptorQ signaling. */
+import { describe, expect, it } from "vitest";
+import { MMTP_HEADER_SIZE, parseAlFecMessage } from "./mmtp.js";
+
+function concat(...parts: Uint8Array[]): Uint8Array {
+	const output = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		output.set(part, offset);
+		offset += part.length;
+	}
+	return output;
+}
+
+function u16(value: number): Uint8Array {
+	return Uint8Array.of((value >>> 8) & 0xff, value & 0xff);
+}
+
+function u24(value: number): Uint8Array {
+	return Uint8Array.of((value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+}
+
+function u32(value: number): Uint8Array {
+	return Uint8Array.of(
+		(value >>> 24) & 0xff,
+		(value >>> 16) & 0xff,
+		(value >>> 8) & 0xff,
+		value & 0xff,
+	);
+}
+
+function raptorqOti(k: number, symbolSize: number, reserved = 0): Uint8Array {
+	const transferLength = k * symbolSize;
+	return Uint8Array.of(
+		Math.floor(transferLength / 0x1_0000_0000) & 0xff,
+		(transferLength >>> 24) & 0xff,
+		(transferLength >>> 16) & 0xff,
+		(transferLength >>> 8) & 0xff,
+		transferLength & 0xff,
+		reserved,
+		(symbolSize >>> 8) & 0xff,
+		symbolSize & 0xff,
+		1,
+		0,
+		1,
+		8,
+	);
+}
+
+function buildAlFecMessage(options: {
+	symbolSize?: number;
+	k?: number;
+	maximumK?: number;
+	p?: number;
+	depth?: number;
+	codingParams?: number;
+	otiReserved?: number;
+	repairFlowIdWidth?: 1 | 2;
+} = {}): Uint8Array {
+	const symbolSize = options.symbolSize ?? 1312;
+	const k = options.k ?? 10;
+	const maximumK = options.maximumK ?? k;
+	const p = options.p ?? 2;
+	const depth = options.depth ?? 4;
+	const oti = raptorqOti(k, symbolSize, options.otiReserved);
+	const repairFlowId = options.repairFlowIdWidth === 1
+		? Uint8Array.of(0)
+		: u16(0);
+	const descriptor = concat(
+		Uint8Array.of(
+			1, // number_of_fec_flows
+			0, // fec_flow_id
+			0, // source_flow_id
+			1, // number_of_assets
+		),
+		u16(1), // packet_id
+		Uint8Array.of(options.codingParams ?? 0x10), // one-stage, ssbg0, no FFSRP, payload-ID mode 0
+		u16(symbolSize),
+		repairFlowId,
+		Uint8Array.of(2), // RaptorQ fec_code_id
+		Uint8Array.of(0x80 | 13), // private_flag + exact OTI/depth length
+		oti,
+		Uint8Array.of(depth),
+		u24(maximumK),
+		u24(p),
+		u32(1_000_000),
+		u32(k * symbolSize),
+	);
+	const messagePayload = concat(Uint8Array.of(0xff), u16(descriptor.length), descriptor);
+	return concat(
+		u16(0x0203),
+		Uint8Array.of(1),
+		u16(messagePayload.length),
+		messagePayload,
+	);
+}
+
+function asMulticastPacket(message: Uint8Array, byte1 = 0x02): Uint8Array {
+	const packet = new Uint8Array(MMTP_HEADER_SIZE + message.length);
+	packet[1] = byte1;
+	packet.set(message, MMTP_HEADER_SIZE);
+	return packet;
+}
+
+describe("parseAlFecMessage", () => {
+	it("parses the exact current one-stage RaptorQ profile", () => {
+		const config = parseAlFecMessage(asMulticastPacket(buildAlFecMessage()));
+		expect(config).not.toBeNull();
+		expect(config).toEqual({
+			fecCodeId: 2,
+			fecPayloadIdMode: 0,
+			repairSymbolSize: 1312,
+			maximumK: 10,
+			maximumP: 2,
+			interleaveDepth: 4,
+			oti: raptorqOti(10, 1312),
+		});
+	});
+
+	it.each([64, 1280, 1312, 1320])("accepts canonical Al=8 symbol size %i", symbolSize => {
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ symbolSize }),
+		))?.repairSymbolSize).toBe(symbolSize);
+	});
+
+	it("rejects the pre-amendment 8-bit repair_flow_id encoding", () => {
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ repairFlowIdWidth: 1 }),
+		))).toBeNull();
+	});
+
+	it("rejects unsupported FEC payload ID mode 1", () => {
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ codingParams: 0x11 }),
+		))).toBeNull();
+	});
+
+	it("rejects inferred or mismatched decoder geometry", () => {
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ depth: 0 }),
+		))).toBeNull();
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ otiReserved: 1 }),
+		))).toBeNull();
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ maximumK: 11 }),
+		))).toBeNull();
+		expect(parseAlFecMessage(asMulticastPacket(
+			buildAlFecMessage({ symbolSize: 1310 }),
+		))).toBeNull();
+	});
+
+	it("requires exact message and descriptor boundaries", () => {
+		const wrongMessageLength = buildAlFecMessage();
+		wrongMessageLength[4] = wrongMessageLength[4]! - 1;
+		expect(parseAlFecMessage(asMulticastPacket(wrongMessageLength))).toBeNull();
+
+		const wrongDescriptorLength = buildAlFecMessage();
+		wrongDescriptorLength[7] = wrongDescriptorLength[7]! - 1;
+		expect(parseAlFecMessage(asMulticastPacket(wrongDescriptorLength))).toBeNull();
+
+		const trailing = concat(buildAlFecMessage(), Uint8Array.of(0));
+		expect(parseAlFecMessage(asMulticastPacket(trailing))).toBeNull();
+	});
+
+	it("rejects the pre-migration high-bit packet_type encoding", () => {
+		expect(parseAlFecMessage(asMulticastPacket(buildAlFecMessage(), 0x08))).toBeNull();
+	});
+
+	it("never throws on truncated input", () => {
+		const packet = asMulticastPacket(buildAlFecMessage());
+		for (let length = 0; length < packet.length; length++) {
+			expect(() => parseAlFecMessage(packet.subarray(0, length))).not.toThrow();
+		}
+	});
+});

package/src/index.ts

@@ -0,0 +1 @@
+export * from './mmtp.js'