@ceralive/modem-control 1.0.0 → 1.1.0

package/src/transport/test-support/independent-producer.py

@@ -1,110 +0,0 @@
-#!/usr/bin/env python3
-"""Independent D-Bus producer for transport conformance half (b).
-
-A different implementation on the wire than the JavaScript library under test: this uses
-the `dbus-python` bindings (`python3-dbus`) plus a GLib main loop. If our TypeScript codec
-agrees with THIS producer as well as with the same-library fake, the codec is correct, not
-merely self-consistent.
-
-It exercises the shapes the plan calls out: the real ModemManager `GetManagedObjects`
-shape `a{oa{sa{sv}}}`, 64-bit `x`/`t` values above 2**53, variants, and a
-`PropertiesChanged` signal that carries an invalidated-properties array (not just changed
-values).
-
-Connects to the bus named by `DBUS_SESSION_BUS_ADDRESS` (set by `dbus-run-session`),
-claims a well-known name, prints `READY` on stdout once serving, then runs the main loop.
-"""
-
-import sys
-
-import dbus
-import dbus.mainloop.glib
-import dbus.service
-from gi.repository import GLib
-
-BUS_NAME = "tv.ceralive.ModemStackPy"
-OBJECT_PATH = "/tv/ceralive/pyfake"
-IFACE = "tv.ceralive.ModemStackPy.Conformance"
-PROPERTIES_IFACE = "org.freedesktop.DBus.Properties"
-
-INT64_MAX = 2**63 - 1
-UINT64_MAX = 2**64 - 1
-
-
-class ConformanceProducer(dbus.service.Object):
-    @dbus.service.method(IFACE, in_signature="", out_signature="a{oa{sa{sv}}}")
-    def GetManagedObjects(self):
-        return dbus.Dictionary(
-            {
-                dbus.ObjectPath("/org/freedesktop/ModemManager1/Modem/0"): dbus.Dictionary(
-                    {
-                        "org.freedesktop.ModemManager1.Modem": dbus.Dictionary(
-                            {
-                                "SupportedCapabilities": dbus.UInt64(UINT64_MAX, variant_level=1),
-                                "MaxBearers": dbus.Int64(-INT64_MAX, variant_level=1),
-                                "SignalQuality": dbus.UInt32(87, variant_level=1),
-                                "DeviceIdentifier": dbus.String("py-device-0", variant_level=1),
-                            },
-                            signature="sv",
-                        ),
-                    },
-                    signature="sa{sv}",
-                ),
-            },
-            signature="oa{sa{sv}}",
-        )
-
-    @dbus.service.method(IFACE, in_signature="", out_signature="x")
-    def GetInt64(self):
-        return dbus.Int64(INT64_MAX)
-
-    @dbus.service.method(IFACE, in_signature="", out_signature="t")
-    def GetUint64(self):
-        return dbus.UInt64(UINT64_MAX)
-
-    @dbus.service.method(IFACE, in_signature="", out_signature="v")
-    def GetVariant(self):
-        return dbus.UInt64(UINT64_MAX, variant_level=1)
-
-    @dbus.service.method(IFACE, in_signature="x", out_signature="x")
-    def EchoInt64(self, value):
-        return dbus.Int64(value)
-
-    @dbus.service.method(IFACE, in_signature="t", out_signature="t")
-    def EchoUint64(self, value):
-        return dbus.UInt64(value)
-
-    @dbus.service.method(IFACE, in_signature="t", out_signature="s")
-    def DescribeUint64(self, value):
-        return dbus.String(str(int(value)))
-
-    @dbus.service.method(IFACE, in_signature="", out_signature="")
-    def TriggerPropertiesChanged(self):
-        changed = dbus.Dictionary(
-            {
-                "AccessTechnologies": dbus.UInt64(UINT64_MAX, variant_level=1),
-                "SignalQuality": dbus.UInt32(42, variant_level=1),
-            },
-            signature="sv",
-        )
-        invalidated = dbus.Array(["OperatorName", "OperatorCode"], signature="s")
-        self.PropertiesChanged(IFACE, changed, invalidated)
-
-    @dbus.service.signal(PROPERTIES_IFACE, signature="sa{sv}as")
-    def PropertiesChanged(self, interface_name, changed_properties, invalidated_properties):
-        pass
-
-
-def main():
-    dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
-    bus = dbus.SessionBus()
-    name = dbus.service.BusName(BUS_NAME, bus)
-    ConformanceProducer(bus, OBJECT_PATH)
-    # Signal readiness only after the name is owned and the object is exported.
-    sys.stdout.write("READY\n")
-    sys.stdout.flush()
-    GLib.MainLoop().run()
-
-
-if __name__ == "__main__":
-    main()

