@ceralive/modem-control 0.1.0 → 1.0.0

package/src/transport/characterization.test.ts

@@ -0,0 +1,260 @@
+// Characterization tests for the transport seam's reconnect / call-correlation / ordering
+// edges — the behaviour that a later refactor (splitting transport.ts into lifecycle,
+// call-dispatch, and signal modules) MUST preserve byte-for-byte at the observable level.
+//
+// These pin CURRENT behaviour, not aspirational behaviour: each assertion records what the
+// unsplit transport.ts actually does today. If the split changes any of these observable
+// facts, one of these tests goes red — which is the whole point.
+//
+// Like reliability.test.ts, these run against dedicated private `dbus-daemon` instances
+// (each test owns one) so a destructive kill/restart is safe. That also makes the file
+// self-contained — it needs no outer `dbus-run-session`.
+
+import { describe, expect, test } from 'bun:test';
+import { createDbusTransport } from './index';
+import { FAKE_IFACE, FAKE_PATH, startFakeService, TICK_MEMBER } from './test-support/fake-service';
+import { PrivateBus } from './test-support/private-bus';
+
+const HAS_DBUS_DAEMON = Bun.which('dbus-daemon') !== null;
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitFor(predicate: () => boolean, timeoutMs: number, label: string): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		if (predicate()) {
+			return;
+		}
+		await sleep(10);
+	}
+	throw new Error(`timed out after ${timeoutMs}ms waiting for ${label}`);
+}
+
+const tickSpec = { interface: FAKE_IFACE, member: TICK_MEMBER, path: FAKE_PATH };
+
+describe.skipIf(!HAS_DBUS_DAEMON)('transport characterization', () => {
+	// (i) A call that times out, then the real reply lands AFTER the timeout already
+	// settled the promise. The late reply must be silently ignored (each `bus.invoke`
+	// owns its own reply closure, guarded by a `done` flag) — no crash, and no
+	// mis-correlation onto a later, unrelated call.
+	test('a reply arriving after the call already timed out is silently ignored', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({ socket: bus.socket, reconnect: { enabled: false } });
+		let errorEvents = 0;
+		transport.on('error', () => {
+			errorEvents += 1;
+		});
+		await transport.connect();
+
+		// SlowPing replies after 400ms; the call's own timeout is 100ms, so it times out
+		// first and the reply becomes a "late" one 300ms later.
+		await expect(
+			transport.callMethod({
+				destination: fake.busName,
+				path: FAKE_PATH,
+				interface: FAKE_IFACE,
+				member: 'SlowPing',
+				signature: 'u',
+				args: [400],
+				timeoutMs: 100,
+			}),
+		).rejects.toThrow('timed out after 100ms');
+
+		// Wait well past the 400ms reply so the ignored late reply has actually been
+		// delivered to (and dropped by) the settled callback.
+		await sleep(500);
+
+		// No crash, no error event, still connected — the late reply disturbed nothing.
+		expect(errorEvents).toBe(0);
+		expect(transport.isConnected()).toBe(true);
+
+		// And the pending machinery is intact: a fresh call correlates to its OWN reply,
+		// proving the late reply was not mis-delivered to a later promise.
+		const reply = await transport.callMethod({
+			destination: fake.busName,
+			path: FAKE_PATH,
+			interface: FAKE_IFACE,
+			member: 'Ping',
+		});
+		expect(reply.body[0]).toBe('pong');
+
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	});
+
+	// (ii) A bus drop while a call is in flight. The in-flight call must reject, and the
+	// observed ordering is pinned: the `disconnected` event is delivered BEFORE the call
+	// rejection is observed. (In `#handleDrop`, pending calls are rejected and then
+	// `disconnected` is emitted synchronously — but a promise rejection is observed on a
+	// microtask, so the synchronous event listener runs first.)
+	test('a mid-call bus drop rejects the in-flight call after emitting disconnected', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({ socket: bus.socket, reconnect: { enabled: false } });
+
+		const order: string[] = [];
+		let rejection: unknown = null;
+		transport.on('disconnected', () => order.push('disconnected'));
+		await transport.connect();
+
+		// A call that will never get a reply — the bus dies under it.
+		const call = transport
+			.callMethod({
+				destination: fake.busName,
+				path: FAKE_PATH,
+				interface: FAKE_IFACE,
+				member: 'SlowPing',
+				signature: 'u',
+				args: [5000],
+			})
+			.catch((error: unknown) => {
+				order.push('call-rejected');
+				rejection = error;
+			});
+
+		// Give the call time to reach the wire, then drop the bus under it.
+		await sleep(30);
+		bus.kill();
+
+		await waitFor(
+			() => order.includes('disconnected') && order.includes('call-rejected'),
+			5000,
+			'disconnected + call rejection',
+		);
+		await call;
+
+		// Pinned ordering: the event precedes the observed rejection.
+		expect(order).toEqual(['disconnected', 'call-rejected']);
+		// Pinned rejection type: a DisconnectedError (the connection-end drop cause).
+		expect(rejection).toBeInstanceOf(Error);
+		expect((rejection as Error).name).toBe('DisconnectedError');
+
+		await transport.disconnect();
+		// The fake died with its bus; stopping it would write to a closed stream. Leave it.
+		await bus.stop();
+	});
+
+	// (iii) A drop that arrives while a reconnect is already running. The reconnect loop is
+	// idempotent: `#handleDrop` early-returns whenever the state is already `disconnected`
+	// or `reconnecting`, so repeated low-level drop signals never spawn a second reconnect
+	// loop. The transport converges to a single connected state — exactly one `disconnected`
+	// and one `reconnected`, no error, and it is not wedged.
+	test('a drop during an in-flight reconnect does not double-schedule or wedge', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		let fake = await startFakeService({ socket: bus.socket });
+		const transport = createDbusTransport({
+			socket: bus.socket,
+			reconnect: { initialDelayMs: 25, maxDelayMs: 100 },
+		});
+
+		const events: string[] = [];
+		let errorEvents = 0;
+		transport.on('disconnected', () => events.push('disconnected'));
+		transport.on('reconnected', () => events.push('reconnected'));
+		transport.on('error', () => {
+			errorEvents += 1;
+		});
+		await transport.connect();
+
+		const ticks: bigint[] = [];
+		const subscription = await transport.subscribeSignal(tickSpec, (event) => {
+			ticks.push(event.body[0] as bigint);
+		});
+
+		fake.emitTick(11n);
+		await waitFor(() => ticks.includes(11n), 3000, 'pre-drop tick');
+
+		// Drop the bus and leave it down long enough for the reconnect loop to spin through
+		// several failed establish attempts before the bus returns.
+		bus.kill();
+		await waitFor(() => events.includes('disconnected'), 5000, 'disconnected');
+		await sleep(150);
+		await bus.start();
+		await waitFor(() => events.includes('reconnected'), 15000, 'reconnected');
+
+		// A settle window to catch any spurious extra event from a double-scheduled loop.
+		await sleep(300);
+
+		expect(events.filter((event) => event === 'disconnected')).toHaveLength(1);
+		expect(events.filter((event) => event === 'reconnected')).toHaveLength(1);
+		expect(errorEvents).toBe(0);
+
+		// Not wedged: a fresh producer's signal flows through the auto-resubscribed rule.
+		fake = await startFakeService({ socket: bus.socket });
+		fake.emitTick(22n);
+		await waitFor(() => ticks.includes(22n), 8000, 'post-reconnect tick');
+		expect(transport.subscriptionCount()).toBe(1);
+
+		await subscription.unsubscribe();
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	}, 30000);
+
+	// (iv) A subscription added AND one removed while a reconnect is in progress. Because
+	// mutating a subscription while disconnected only touches the in-memory match-rule
+	// refcount (the bus call is skipped when not connected), and `#establish()` re-issues
+	// every live rule on reconnect, the refcounting must end up correct: the added
+	// subscription is registered (receives signals) and the removed one is not.
+	test('subscriptions mutated during reconnect end up correctly (un)registered', async () => {
+		const bus = new PrivateBus();
+		await bus.start();
+		const transport = createDbusTransport({
+			socket: bus.socket,
+			reconnect: { initialDelayMs: 25, maxDelayMs: 100 },
+		});
+
+		const events: string[] = [];
+		transport.on('disconnected', () => events.push('disconnected'));
+		transport.on('reconnected', () => events.push('reconnected'));
+		await transport.connect();
+
+		// `removed` is a path-filtered rule; `added` is a distinct (no-path) rule that still
+		// matches the same emitted Tick — so their match-rule strings differ and are tracked
+		// independently.
+		const removedTicks: bigint[] = [];
+		const addedTicks: bigint[] = [];
+		const removed = await transport.subscribeSignal(tickSpec, (event) => {
+			removedTicks.push(event.body[0] as bigint);
+		});
+		expect(transport.subscriptionCount()).toBe(1);
+
+		// Drop the bus; while the reconnect loop is running, mutate the subscription set.
+		bus.kill();
+		await waitFor(() => events.includes('disconnected'), 5000, 'disconnected');
+
+		await removed.unsubscribe();
+		const added = await transport.subscribeSignal(
+			{ interface: FAKE_IFACE, member: TICK_MEMBER },
+			(event) => {
+				addedTicks.push(event.body[0] as bigint);
+			},
+		);
+		expect(transport.subscriptionCount()).toBe(1);
+
+		// Bring the bus back; `#establish()` re-issues exactly the rules still in the
+		// refcount map — the `added` one, not the `removed` one.
+		await bus.start();
+		await waitFor(() => events.includes('reconnected'), 15000, 'reconnected');
+
+		const fake = await startFakeService({ socket: bus.socket });
+		fake.emitTick(33n);
+		await waitFor(() => addedTicks.includes(33n), 8000, 'added-subscription tick');
+
+		// Grace to prove the removed subscription genuinely receives nothing.
+		await sleep(200);
+		expect(addedTicks).toEqual([33n]);
+		expect(removedTicks).toEqual([]);
+		expect(transport.subscriptionCount()).toBe(1);
+
+		await added.unsubscribe();
+		await transport.disconnect();
+		await fake.stop();
+		await bus.stop();
+	}, 30000);
+});

