@blockcast/mmt-transport 0.2.0 → 0.2.2

package/src/endpoint-config.ts

@@ -0,0 +1,121 @@
+export type MulticastTransportPreference = "auto" | "native" | "tunnel";
+
+export interface MulticastEndpointConfig {
+	groupAddress: string;
+	sourceAddress?: string;
+	port: number;
+	mode?: MulticastTransportPreference;
+	amtRelay?: string;
+	amtRelayPort?: number;
+}
+
+export function isValidMulticastGroupAddress(address: string | undefined): boolean {
+	const value = address?.trim().toLowerCase();
+	if (!value) return false;
+	if (value.startsWith("ff")) return isValidIpv6MulticastAddress(value);
+
+	const parts = value.split(".");
+	if (parts.length !== 4) return false;
+	const octets = parts.map((part) => {
+		if (!/^\d+$/.test(part)) return Number.NaN;
+		const octet = Number(part);
+		return Number.isInteger(octet) && octet >= 0 && octet <= 255 ? octet : Number.NaN;
+	});
+	return octets.every(Number.isInteger) && octets[0] >= 224 && octets[0] <= 239;
+}
+
+export function normalizeMulticastEndpoint(
+	endpoint: MulticastEndpointConfig,
+): MulticastEndpointConfig | undefined {
+	const groupAddress = endpoint.groupAddress.trim().toLowerCase();
+	const sourceAddress = endpoint.sourceAddress?.trim().toLowerCase() || undefined;
+	const amtRelay = endpoint.amtRelay?.trim().toLowerCase() || undefined;
+	if (!isValidMulticastGroupAddress(groupAddress) || !isPositivePort(endpoint.port)) return undefined;
+	if (endpoint.mode && !["auto", "native", "tunnel"].includes(endpoint.mode)) return undefined;
+	if (endpoint.amtRelayPort !== undefined && !isPositivePort(endpoint.amtRelayPort)) return undefined;
+
+	return {
+		groupAddress,
+		...(sourceAddress ? { sourceAddress } : {}),
+		port: endpoint.port,
+		...(endpoint.mode ? { mode: endpoint.mode } : {}),
+		...(amtRelay ? { amtRelay } : {}),
+		...(endpoint.amtRelayPort ? { amtRelayPort: endpoint.amtRelayPort } : {}),
+	};
+}
+
+/** Stable ownership key for one IWA multicast/AMT subscription. */
+export function multicastEndpointKey(endpoint: MulticastEndpointConfig): string {
+	const normalized = normalizeMulticastEndpoint(endpoint);
+	if (!normalized) throw new Error("Invalid multicast endpoint");
+	return JSON.stringify([
+		normalized.sourceAddress ?? "",
+		normalized.groupAddress,
+		normalized.port,
+		normalized.mode ?? "auto",
+		normalized.amtRelay ?? "",
+		normalized.amtRelayPort ?? "",
+	]);
+}
+
+export function isUsableMulticastEndpoint(
+	endpoint: { groupAddress?: string; port?: unknown } | undefined,
+): boolean {
+	const port = Number(endpoint?.port);
+	return isValidMulticastGroupAddress(endpoint?.groupAddress) && isPositivePort(port);
+}
+
+export function readUrlMulticastConfig(
+	search: string | URLSearchParams = typeof location === "undefined" ? "" : location.search,
+): MulticastEndpointConfig | undefined {
+	const params = typeof search === "string" ? new URLSearchParams(search) : search;
+	const groupAddress = params.get("mc_group") || "";
+	const port = positivePort(params.get("mc_port"));
+	if (!groupAddress || !port) return undefined;
+
+	const amtRelay = params.get("mc_amt_relay") || params.get("amt_relay") || undefined;
+	const amtRelayPort = positivePort(params.get("mc_amt_relay_port") || params.get("amt_relay_port"));
+	const requestedMode = params.get("mc_mode");
+	const mode = amtRelay ? "tunnel" : multicastMode(requestedMode);
+
+	return normalizeMulticastEndpoint({
+		groupAddress,
+		sourceAddress: params.get("mc_source") || undefined,
+		port,
+		...(mode ? { mode } : {}),
+		...(amtRelay ? { amtRelay } : {}),
+		...(amtRelayPort ? { amtRelayPort } : {}),
+	});
+}
+
+export function isMulticastExplicitlyDisabled(
+	search: string | URLSearchParams = typeof location === "undefined" ? "" : location.search,
+): boolean {
+	const params = typeof search === "string" ? new URLSearchParams(search) : search;
+	const multicast = params.get("multicast")?.trim().toLowerCase();
+	const transport = params.get("transport")?.trim().toLowerCase();
+	return transport === "moq-only" || ["0", "false", "no", "off"].includes(multicast || "");
+}
+
+function isValidIpv6MulticastAddress(value: string): boolean {
+	if (!/^[0-9a-f:]+$/.test(value)) return false;
+	const compressed = value.includes("::");
+	if (value.indexOf("::") !== value.lastIndexOf("::")) return false;
+	const groups = value.split(":").filter(Boolean);
+	if (groups.length === 0 || groups.length > 8) return false;
+	if (!compressed && groups.length !== 8) return false;
+	return groups.every((group) => /^[0-9a-f]{1,4}$/.test(group));
+}
+
+function multicastMode(value: string | null): MulticastTransportPreference | undefined {
+	return value === "native" || value === "tunnel" || value === "auto" ? value : undefined;
+}
+
+function positivePort(value: string | null): number | undefined {
+	const port = Number(value);
+	return isPositivePort(port) ? port : undefined;
+}
+
+function isPositivePort(port: number): boolean {
+	return Number.isInteger(port) && port > 0 && port <= 65535;
+}