package/src/transport/test-support/private-bus.ts

@@ -1,66 +0,0 @@
-// A dedicated private `dbus-daemon` at a FIXED socket path, for the reconnect test.
-//
-// The outer `dbus-run-session` bus is shared by the whole `bun test` run, so the
-// destructive kill/restart cannot happen there. This helper owns a throwaway daemon we
-// can kill and respawn at the same socket path, so the transport reconnects to "the same
-// bus" exactly as it would after a real bus restart on a device.
-
-import { existsSync, mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-export class PrivateBus {
-	readonly socket: string;
-	readonly address: string;
-	readonly #dir: string;
-	#proc: ReturnType<typeof Bun.spawn> | null = null;
-
-	constructor() {
-		this.#dir = mkdtempSync(join(tmpdir(), 'ceralive-dbus-'));
-		this.socket = join(this.#dir, 'bus');
-		this.address = `unix:path=${this.socket}`;
-	}
-
-	async start(): Promise<void> {
-		// A SIGKILL leaves the socket file behind; dbus-daemon refuses to bind over it.
-		if (existsSync(this.socket)) {
-			rmSync(this.socket, { force: true });
-		}
-		this.#proc = Bun.spawn(
-			['dbus-daemon', '--session', `--address=${this.address}`, '--nofork', '--nopidfile'],
-			{ stdout: 'ignore', stderr: 'ignore' },
-		);
-		await this.#waitForSocket();
-	}
-
-	kill(): void {
-		this.#proc?.kill('SIGKILL');
-		this.#proc = null;
-	}
-
-	async restart(): Promise<void> {
-		this.kill();
-		await sleep(50);
-		await this.start();
-	}
-
-	async stop(): Promise<void> {
-		this.kill();
-		await sleep(20);
-		rmSync(this.#dir, { recursive: true, force: true });
-	}
-
-	async #waitForSocket(): Promise<void> {
-		for (let attempt = 0; attempt < 300; attempt += 1) {
-			if (existsSync(this.socket)) {
-				// Socket exists → daemon is listening; a short grace covers the accept race.
-				await sleep(30);
-				return;
-			}
-			await sleep(10);
-		}
-		throw new Error(`private dbus-daemon socket ${this.socket} never appeared`);
-	}
-}

package/src/transport/transport.ts

@@ -1,250 +0,0 @@
-// The D-Bus transport seam implementation.
-//
-// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface. This module owns the
-// connection lifecycle — handshake, a reconnect loop that re-issues every match rule after a
-// bus restart, and teardown — and delegates method-call dispatch to `./calls` and signal
-// subscription/match-rule tracking to `./signals`. Its single `message` listener fans out to
-// the signal registry, so subscribing never grows the listener count (the 100-cycle leak check).
-
-import { EventEmitter } from 'node:events';
-import { CallDispatcher, DEFAULT_CALL_TIMEOUT_MS } from './calls';
-import {
-	type CreateClientOptions,
-	createClient,
-	type RawBus,
-	type RawMessage,
-} from './dbus-native';
-import { DisconnectedError, TransportError } from './errors';
-import { SignalRegistry } from './signals';
-import type {
-	DbusTransport,
-	DbusTransportOptions,
-	MethodCall,
-	MethodReply,
-	SignalListener,
-	SignalSpec,
-	Subscription,
-	TransportEvent,
-} from './types';
-
-type State = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'closed';
-
-interface ResolvedReconnect {
-	readonly enabled: boolean;
-	readonly initialDelayMs: number;
-	readonly maxDelayMs: number;
-	readonly maxAttempts: number;
-}
-
-// Bound a single connect/auth attempt so a stalled handshake cannot freeze the reconnect
-// loop. A local unix-socket D-Bus connect completes in milliseconds; 2s is ample headroom
-// while keeping reconnect responsive after a bus restart.
-const CONNECT_TIMEOUT_MS = 2_000;
-const DEFAULT_RECONNECT: ResolvedReconnect = {
-	enabled: true,
-	initialDelayMs: 50,
-	maxDelayMs: 2_000,
-	maxAttempts: 0,
-};
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-class DbusTransportImpl implements DbusTransport {
-	readonly #options: DbusTransportOptions;
-	readonly #reconnect: ResolvedReconnect;
-	readonly #emitter = new EventEmitter();
-	readonly #calls: CallDispatcher;
-	readonly #signals: SignalRegistry;
-
-	#bus: RawBus | null = null;
-	#state: State = 'idle';
-	#closing = false;
-
-	// Bound once so the same references can be detached from a dead connection.
-	readonly #onMessage = (message: RawMessage): void => this.#signals.dispatch(message);
-	readonly #onConnectionError = (cause: unknown): void =>
-		this.#handleDrop(cause instanceof Error ? cause : new DisconnectedError(String(cause)));
-	readonly #onConnectionEnd = (): void =>
-		this.#handleDrop(new DisconnectedError('bus connection ended'));
-
-	constructor(options: DbusTransportOptions) {
-		this.#options = options;
-		this.#calls = new CallDispatcher(options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
-		this.#signals = new SignalRegistry({
-			currentBus: () => this.#bus,
-			isConnected: () => this.#state === 'connected',
-			emitError: (error) => this.#emitter.emit('error', error),
-		});
-		this.#reconnect = {
-			enabled: options.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
-			initialDelayMs: options.reconnect?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs,
-			maxDelayMs: options.reconnect?.maxDelayMs ?? DEFAULT_RECONNECT.maxDelayMs,
-			maxAttempts: options.reconnect?.maxAttempts ?? DEFAULT_RECONNECT.maxAttempts,
-		};
-		// Avoid MaxListeners warnings when many consumers observe transport events.
-		this.#emitter.setMaxListeners(0);
-	}
-
-	async connect(): Promise<void> {
-		if (this.#state === 'connected') {
-			return;
-		}
-		if (this.#closing) {
-			throw new TransportError('Transport is closed');
-		}
-		this.#state = 'connecting';
-		await this.#establish();
-		this.#emitter.emit('connected');
-	}
-
-	isConnected(): boolean {
-		return this.#state === 'connected';
-	}
-
-	async disconnect(): Promise<void> {
-		this.#closing = true;
-		this.#state = 'closed';
-		const bus = this.#bus;
-		this.#bus = null;
-		this.#calls.rejectAll(new DisconnectedError('transport closed'));
-		if (bus) {
-			this.#quiesce(bus);
-			await bus.disconnect().catch(() => undefined);
-		}
-	}
-
-	callMethod(call: MethodCall): Promise<MethodReply> {
-		return this.#calls.call(this.#bus, this.#state === 'connected', call);
-	}
-
-	subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
-		return this.#signals.subscribe(spec, listener);
-	}
-
-	subscriptionCount(): number {
-		return this.#signals.count();
-	}
-
-	on(event: TransportEvent, handler: (payload?: unknown) => void): void {
-		this.#emitter.on(event, handler);
-	}
-
-	off(event: TransportEvent, handler: (payload?: unknown) => void): void {
-		this.#emitter.off(event, handler);
-	}
-
-	// ── internals ──────────────────────────────────────────────────────────────────
-
-	async #establish(): Promise<void> {
-		const options: CreateClientOptions = { ReturnLongjs: true };
-		if (this.#options.socket !== undefined) {
-			options.socket = this.#options.socket;
-		} else if (this.#options.busAddress !== undefined) {
-			options.busAddress = this.#options.busAddress;
-		}
-
-		const bus = createClient(options);
-		try {
-			await new Promise<void>((resolve, reject) => {
-				const onConnect = (): void => {
-					cleanup();
-					resolve();
-				};
-				const onError = (error: unknown): void => {
-					cleanup();
-					reject(error instanceof Error ? error : new TransportError(String(error)));
-				};
-				const timer = setTimeout(() => {
-					cleanup();
-					reject(new TransportError(`bus connect timed out after ${CONNECT_TIMEOUT_MS}ms`));
-				}, CONNECT_TIMEOUT_MS);
-				const cleanup = (): void => {
-					clearTimeout(timer);
-					bus.connection.removeListener('connect', onConnect);
-					bus.connection.removeListener('error', onError);
-				};
-				bus.connection.once('connect', onConnect);
-				bus.connection.once('error', onError);
-			});
-
-			bus.connection.on('message', this.#onMessage as (...args: unknown[]) => void);
-			bus.connection.on('error', this.#onConnectionError);
-			bus.connection.on('end', this.#onConnectionEnd);
-
-			// Re-issue every live match rule so a reconnect resubscribes transparently.
-			await this.#signals.reissueRules(bus);
-
-			this.#bus = bus;
-			this.#state = 'connected';
-		} catch (error) {
-			this.#detachHandlers(bus);
-			bus.connection.removeAllListeners();
-			bus.connection.on('error', () => undefined);
-			try {
-				bus.connection.end();
-			} catch {
-				// The half-open connection is already dead; nothing to close.
-			}
-			throw error;
-		}
-	}
-
-	#detachHandlers(bus: RawBus): void {
-		bus.connection.removeListener('message', this.#onMessage as (...args: unknown[]) => void);
-		bus.connection.removeListener('error', this.#onConnectionError);
-		bus.connection.removeListener('end', this.#onConnectionEnd);
-	}
-
-	// Detach our handlers from a dead connection, then swallow any late socket error it
-	// still emits — without a listener, Node re-throws an EventEmitter 'error' and crashes
-	// the process mid-reconnect.
-	#quiesce(bus: RawBus): void {
-		this.#detachHandlers(bus);
-		bus.connection.on('error', () => undefined);
-	}
-
-	#handleDrop(cause: unknown): void {
-		if (this.#closing) {
-			return;
-		}
-		if (this.#state === 'disconnected' || this.#state === 'reconnecting') {
-			return;
-		}
-		this.#state = 'disconnected';
-		if (this.#bus) {
-			this.#quiesce(this.#bus);
-		}
-		this.#bus = null;
-		this.#calls.rejectAll(cause);
-		this.#emitter.emit('disconnected', cause);
-		if (this.#reconnect.enabled) {
-			void this.#reconnectLoop();
-		}
-	}
-
-	async #reconnectLoop(): Promise<void> {
-		this.#state = 'reconnecting';
-		let delay = this.#reconnect.initialDelayMs;
-		let attempt = 0;
-		while (!this.#closing) {
-			attempt += 1;
-			try {
-				await this.#establish();
-				this.#emitter.emit('reconnected');
-				return;
-			} catch (error) {
-				if (this.#reconnect.maxAttempts > 0 && attempt >= this.#reconnect.maxAttempts) {
-					this.#state = 'disconnected';
-					this.#emitter.emit('error', error);
-					return;
-				}
-				await sleep(delay);
-				delay = Math.min(delay * 2, this.#reconnect.maxDelayMs);
-			}
-		}
-	}
-}
-
-export function createDbusTransport(options: DbusTransportOptions = {}): DbusTransport {
-	return new DbusTransportImpl(options);
-}

package/src/transport/types.ts

@@ -1,118 +0,0 @@
-// Public value and message types for the D-Bus transport seam.
-//
-// These types are the transport's own vocabulary. None of the underlying
-// `@httptoolkit/dbus-native` types appear here or in `./index.ts`, so the package's
-// public surface never leaks the library — swapping the implementation (see README:
-// documented fallback `@particle/dbus-next`) would not change a single caller type.
-
-// A decoded / encodable D-Bus value.
-//
-// 64-bit integers (`x`, `t`) are ALWAYS `bigint`, never `number`. Byte arrays (`ay`)
-// are `Uint8Array`. Arrays, structs, and dict entries are all plain arrays; a dict
-// `a{KV}` decodes to an array of `[key, value]` entry pairs, preserving order and
-// tolerating duplicate/non-string keys losslessly. Variants are wrapped in
-// `DbusVariant` so their inner signature survives a round-trip.
-export type DbusValue = string | number | boolean | bigint | Uint8Array | DbusVariant | DbusValue[];
-
-// A D-Bus variant (`v`): a value tagged with the signature of its contained type.
-export interface DbusVariant {
-	readonly signature: string;
-	readonly value: DbusValue;
-}
-
-// Construct a variant for encoding, e.g. `variant('u', 42)` or `variant('t', 5n)`.
-export function variant(signature: string, value: DbusValue): DbusVariant {
-	return { signature, value };
-}
-
-// Narrowing guard for a decoded variant.
-export function isVariant(value: DbusValue): value is DbusVariant {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		!Array.isArray(value) &&
-		!(value instanceof Uint8Array) &&
-		typeof (value as DbusVariant).signature === 'string' &&
-		'value' in value
-	);
-}
-
-// An outgoing method call.
-export interface MethodCall {
-	readonly destination: string;
-	readonly path: string;
-	readonly interface: string;
-	readonly member: string;
-	// D-Bus signature of `args`. Omit (or empty) for a no-argument call.
-	readonly signature?: string;
-	readonly args?: readonly DbusValue[];
-	// Per-call reply timeout in ms. Defaults to the transport's configured timeout.
-	readonly timeoutMs?: number;
-}
-
-// A decoded method reply.
-export interface MethodReply {
-	readonly signature: string;
-	readonly body: DbusValue[];
-}
-
-// A signal subscription filter. `interface` and `member` are required; `path` and
-// `sender` narrow further when supplied (MM emits the same signal from many paths).
-export interface SignalSpec {
-	readonly interface: string;
-	readonly member: string;
-	readonly path?: string;
-	readonly sender?: string;
-}
-
-// A decoded signal delivered to a subscriber.
-export interface SignalEvent {
-	readonly path: string;
-	readonly interface: string;
-	readonly member: string;
-	readonly sender: string | undefined;
-	readonly signature: string;
-	readonly body: DbusValue[];
-}
-
-export type SignalListener = (event: SignalEvent) => void;
-
-// Handle returned by `subscribeSignal`; call `unsubscribe` to detach the listener and
-// (when it was the last subscriber for its match rule) drop the bus-side match.
-export interface Subscription {
-	unsubscribe(): Promise<void>;
-}
-
-export type TransportEvent = 'connected' | 'reconnected' | 'disconnected' | 'error';
-
-export interface DbusTransportOptions {
-	// Encoded bus address. Defaults to `DBUS_SESSION_BUS_ADDRESS`.
-	readonly busAddress?: string;
-	// Unix socket path (an alternative to `busAddress` for a private test bus).
-	readonly socket?: string;
-	// Default per-call reply timeout in ms (default 30000).
-	readonly callTimeoutMs?: number;
-	// Automatic reconnect after an unexpected bus drop (default enabled).
-	readonly reconnect?: ReconnectOptions;
-}
-
-export interface ReconnectOptions {
-	readonly enabled?: boolean;
-	readonly initialDelayMs?: number;
-	readonly maxDelayMs?: number;
-	// 0 = retry forever (default).
-	readonly maxAttempts?: number;
-}
-
-// The transport seam. This is the entire surface the A3.x D-Bus backend builds on.
-export interface DbusTransport {
-	connect(): Promise<void>;
-	disconnect(): Promise<void>;
-	isConnected(): boolean;
-	callMethod(call: MethodCall): Promise<MethodReply>;
-	subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription>;
-	on(event: TransportEvent, handler: (payload?: unknown) => void): void;
-	off(event: TransportEvent, handler: (payload?: unknown) => void): void;
-	// Number of live signal subscriptions — exposed for leak assertions in tests.
-	subscriptionCount(): number;
-}