package/src/transport/no-library-leak.test.ts

@@ -6,6 +6,7 @@
 // fallback `@particle/dbus-next`) must stay invisible to every caller.
 
 import { expect, test } from 'bun:test';
+import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import * as transportPublic from './index';
 
@@ -26,11 +27,21 @@ test('the transport public entry does not import or re-export the D-Bus library'
 });
 
 test('only the quarantined facade imports the D-Bus library from production modules', async () => {
-	const productionModules = ['transport.ts', 'codec.ts', 'signature.ts', 'errors.ts', 'types.ts'];
+	// Enumerate every non-test production module in transport/ dynamically, so a NEW module
+	// (e.g. a future transport split) that imports the library directly is caught — the old
+	// fixed list never knew about files it did not name. The importer set must be EXACTLY the
+	// sanctioned facade, `dbus-native.ts`.
+	const productionModules = readdirSync(transportDir).filter(
+		(name) => name.endsWith('.ts') && !name.endsWith('.test.ts'),
+	);
+	const importers: string[] = [];
 	for (const moduleName of productionModules) {
 		const source = await Bun.file(join(transportDir, moduleName)).text();
-		expect(source).not.toContain(LIBRARY_IMPORT);
+		if (source.includes(LIBRARY_IMPORT)) {
+			importers.push(moduleName);
+		}
 	}
+	expect(importers.sort()).toEqual(['dbus-native.ts']);
 });
 
 test('the transport public surface exposes only the seam\u2019s own values', () => {

package/src/transport/signals.ts

@@ -0,0 +1,150 @@
+// Signal subscription and match-rule tracking for the D-Bus transport seam.
+//
+// The transport's single persistent `message` listener fans out here: `dispatch` walks the
+// live subscription registry and delivers each decoded signal to every matching listener.
+// Match rules are refcounted so N subscriptions sharing a rule add/remove it on the bus
+// exactly once, and `reissueRules` re-adds every live rule after a reconnect — so
+// subscribing/unsubscribing never grows the connection's listener count (the 100-cycle
+// leak check depends on this).
+
+import { decodeBody } from './codec';
+import { messageType, type RawBus, type RawMessage } from './dbus-native';
+import type { DbusValue, SignalEvent, SignalListener, SignalSpec, Subscription } from './types';
+
+// The live connection context the registry reads through. The transport supplies these so
+// the registry always sees the current bus/connected state (which change across reconnects)
+// rather than capturing a stale reference, and routes decode/listener failures to the
+// transport's `error` event.
+export interface SignalHost {
+	currentBus(): RawBus | null;
+	isConnected(): boolean;
+	emitError(error: unknown): void;
+}
+
+interface SubscriptionRecord {
+	readonly id: number;
+	readonly spec: SignalSpec;
+	readonly listener: SignalListener;
+	readonly rule: string;
+}
+
+function buildMatchRule(spec: SignalSpec): string {
+	const parts = [`type='signal'`, `interface='${spec.interface}'`, `member='${spec.member}'`];
+	if (spec.path !== undefined) {
+		parts.push(`path='${spec.path}'`);
+	}
+	if (spec.sender !== undefined) {
+		parts.push(`sender='${spec.sender}'`);
+	}
+	return parts.join(',');
+}
+
+function signalMatches(spec: SignalSpec, message: RawMessage): boolean {
+	if (message.interface !== spec.interface || message.member !== spec.member) {
+		return false;
+	}
+	if (spec.path !== undefined && message.path !== spec.path) {
+		return false;
+	}
+	if (spec.sender !== undefined && message.sender !== spec.sender) {
+		return false;
+	}
+	return true;
+}
+
+export class SignalRegistry {
+	readonly #host: SignalHost;
+	readonly #subscriptions = new Map<number, SubscriptionRecord>();
+	readonly #matchRuleRefcount = new Map<string, number>();
+	#nextSubId = 1;
+
+	constructor(host: SignalHost) {
+		this.#host = host;
+	}
+
+	async subscribe(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
+		const rule = buildMatchRule(spec);
+		const id = this.#nextSubId++;
+		this.#subscriptions.set(id, { id, spec, listener, rule });
+		await this.#addMatchRule(rule);
+
+		let removed = false;
+		return {
+			unsubscribe: async (): Promise<void> => {
+				if (removed) {
+					return;
+				}
+				removed = true;
+				this.#subscriptions.delete(id);
+				await this.#removeMatchRule(rule);
+			},
+		};
+	}
+
+	count(): number {
+		return this.#subscriptions.size;
+	}
+
+	// Re-issue every live match rule against a freshly established bus so a reconnect
+	// resubscribes transparently. Called by `#establish` before it swaps in the new bus, so
+	// the fresh bus is passed in explicitly rather than read from the host.
+	async reissueRules(bus: RawBus): Promise<void> {
+		for (const rule of this.#matchRuleRefcount.keys()) {
+			await bus.addMatch(rule);
+		}
+	}
+
+	dispatch(message: RawMessage): void {
+		if (message.type !== messageType.signal) {
+			return;
+		}
+		for (const record of this.#subscriptions.values()) {
+			if (!signalMatches(record.spec, message)) {
+				continue;
+			}
+			let body: DbusValue[];
+			try {
+				const signature = message.signature ?? '';
+				body = signature.length > 0 ? decodeBody(signature, message.body ?? []) : [];
+			} catch (error) {
+				this.#host.emitError(error);
+				continue;
+			}
+			const event: SignalEvent = {
+				path: message.path ?? '',
+				interface: message.interface ?? '',
+				member: message.member ?? '',
+				sender: message.sender,
+				signature: message.signature ?? '',
+				body,
+			};
+			try {
+				record.listener(event);
+			} catch (error) {
+				this.#host.emitError(error);
+			}
+		}
+	}
+
+	async #addMatchRule(rule: string): Promise<void> {
+		const current = this.#matchRuleRefcount.get(rule) ?? 0;
+		this.#matchRuleRefcount.set(rule, current + 1);
+		const bus = this.#host.currentBus();
+		if (current === 0 && this.#host.isConnected() && bus) {
+			await bus.addMatch(rule);
+		}
+	}
+
+	async #removeMatchRule(rule: string): Promise<void> {
+		const current = this.#matchRuleRefcount.get(rule) ?? 0;
+		if (current <= 1) {
+			this.#matchRuleRefcount.delete(rule);
+			const bus = this.#host.currentBus();
+			if (current === 1 && this.#host.isConnected() && bus) {
+				await bus.removeMatch(rule).catch(() => undefined);
+			}
+		} else {
+			this.#matchRuleRefcount.set(rule, current - 1);
+		}
+	}
+}