package/src/fec-client.ts

@@ -5,7 +5,7 @@
  *
  * Integrates libmmt WASM FEC decoder with:
  * - MFU fragment reassembly
- * - window.Multicast API from pim-multicast-gateway
+ * - window.multicast gateway from pim-multicast-gateway
  * - Green-fill fallback for unrecoverable frames
  *
  * Designed for hang and moqtail players.
@@ -487,7 +487,7 @@ export class MmtFecClient {
 }
 
 /**
- * Integration with window.Multicast API (pim-multicast-gateway)
+ * Integration with window.multicast gateway (pim-multicast-gateway)
  */
 export function createMulticastFecHandler(
 	client: MmtFecClient,
@@ -506,9 +506,9 @@ export function createMulticastFecHandler(
 export async function setupMmtFec(options?: MmtFecClientOptions): Promise<MmtFecClient> {
 	const client = new MmtFecClient(options);
 
-	// Integrate with window.Multicast if available
-	if (typeof window !== "undefined" && (window as unknown as { Multicast?: unknown }).Multicast) {
-		console.log("[MmtFecClient] window.Multicast detected, ready for integration");
+	// Integrate with window.multicast if available
+	if (typeof window !== "undefined" && (window as unknown as { multicast?: unknown }).multicast) {
+		console.log("[MmtFecClient] window.multicast detected, ready for integration");
 	}
 
 	return client;
@@ -835,6 +835,12 @@ export class MoqFecClient {
 		this.encoder = new this.wasmMoqFecEncoder(this.wasmConfig);
 		this.oti = new Uint8Array(this.encoder.getOti());
 
+		// Create decoder from encoder's OTI so addSourceSymbol/addRepairSymbol
+		// work immediately without waiting for an in-band OTI from repair frames.
+		if (this.wasmMoqFecDecoder) {
+			this.decoder = new this.wasmMoqFecDecoder(this.wasmConfig, this.oti);
+		}
+
 		this.initialized = true;
 		console.log(
 			`[MoqFecClient] Initialized: K=${this.config.k}, P=${this.config.p}, ` +

package/src/index.ts

@@ -41,8 +41,12 @@ export type {
 	MmtFecClientOptions,
 	Micro,
 	SyncDecision,
-	MulticastAPI,
-	MulticastSubscription,
+	WindowMulticastSubscribeConfig,
+	WindowMulticastSubscriptionState,
+	WindowMulticastSubscriptionEventMap,
+	WindowMulticastSubscription,
+	WindowMulticastCapabilities,
+	WindowMulticastGateway,
 	// Consolidated from @blockcast/multicast
 	MulticastTransportMode,
 	MulticastConfig,
@@ -88,6 +92,72 @@ export {
 	type FecStatsForAbr,
 } from "./abr-controller.js";
 
+export {
+	endpointKey,
+	selectMulticastTier,
+	type MulticastTierEndpoint,
+} from "./multicast-tier.js";
+
+export {
+	MulticastOrchestrator,
+	DEFAULT_DWELL_MS,
+	DEFAULT_JOIN_DEADLINE_MS,
+	goodputFromStats,
+	type GoodputSample,
+	type MulticastTierPacket,
+	type OrchestratorCommand,
+	type OrchestratorOptions,
+	type OrchestratorState,
+} from "./multicast-orchestrator.js";
+
+export {
+	isMulticastExplicitlyDisabled,
+	isUsableMulticastEndpoint,
+	isValidMulticastGroupAddress,
+	multicastEndpointKey,
+	normalizeMulticastEndpoint,
+	readUrlMulticastConfig,
+	type MulticastEndpointConfig,
+	type MulticastTransportPreference,
+} from "./endpoint-config.js";
+
+export {
+	MulticastSubscriptionPool,
+	multicastSubscriptionPool,
+	type MulticastSubscriptionConsumer,
+	type MulticastSubscriptionLease,
+} from "./multicast-subscription-pool.js";
+
+export {
+	TransportStallDetector,
+	type FecProgressSnapshot,
+	type StallDetectorConfig,
+} from "./stall-detector.js";
+
+export {
+	makeSourceSwitchHandler,
+	wireStallDetector,
+	wireStarvationDetector,
+	type ActivatableSessions,
+	type FecStarvationSnapshot,
+	type LossArcSession,
+	type StallDetectorLike,
+	type StarvationDetectorLike,
+} from "./takeover.js";
+
+export {
+	runUnicastFallback,
+	type FallbackBroadcast,
+	type FallbackBroadcastLike,
+	type FallbackGroup,
+	type FallbackGroupLike,
+	type FallbackSessionManagerLike,
+	type FallbackSessions,
+	type FallbackSubscription,
+	type FallbackSubLike,
+	type FallbackTrack,
+} from "./unicast-fallback.js";
+
 // AMT Gateway
 export {
 	AMTGatewayManager,

package/src/multicast-orchestrator.ts

@@ -0,0 +1,150 @@
+import { endpointKey, selectMulticastTier, type MulticastTierEndpoint } from "./multicast-tier.js";
+
+export type OrchestratorState = "stable" | "joining";
+export type OrchestratorCommand =
+	| { kind: "join-target"; current: MulticastTierEndpoint; target: MulticastTierEndpoint }
+	| { kind: "commit-swap"; target: MulticastTierEndpoint; old: MulticastTierEndpoint }
+	| { kind: "abandon-join"; current: MulticastTierEndpoint; target: MulticastTierEndpoint };
+
+export interface MulticastTierPacket {
+	endpointKey: string;
+	keyframe: boolean;
+	timestamp: number;
+	hasValidCodecConfig: boolean;
+}
+
+export interface OrchestratorOptions {
+	endpoints: readonly MulticastTierEndpoint[];
+	initialEndpoint?: MulticastTierEndpoint;
+	adaptive?: boolean;
+	now: () => number;
+	dwellMs?: number;
+	joinDeadlineMs?: number;
+}
+
+export interface GoodputSample { bitrate: number | undefined; }
+
+export const DEFAULT_DWELL_MS = 3_000;
+export const DEFAULT_JOIN_DEADLINE_MS = 5_000;
+
+export function goodputFromStats(
+	previous: { bytesReceived: number; atMs: number } | undefined,
+	current: { bytesReceived: number; atMs: number },
+	minSampleMs = 500,
+): number | undefined {
+	if (!previous) return undefined;
+	const durationMs = current.atMs - previous.atMs;
+	const bytes = current.bytesReceived - previous.bytesReceived;
+	if (durationMs < minSampleMs || bytes <= 0) return undefined;
+	return (bytes * 8 * 1000) / durationMs;
+}
+
+export class MulticastOrchestrator {
+	#state: OrchestratorState = "stable";
+	#current: MulticastTierEndpoint | undefined;
+	#target: MulticastTierEndpoint | undefined;
+	#estimate: number | undefined;
+	#favored: { key: string; since: number } | undefined;
+	#joinStartedAt = 0;
+	#lastCommittedTimestamp = Number.NEGATIVE_INFINITY;
+	readonly #dwellMs: number;
+	readonly #joinDeadlineMs: number;
+
+	constructor(private readonly options: OrchestratorOptions) {
+		this.#dwellMs = options.dwellMs ?? DEFAULT_DWELL_MS;
+		this.#joinDeadlineMs = options.joinDeadlineMs ?? DEFAULT_JOIN_DEADLINE_MS;
+		if (!Number.isFinite(this.#dwellMs) || !Number.isFinite(this.#joinDeadlineMs) ||
+			this.#dwellMs <= 0 || this.#joinDeadlineMs <= 0) {
+			throw new Error("Multicast dwell and join deadline must be positive");
+		}
+	}
+
+	get state(): OrchestratorState { return this.#state; }
+	get current(): MulticastTierEndpoint | undefined { return this.#current; }
+	get target(): MulticastTierEndpoint | undefined { return this.#target; }
+	get estimate(): number | undefined { return this.#estimate; }
+
+	start(): MulticastTierEndpoint | undefined {
+		this.#current ??= this.options.initialEndpoint ?? selectMulticastTier(this.options.endpoints, undefined);
+		return this.#current;
+	}
+
+	onGoodput(sample: GoodputSample): OrchestratorCommand | undefined {
+		const bitrate = sample.bitrate;
+		this.#estimate = bitrate;
+		if (!this.#current || this.options.adaptive === false) return undefined;
+		if (this.#state === "joining") return this.poll();
+		const desired = selectMulticastTier(this.options.endpoints, bitrate);
+		if (!desired) return undefined;
+		const desiredKey = endpointKey(desired);
+		if (desiredKey === endpointKey(this.#current)) {
+			this.#favored = undefined;
+			return undefined;
+		}
+
+		const now = this.#now();
+		if (!this.#favored || this.#favored.key !== desiredKey) {
+			this.#favored = { key: desiredKey, since: now };
+			return undefined;
+		}
+		if (now - this.#favored.since < this.#dwellMs) return undefined;
+
+		this.#state = "joining";
+		this.#target = desired;
+		this.#joinStartedAt = now;
+		this.#favored = undefined;
+		return { kind: "join-target", current: this.#current, target: desired };
+	}
+
+	onTierPacket(packet: MulticastTierPacket): OrchestratorCommand | undefined {
+		if (!this.#current) return undefined;
+		if (packet.endpointKey === endpointKey(this.#current) && Number.isFinite(packet.timestamp)) {
+			this.#lastCommittedTimestamp = Math.max(this.#lastCommittedTimestamp, packet.timestamp);
+		}
+		if (this.#state !== "joining" || !this.#target) return undefined;
+		const expired = this.poll();
+		if (expired) return expired;
+		if (
+			packet.endpointKey !== endpointKey(this.#target) ||
+			!packet.keyframe ||
+			!packet.hasValidCodecConfig ||
+			!Number.isFinite(packet.timestamp) ||
+			packet.timestamp < this.#lastCommittedTimestamp
+		) return undefined;
+
+		const command: OrchestratorCommand = {
+			kind: "commit-swap",
+			target: this.#target,
+			old: this.#current,
+		};
+		this.#lastCommittedTimestamp = packet.timestamp;
+		this.#current = this.#target;
+		this.#target = undefined;
+		this.#state = "stable";
+		return command;
+	}
+
+	poll(): OrchestratorCommand | undefined {
+		if (this.#state !== "joining" || !this.#target || !this.#current) return undefined;
+		if (this.#now() - this.#joinStartedAt < this.#joinDeadlineMs) return undefined;
+		return this.cancel();
+	}
+
+	cancel(): OrchestratorCommand | undefined {
+		if (this.#state !== "joining" || !this.#target || !this.#current) return undefined;
+		const command: OrchestratorCommand = {
+			kind: "abandon-join",
+			current: this.#current,
+			target: this.#target,
+		};
+		this.#target = undefined;
+		this.#state = "stable";
+		return command;
+	}
+
+	#now(): number {
+		const now = this.options.now();
+		if (!Number.isFinite(now)) throw new Error("Multicast orchestrator clock must be finite");
+		return now;
+	}
+}

package/src/multicast-subscription-pool.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from "vitest";
+import { MulticastSubscriptionPool } from "./multicast-subscription-pool.js";
+import type { TransportConfig, WindowMulticastSubscriptionEventMap } from "./types.js";
+
+const config: TransportConfig = {
+	group: "232.1.1.1",
+	source: "192.0.2.1",
+	port: 5000,
+	streamType: "video",
+};
+
+describe("MulticastSubscriptionPool", () => {
+	it("shares an endpoint and unsubscribes only after the last owner releases", async () => {
+		const listeners = new Map<keyof WindowMulticastSubscriptionEventMap, (event: CustomEvent<never>) => void>();
+		const unsubscribe = vi.fn();
+		const subscription = {
+			addEventListener: vi.fn((type, listener) => listeners.set(type, listener)),
+			removeEventListener: vi.fn(),
+			unsubscribe,
+		};
+		const subscribe = vi.fn().mockResolvedValue(subscription);
+		const gateway = { subscribe };
+		const pool = new MulticastSubscriptionPool();
+		const firstPacket = vi.fn();
+		const secondPacket = vi.fn();
+
+		const first = await pool.acquire(gateway, config, { onBytes: firstPacket });
+		const second = await pool.acquire(gateway, { ...config, group: " 232.1.1.1 " }, { onBytes: secondPacket });
+		expect(subscribe).toHaveBeenCalledOnce();
+
+		const payload = new Uint8Array([1, 2]).buffer;
+		listeners.get("bytes")?.({ detail: payload } as CustomEvent<never>);
+		expect(firstPacket).toHaveBeenCalledWith(payload);
+		expect(secondPacket).toHaveBeenCalledWith(payload);
+
+		await first.release();
+		expect(unsubscribe).not.toHaveBeenCalled();
+		await second.release();
+		expect(unsubscribe).toHaveBeenCalledOnce();
+		expect(pool.size).toBe(0);
+	});
+
+	it("counts an awaiting acquire before the previous owner releases", async () => {
+		const unsubscribe = vi.fn();
+		const subscription = {
+			addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe,
+		};
+		const subscribe = vi.fn().mockResolvedValue(subscription);
+		const gateway = { subscribe };
+		const pool = new MulticastSubscriptionPool();
+		const first = await pool.acquire(gateway, config, { onBytes: vi.fn() });
+		const secondPending = pool.acquire(gateway, config, { onBytes: vi.fn() });
+		await first.release();
+		const second = await secondPending;
+		expect(unsubscribe).not.toHaveBeenCalled();
+		expect(pool.size).toBe(1);
+		await second.release();
+		expect(unsubscribe).toHaveBeenCalledOnce();
+	});
+
+	it("does not conflate transport preferences or gateway instances", async () => {
+		const makeSubscription = () => ({
+			addEventListener: vi.fn(), removeEventListener: vi.fn(), unsubscribe: vi.fn(),
+		});
+		const firstGateway = { subscribe: vi.fn().mockResolvedValue(makeSubscription()) };
+		const secondGateway = { subscribe: vi.fn().mockResolvedValue(makeSubscription()) };
+		const pool = new MulticastSubscriptionPool();
+		const native = await pool.acquire(firstGateway, { ...config, mode: "native" }, { onBytes: vi.fn() });
+		const tunnel = await pool.acquire(firstGateway, { ...config, mode: "tunnel", amtRelay: "relay.example" }, { onBytes: vi.fn() });
+		const replacement = await pool.acquire(secondGateway, { ...config, mode: "native" }, { onBytes: vi.fn() });
+		expect(firstGateway.subscribe).toHaveBeenCalledTimes(2);
+		expect(secondGateway.subscribe).toHaveBeenCalledOnce();
+		await Promise.all([native.release(), tunnel.release(), replacement.release()]);
+	});
+
+	it("evicts a closed entry so the next owner reconnects", async () => {
+		const stateListeners: Array<(event: CustomEvent<"closed">) => void> = [];
+		const subscribe = vi.fn().mockImplementation(async () => ({
+			addEventListener: vi.fn((type, listener) => {
+				if (type === "state") stateListeners.push(listener);
+			}),
+			removeEventListener: vi.fn(),
+			unsubscribe: vi.fn(),
+		}));
+		const gateway = { subscribe };
+		const pool = new MulticastSubscriptionPool();
+		const first = await pool.acquire(gateway, config, { onBytes: vi.fn() });
+		stateListeners[0]({ detail: "closed" } as CustomEvent<"closed">);
+		expect(pool.size).toBe(0);
+		const second = await pool.acquire(gateway, config, { onBytes: vi.fn() });
+		expect(subscribe).toHaveBeenCalledTimes(2);
+		await first.release();
+		await second.release();
+	});
+
+	it("isolates consumer callback failures", async () => {
+		let bytesListener: ((event: CustomEvent<ArrayBuffer>) => void) | undefined;
+		const subscribe = vi.fn().mockResolvedValue({
+			addEventListener: vi.fn((type, listener) => {
+				if (type === "bytes") bytesListener = listener;
+			}),
+			removeEventListener: vi.fn(), unsubscribe: vi.fn(),
+		});
+		const gateway = { subscribe };
+		const pool = new MulticastSubscriptionPool();
+		const secondConsumer = vi.fn();
+		const first = await pool.acquire(gateway, config, { onBytes: () => { throw new Error("boom"); } });
+		const second = await pool.acquire(gateway, config, { onBytes: secondConsumer });
+		const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+		bytesListener?.({ detail: new ArrayBuffer(1) } as CustomEvent<ArrayBuffer>);
+		expect(secondConsumer).toHaveBeenCalledOnce();
+		consoleError.mockRestore();
+		await Promise.all([first.release(), second.release()]);
+	});
+});

package/src/multicast-subscription-pool.ts

@@ -0,0 +1,164 @@
+import { multicastEndpointKey, normalizeMulticastEndpoint } from "./endpoint-config.js";
+import type {
+	TransportConfig,
+	WindowMulticastGateway,
+	WindowMulticastSubscription,
+	WindowMulticastSubscriptionState,
+} from "./types.js";
+
+export interface MulticastSubscriptionConsumer {
+	onBytes(data: ArrayBuffer): void;
+	onState?(state: WindowMulticastSubscriptionState): void;
+	onError?(error: Error): void;
+}
+
+interface PoolEntry {
+	subscription: WindowMulticastSubscription;
+	consumers: Map<symbol, MulticastSubscriptionConsumer>;
+	bytesListener: (event: CustomEvent<ArrayBuffer>) => void;
+	stateListener: (event: CustomEvent<WindowMulticastSubscriptionState>) => void;
+	errorListener: (event: CustomEvent<unknown>) => void;
+	closed: boolean;
+}
+
+interface PoolRecord { claims: number; entry: Promise<PoolEntry>; }
+
+export interface MulticastSubscriptionLease {
+	readonly key: string;
+	release(): Promise<void>;
+}
+
+/** Shares only IWA multicast/AMT subscriptions. Unicast sessions remain per manager. */
+export class MulticastSubscriptionPool {
+	readonly #entries = new Map<string, PoolRecord>();
+	readonly #gatewayIds = new WeakMap<object, number>();
+	#nextGatewayId = 1;
+
+	async acquire(
+		gateway: WindowMulticastGateway,
+		config: TransportConfig,
+		consumer: MulticastSubscriptionConsumer,
+	): Promise<MulticastSubscriptionLease> {
+		const endpoint = normalizeMulticastEndpoint({
+			groupAddress: config.group,
+			sourceAddress: config.source,
+			port: config.port,
+			mode: config.mode,
+			amtRelay: config.amtRelay,
+			amtRelayPort: config.amtRelayPort,
+		});
+		if (!endpoint) throw new Error("Invalid multicast endpoint");
+		if (typeof gateway.subscribe !== "function") throw new Error("window.multicast.subscribe unavailable");
+
+		const key = multicastEndpointKey(endpoint);
+		const internalKey = `${this.#gatewayId(gateway)}|${key}`;
+		let record = this.#entries.get(internalKey);
+		if (!record) {
+			record = { claims: 0, entry: Promise.resolve(null as unknown as PoolEntry) };
+			const createdRecord = record;
+			record.entry = this.#createEntry(gateway, endpoint, (entry) => {
+				if (this.#entries.get(internalKey) === createdRecord) this.#entries.delete(internalKey);
+				this.#detach(entry);
+			}).catch((error) => {
+				if (this.#entries.get(internalKey) === createdRecord) this.#entries.delete(internalKey);
+				throw error;
+			});
+			this.#entries.set(internalKey, record);
+		}
+
+		record.claims++;
+		let entry: PoolEntry;
+		try {
+			entry = await record.entry;
+		} catch (error) {
+			record.claims--;
+			throw error;
+		}
+		if (entry.closed) {
+			record.claims--;
+			return this.acquire(gateway, config, consumer);
+		}
+		const token = Symbol(key);
+		entry.consumers.set(token, consumer);
+		let released = false;
+		return {
+			key,
+			release: async () => {
+				if (released) return;
+				released = true;
+				entry.consumers.delete(token);
+				record.claims--;
+				if (record.claims > 0) return;
+				if (this.#entries.get(internalKey) === record) this.#entries.delete(internalKey);
+				this.#detach(entry);
+				if (!entry.closed) await entry.subscription.unsubscribe();
+			},
+		};
+	}
+
+	get size(): number { return this.#entries.size; }
+
+	async #createEntry(
+		gateway: WindowMulticastGateway,
+		endpoint: NonNullable<ReturnType<typeof normalizeMulticastEndpoint>>,
+		onClosed: (entry: PoolEntry) => void,
+	): Promise<PoolEntry> {
+		const subscription = await gateway.subscribe!({
+			group: endpoint.groupAddress,
+			...(endpoint.sourceAddress ? { source: endpoint.sourceAddress } : {}),
+			port: endpoint.port,
+			consume: "bytes",
+			...(endpoint.mode ? { mode: endpoint.mode } : {}),
+			...(endpoint.amtRelay ? { amtRelay: endpoint.amtRelay } : {}),
+			...(endpoint.amtRelayPort ? { amtRelayPort: endpoint.amtRelayPort } : {}),
+		});
+		const consumers = new Map<symbol, MulticastSubscriptionConsumer>();
+		let entry: PoolEntry;
+		const bytesListener = (event: CustomEvent<ArrayBuffer>) => {
+			this.#dispatch(consumers, (consumer) => consumer.onBytes(event.detail));
+		};
+		const stateListener = (event: CustomEvent<WindowMulticastSubscriptionState>) => {
+			this.#dispatch(consumers, (consumer) => consumer.onState?.(event.detail));
+			if (event.detail === "closed" && !entry.closed) {
+				entry.closed = true;
+				onClosed(entry);
+			}
+		};
+		const errorListener = (event: CustomEvent<unknown>) => {
+			const error = event.detail instanceof Error ? event.detail : new Error(String(event.detail));
+			this.#dispatch(consumers, (consumer) => consumer.onError?.(error));
+		};
+		entry = { subscription, consumers, bytesListener, stateListener, errorListener, closed: false };
+		subscription.addEventListener("bytes", bytesListener);
+		subscription.addEventListener("state", stateListener);
+		subscription.addEventListener("error", errorListener);
+		return entry;
+	}
+
+	#gatewayId(gateway: WindowMulticastGateway): number {
+		const object = gateway as object;
+		let id = this.#gatewayIds.get(object);
+		if (!id) {
+			id = this.#nextGatewayId++;
+			this.#gatewayIds.set(object, id);
+		}
+		return id;
+	}
+
+	#detach(entry: PoolEntry): void {
+		entry.subscription.removeEventListener("bytes", entry.bytesListener);
+		entry.subscription.removeEventListener("state", entry.stateListener);
+		entry.subscription.removeEventListener("error", entry.errorListener);
+	}
+
+	#dispatch(
+		consumers: Map<symbol, MulticastSubscriptionConsumer>,
+		callback: (consumer: MulticastSubscriptionConsumer) => void,
+	): void {
+		for (const consumer of consumers.values()) {
+			try { callback(consumer); } catch (error) { console.error("[Transport] multicast consumer callback failed", error); }
+		}
+	}
+}
+
+export const multicastSubscriptionPool = new MulticastSubscriptionPool();