@ceralive/modem-control 1.0.0 → 1.2.0

package/src/transport/README.md

@@ -1,65 +0,0 @@
-# D-Bus transport seam
-
-A minimal internal transport interface over [`@httptoolkit/dbus-native`](https://www.npmjs.com/package/@httptoolkit/dbus-native).
-Everything the rest of `@ceralive/modem-control` needs to talk to ModemManager over
-D-Bus goes through the `DbusTransport` interface exported by [`index.ts`](./index.ts) —
-method calls, signal subscriptions, and reconnect. The A3.x D-Bus backend builds
-directly on this shape.
-
-## Why this library
-
-`@httptoolkit/dbus-native` is a pure-JavaScript D-Bus client (no libdbus / native
-addon), which is the deciding factor: it imports and runs under **Bun 1.3.14** with
-**EXTERNAL** auth on a session bus — session-verified during A2.4, and pinned exactly at
-`0.1.5`. A native-addon client (anything binding libdbus) is a portability and
-cross-compile liability for the arm64 + amd64 device image; a pure-JS client is not.
-
-## The fallback
-
-If `@httptoolkit/dbus-native` proves inadequate — an un-fixable marshalling bug, an
-unmaintained upstream, or a Bun incompatibility introduced by a future runtime bump —
-the documented fallback is [`@particle/dbus-next`](https://www.npmjs.com/package/@particle/dbus-next),
-which is also pure-JS and was verified importable under Bun during planning (draft
-ledger §dbus-native). It is **not** implemented here; this note records the escape hatch.
-Because the entire library surface is quarantined behind this seam (see below), swapping
-to it would touch only [`dbus-native.ts`](./dbus-native.ts), [`transport.ts`](./transport.ts),
-and [`codec.ts`](./codec.ts) — never a caller.
-
-## The seam contract
-
-* **No library types leak.** `index.ts` re-exports only the transport's own types
-  (`DbusValue`, `DbusVariant`, `MethodCall`, `SignalEvent`, …). The raw library types
-  live in [`dbus-native.ts`](./dbus-native.ts) and go no further. A guard test asserts
-  the package entry (`../index.ts`) never re-exports the library.
-* **Lossless 64-bit.** D-Bus `x` (INT64) and `t` (UINT64) are `bigint` end-to-end, never
-  a JS `number`. On decode the library runs with `ReturnLongjs: true` and we convert its
-  Long.js objects to `bigint` via their exact decimal string; on encode we require a
-  `bigint` and hand the library a decimal string (its only lossless 64-bit input).
-  Passing a `number` for a 64-bit field throws `BigIntRequiredError`.
-* **`h` is unsupported.** UNIX_FD / file-descriptor passing is rejected up front with a
-  typed `UnsupportedSignatureError` — in an outgoing signature, a reply/signal signature,
-  or nested in a variant — never silently dropped or coerced.
-* **Variants round-trip.** A decoded variant keeps its inner signature
-  (`DbusVariant { signature, value }`), so encode/decode is symmetric.
-
-## Conformance
-
-Tests run under `dbus-run-session -- bun test control/src/transport` and prove the seam
-two independent ways:
-
-1. **Same library** ([`conformance-same-lib.test.ts`](./conformance-same-lib.test.ts)) —
-   round-trips representative signatures against a minimal fake service built on the same
-   `@httptoolkit/dbus-native`.
-2. **Independent producer** ([`conformance-python.test.ts`](./conformance-python.test.ts)) —
-   round-trips against a `python3-dbus` (`dbus-python`) service in a subprocess,
-   exercising `a{oa{sa{sv}}}`, `x`/`t` above 2^53, variants, and `PropertiesChanged`
-   invalidations. A different implementation on the wire is the real proof our codec is
-   correct, not merely self-consistent.
-
-Plus [`reliability.test.ts`](./reliability.test.ts): reconnect after a bus restart
-(against a dedicated private `dbus-daemon`), a ≥5000-event signal stream, late replies,
-and a 100-cycle subscribe/unsubscribe listener-leak check.
-
-The `test-support/` fakes here are intentionally minimal — just enough to round-trip the
-signatures under test. The MM-faithful fake service (root ObjectManager, `Modem` /
-`Modem3gpp` interfaces, SIM objects, bearer tripwires) is a separate, later task (A2.3).

package/src/transport/calls.ts

@@ -1,113 +0,0 @@
-// Method-call dispatch and reply correlation for the D-Bus transport seam.
-//
-// A call marshals its body through the codec, registers a pending record so a bus drop can
-// reject it, and installs a per-call reply callback guarded by a `done` flag — so a reply
-// that arrives after the call already timed out or the connection dropped is silently
-// ignored rather than mis-correlated onto a stale promise. `rejectAll` mass-rejects every
-// in-flight call when the connection drops.
-
-import { decodeBody, encodeBody } from './codec';
-import { messageType, type RawBus, type RawMessage, type ReplyContext } from './dbus-native';
-import { DisconnectedError, TransportError } from './errors';
-import type { DbusValue, MethodCall, MethodReply } from './types';
-
-export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
-
-interface PendingCall {
-	settle(): void;
-	reject(error: unknown): void;
-}
-
-export class CallDispatcher {
-	readonly #pending = new Set<PendingCall>();
-	readonly #callTimeoutMs: number;
-
-	constructor(callTimeoutMs: number) {
-		this.#callTimeoutMs = callTimeoutMs;
-	}
-
-	async call(bus: RawBus | null, connected: boolean, call: MethodCall): Promise<MethodReply> {
-		if (!connected || bus === null) {
-			throw new DisconnectedError('cannot call method: transport not connected');
-		}
-
-		const signature = call.signature ?? '';
-		const args = call.args ?? [];
-		const message: RawMessage = {
-			type: messageType.methodCall,
-			destination: call.destination,
-			path: call.path,
-			interface: call.interface,
-			member: call.member,
-		};
-		if (signature.length > 0) {
-			// Throws UnsupportedSignatureError / BigIntRequiredError before anything hits
-			// the wire.
-			message.signature = signature;
-			message.body = encodeBody(signature, args);
-		}
-
-		const timeoutMs = call.timeoutMs ?? this.#callTimeoutMs;
-		const pendingSet = this.#pending;
-		return new Promise<MethodReply>((resolve, reject) => {
-			let done = false;
-			const pending: PendingCall = {
-				settle: finish,
-				reject: (error) => {
-					finish();
-					reject(error);
-				},
-			};
-
-			function finish(): void {
-				if (done) {
-					return;
-				}
-				done = true;
-				clearTimeout(timer);
-				pendingSet.delete(pending);
-			}
-
-			const timer = setTimeout(() => {
-				finish();
-				reject(
-					new TransportError(
-						`Method call ${call.interface}.${call.member} timed out after ${timeoutMs}ms`,
-					),
-				);
-			}, timeoutMs);
-
-			pendingSet.add(pending);
-
-			bus.invoke(
-				message,
-				function reply(this: ReplyContext, error: unknown, ...body: unknown[]): void {
-					if (done) {
-						// Reply arrived after timeout/disconnect already settled the promise — ignore.
-						return;
-					}
-					finish();
-					if (error) {
-						reject(error instanceof Error ? error : new TransportError(String(error)));
-						return;
-					}
-					try {
-						const replySignature = this.signature ?? '';
-						const decoded: DbusValue[] =
-							replySignature.length > 0 ? decodeBody(replySignature, body) : [];
-						resolve({ signature: replySignature, body: decoded });
-					} catch (decodeError) {
-						reject(decodeError);
-					}
-				},
-			);
-		});
-	}
-
-	rejectAll(cause: unknown): void {
-		for (const pending of this.#pending) {
-			pending.reject(cause);
-		}
-		this.#pending.clear();
-	}
-}

package/src/transport/characterization.test.ts

@@ -1,260 +0,0 @@
-// 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/codec.test.ts

@@ -1,118 +0,0 @@
-// Pure, in-process encode/decode round-trip: no bus, fully deterministic. Marshals with
-// the library's own marshaller and reads it back with its DBusBuffer under
-// `ReturnLongjs: true` — exactly the wire path a real call takes — so a green run here is
-// exact proof the codec is lossless, independent of any daemon timing.
-
-import { expect, test } from 'bun:test';
-import DBusBuffer from '@httptoolkit/dbus-native/lib/dbus-buffer';
-import marshall from '@httptoolkit/dbus-native/lib/marshall';
-import { decodeBody, encodeBody } from './codec';
-import { BigIntRequiredError, SixtyFourBitRangeError, UnsupportedSignatureError } from './errors';
-import { type DbusValue, variant } from './types';
-
-const INT64_MAX = 2n ** 63n - 1n;
-const INT64_MIN = -(2n ** 63n);
-const UINT64_MAX = 2n ** 64n - 1n;
-
-function roundTrip(signature: string, values: readonly DbusValue[]): DbusValue[] {
-	const encoded = encodeBody(signature, values);
-	const buffer = marshall(signature, encoded);
-	const reader = new DBusBuffer(buffer, 0, { ayBuffer: true, ReturnLongjs: true });
-	const raw = reader.read(signature) as unknown[];
-	return decodeBody(signature, raw);
-}
-
-test('2^63-1 round-trips through an INT64 exactly (bigint equality)', () => {
-	const [value] = roundTrip('x', [INT64_MAX]);
-	expect(value).toBe(INT64_MAX);
-	expect(typeof value).toBe('bigint');
-});
-
-test('the full UINT64 range (2^64-1) round-trips exactly', () => {
-	const [value] = roundTrip('t', [UINT64_MAX]);
-	expect(value).toBe(UINT64_MAX);
-});
-
-test('INT64 minimum round-trips exactly', () => {
-	const [value] = roundTrip('x', [INT64_MIN]);
-	expect(value).toBe(INT64_MIN);
-});
-
-test('a value just above 2^53 survives (no silent Number coercion)', () => {
-	const beyondSafe = 2n ** 53n + 1n;
-	const [asInt, asUint] = roundTrip('xt', [beyondSafe, beyondSafe]);
-	expect(asInt).toBe(beyondSafe);
-	expect(asUint).toBe(beyondSafe);
-	// The precision-losing path would have produced 9007199254740992n (== 2^53).
-	expect(asInt).not.toBe(2n ** 53n);
-});
-
-test('the MM GetManagedObjects shape a{oa{sa{sv}}} round-trips with a 64-bit variant', () => {
-	const managed: DbusValue = [
-		[
-			'/org/freedesktop/ModemManager1/Modem/0',
-			[
-				[
-					'org.freedesktop.ModemManager1.Modem',
-					[
-						['SupportedCapabilities', variant('t', UINT64_MAX)],
-						['SignalQuality', variant('u', 87)],
-						['DeviceIdentifier', variant('s', 'dev-0')],
-					],
-				],
-			],
-		],
-	];
-	const [decoded] = roundTrip('a{oa{sa{sv}}}', [managed]);
-	expect(decoded).toEqual(managed);
-});
-
-test('a variant preserves its inner signature and 64-bit value across a round-trip', () => {
-	const [decoded] = roundTrip('v', [variant('t', UINT64_MAX)]);
-	expect(decoded).toEqual({ signature: 't', value: UINT64_MAX });
-});
-
-test('a byte array (ay) round-trips as a Uint8Array', () => {
-	const bytes = new Uint8Array([0, 1, 2, 254, 255]);
-	const [decoded] = roundTrip('ay', [bytes]);
-	expect(decoded).toBeInstanceOf(Uint8Array);
-	expect(Array.from(decoded as Uint8Array)).toEqual([0, 1, 2, 254, 255]);
-});
-
-test('a struct with mixed 64-bit fields round-trips', () => {
-	const [decoded] = roundTrip('(xtu)', [[INT64_MIN, UINT64_MAX, 7]]);
-	expect(decoded).toEqual([INT64_MIN, UINT64_MAX, 7]);
-});
-
-test('signature h (UNIX_FD) is rejected on encode with a typed error', () => {
-	expect(() => encodeBody('h', [0])).toThrow(UnsupportedSignatureError);
-});
-
-test('signature h nested inside a container is rejected on encode', () => {
-	expect(() => encodeBody('a{sh}', [[]])).toThrow(UnsupportedSignatureError);
-});
-
-test('signature h is rejected on decode with a typed error', () => {
-	expect(() => decodeBody('h', [0])).toThrow(UnsupportedSignatureError);
-});
-
-test('the UnsupportedSignatureError carries the offending type', () => {
-	try {
-		encodeBody('h', [0]);
-		throw new Error('expected throw');
-	} catch (error) {
-		expect(error).toBeInstanceOf(UnsupportedSignatureError);
-		expect((error as UnsupportedSignatureError).unsupportedType).toBe('h');
-	}
-});
-
-test('passing a JS number for a 64-bit field throws BigIntRequiredError', () => {
-	expect(() => encodeBody('t', [123])).toThrow(BigIntRequiredError);
-	expect(() => encodeBody('x', [123])).toThrow(BigIntRequiredError);
-});
-
-test('an out-of-range 64-bit bigint throws SixtyFourBitRangeError', () => {
-	expect(() => encodeBody('t', [-1n])).toThrow(SixtyFourBitRangeError);
-	expect(() => encodeBody('x', [2n ** 63n])).toThrow(SixtyFourBitRangeError);
-	expect(() => encodeBody('t', [2n ** 64n])).toThrow(SixtyFourBitRangeError);
-});