package/src/transport/test-support/fake-service.ts

@@ -106,16 +106,40 @@ export async function startFakeService(options: FakeServiceOptions): Promise<Fak
 	// surface an unhandled EventEmitter 'error' from this helper's dead connection.
 	bus.connection.on('error', () => undefined);
 
+	// A reconnect/drop test kills the bus and ABANDONS this fake (stopping it would itself
+	// write to the closed stream). Any reply the library still owes — e.g. a SlowPing whose
+	// delay has not elapsed — would then be written to that dead stream when its timer
+	// fires, throwing "Can't write a message to a closed stream" ASYNCHRONOUSLY, seconds
+	// later, inside whatever unrelated test happens to be running. Track the reply timers
+	// and cancel them the instant the connection stream ends, so a dead fake never writes.
+	const pendingReplyTimers = new Set<ReturnType<typeof setTimeout>>();
+	const clearPendingReplies = (): void => {
+		for (const timer of pendingReplyTimers) {
+			clearTimeout(timer);
+		}
+		pendingReplyTimers.clear();
+	};
+	bus.connection.on('end', clearPendingReplies);
+
 	const define = (member: string, impl: MethodImpl, resultSignature: string): void => {
 		bus.setMethodCallHandler(FAKE_PATH, FAKE_IFACE, member, [impl, resultSignature]);
 	};
 
 	define('Ping', () => 'pong', 's');
 	// The library awaits a Promise returned by a handler, so this replies after a delay —
-	// used to prove a late reply still resolves the caller's method call.
+	// used to prove a late reply still resolves the caller's method call. The timer is
+	// tracked so a bus drop before it fires cancels the owed reply instead of writing it
+	// to a closed stream.
 	define(
 		'SlowPing',
-		(delayMs) => new Promise((resolve) => setTimeout(() => resolve('pong'), Number(delayMs))),
+		(delayMs) =>
+			new Promise((resolve) => {
+				const timer = setTimeout(() => {
+					pendingReplyTimers.delete(timer);
+					resolve('pong');
+				}, Number(delayMs));
+				pendingReplyTimers.add(timer);
+			}),
 		's',
 	);
 	define('GetManagedObjects', () => managedObjectsValue(), 'a{oa{sa{sv}}}');
@@ -137,6 +161,7 @@ export async function startFakeService(options: FakeServiceOptions): Promise<Fak
 			bus.sendSignal(FAKE_PATH, FAKE_IFACE, TICK_MEMBER, 't', [seq.toString()]);
 		},
 		async stop(): Promise<void> {
+			clearPendingReplies();
 			await bus.disconnect().catch(() => undefined);
 		},
 	};