@ceralive/modem-control 1.2.0 → 1.3.0

package/dist/providers/network-manager/observe-fold.js

@@ -0,0 +1,109 @@
+import { freshObservation, observedState, unavailableObservation } from '../../observations/index.js';
+import { targetIfname } from './state.js';
+import { boundBearer, unboundBearer } from './types.js';
+const SOURCE = 'networkmanager';
+const TRANSITIONAL_STATES = new Set([
+    'prepare',
+    'config',
+    'need-auth',
+    'ip-config',
+    'ip-check',
+    'secondaries',
+    'deactivating',
+]);
+export function foldObservation(slotsByConnection, observedGeneration, input) {
+    const generation = input.context.generation;
+    if (observedGeneration !== null && generation < observedGeneration) {
+        return {
+            generation: observedGeneration,
+            result: {
+                kind: 'refused',
+                reason: 'superseded-generation',
+                currentGeneration: observedGeneration,
+            },
+        };
+    }
+    const devices = new Map(input.devices.map((device) => [device.ifname, device]));
+    const outcomes = [];
+    const losses = [];
+    for (const [id, slots] of slotsByConnection) {
+        const ifname = targetIfname(slots);
+        if (ifname === undefined) {
+            continue;
+        }
+        const device = devices.get(ifname);
+        slots.observed = observedState(device === undefined
+            ? unavailableObservation(SOURCE, input.context, 'device-absent')
+            : freshObservation(SOURCE, input.context, observedBearer(device)));
+        const outcome = classifyApplied(id, slots, ifname, device, input.context.observedAt);
+        outcomes.push({ connectionId: id, outcome });
+        if (outcome.status === 'lost') {
+            losses.push(outcome.loss);
+        }
+    }
+    return {
+        generation,
+        result: {
+            kind: 'accepted',
+            generation,
+            observedAt: input.context.observedAt,
+            outcomes,
+            losses,
+        },
+    };
+}
+function classifyApplied(id, slots, ifname, device, observedAt) {
+    const applied = slots.applied;
+    if (applied === null) {
+        return { status: 'unapplied' };
+    }
+    const lose = (reason) => {
+        slots.applied = null;
+        return {
+            status: 'lost',
+            loss: {
+                connectionId: id,
+                deviceIfname: ifname,
+                reason,
+                lostAt: observedAt,
+                generation: applied.generation,
+                previous: applied,
+            },
+        };
+    };
+    if (device === undefined) {
+        return lose('interface-absent');
+    }
+    if (device.state === 'failed') {
+        return lose('activation-failed');
+    }
+    if (applied.configuration.kind === 'unbound') {
+        return device.activeConnection === undefined
+            ? { status: 'retained', applied }
+            : lose('connection-replaced');
+    }
+    if (device.activeConnection === undefined) {
+        return lose('interface-detached');
+    }
+    if (device.activeConnection.connectionId !== id) {
+        return lose('connection-replaced');
+    }
+    if (device.state === 'activated') {
+        return { status: 'retained', applied };
+    }
+    return TRANSITIONAL_STATES.has(device.state)
+        ? { status: 'pending', applied, deviceState: device.state }
+        : lose('interface-detached');
+}
+function observedBearer(device) {
+    const active = device.activeConnection;
+    return active === undefined
+        ? unboundBearer(device.ifname)
+        : boundBearer({
+            connectionId: active.connectionId,
+            deviceIfname: device.ifname,
+            apn: active.apn,
+            autoConfig: active.autoConfig,
+            homeOnly: active.homeOnly,
+        });
+}

package/dist/providers/network-manager/projection.d.ts

@@ -0,0 +1,5 @@
+import type { ModemStateView, NormalizationContext } from '../../observations/index.js';
+import type { ConnectionId } from '../../ports/index.js';
+import type { ConnectionSlots } from './state.js';
+import type { NmBearerState } from './types.js';
+export declare function projectStateView(slotsByConnection: ReadonlyMap<ConnectionId, ConnectionSlots>, id: ConnectionId, context: NormalizationContext): ModemStateView<NmBearerState, NmBearerState, NmBearerState> | null;

package/dist/providers/network-manager/projection.js

@@ -0,0 +1,14 @@
+import { observedState, unavailableObservation } from '../../observations/index.js';
+const SOURCE = 'networkmanager';
+export function projectStateView(slotsByConnection, id, context) {
+    const slots = slotsByConnection.get(id);
+    if (slots === undefined) {
+        return null;
+    }
+    return {
+        desired: slots.desired,
+        applied: slots.applied,
+        observed: slots.observed ??
+            observedState(unavailableObservation(SOURCE, context, 'provider-unavailable')),
+    };
+}

package/dist/providers/network-manager/state.d.ts

@@ -0,0 +1,10 @@
+import type { AppliedConfiguration, DesiredProfile, ObservedState } from '../../observations/index.js';
+import type { ConnectionId, DeviceIfname } from '../../ports/index.js';
+import type { NmBearerState } from './types.js';
+export interface ConnectionSlots {
+    desired: DesiredProfile<NmBearerState> | null;
+    applied: AppliedConfiguration<NmBearerState> | null;
+    observed: ObservedState<NmBearerState> | null;
+}
+export declare function slotsFor(slotsByConnection: Map<ConnectionId, ConnectionSlots>, id: ConnectionId): ConnectionSlots;
+export declare function targetIfname(slots: ConnectionSlots): DeviceIfname | undefined;

package/dist/providers/network-manager/state.js

@@ -0,0 +1,16 @@
+export function slotsFor(slotsByConnection, id) {
+    const existing = slotsByConnection.get(id);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = { desired: null, applied: null, observed: null };
+    slotsByConnection.set(id, created);
+    return created;
+}
+export function targetIfname(slots) {
+    const state = slots.applied?.configuration ?? slots.desired?.profile;
+    if (state === undefined) {
+        return undefined;
+    }
+    return state.kind === 'bound' ? state.binding.deviceIfname : state.deviceIfname;
+}

package/dist/providers/ufi-himi/session.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseJsonWith } from '../../json-boundary.js';
 import { UFI_API_PATH, } from './transport.js';
 /** The HIMI firmware's own word for "your session is gone". */
 export const UFI_SESSION_REFUSAL = 'SessionOut';
@@ -9,22 +10,7 @@ const ufiReplySchema = z.object({
     params: flatRecordSchema.optional(),
 });
 export function parseUfiReply(body) {
-    const parsed = z
-        .string()
-        .transform((value, context) => {
-        try {
-            return JSON.parse(value);
-        }
-        catch (error) {
-            if (!(error instanceof SyntaxError))
-                throw error;
-            context.addIssue({ code: 'custom', message: 'invalid JSON' });
-            return z.NEVER;
-        }
-    })
-        .pipe(ufiReplySchema)
-        .safeParse(body);
-    return parsed.success ? parsed.data : undefined;
+    return parseJsonWith(ufiReplySchema, body);
 }
 /**
  * Session acquisition, bounded to ONE login per physical modem per generation.

package/dist/providers/zte-goform/session.js

@@ -1,24 +1,10 @@
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
+import { parseJsonWith } from '../../json-boundary.js';
 import { ZTE_EVIDENCE_CMD, ZTE_PATHS, ZTE_UNKNOWN_PROFILE, zteProfileById, zteProfilesForFirmware, } from './provider.js';
 const flatRecordSchema = z.record(z.string(), z.union([z.string(), z.number()]));
 export function parseZteRecord(body) {
-    const result = z
-        .string()
-        .transform((value, context) => {
-        try {
-            return JSON.parse(value);
-        }
-        catch (error) {
-            if (!(error instanceof SyntaxError))
-                throw error;
-            context.addIssue({ code: 'custom', message: 'invalid JSON' });
-            return z.NEVER;
-        }
-    })
-        .pipe(flatRecordSchema)
-        .safeParse(body);
-    return result.success ? result.data : undefined;
+    return parseJsonWith(flatRecordSchema, body);
 }
 function stokCookie(response) {
     const expected = 'set-cookie';

package/dist/safety/flock-resource-ownership.js

@@ -8,16 +8,26 @@ export class FlockResourceOwnershipError extends Error {
         this.detail = detail;
     }
 }
+const STARTUP_DEADLINE_MS = 1_000;
+const STARTUP_OUTPUT_LIMIT_BYTES = 64 * 1024;
 export function createFlockResourceOwnershipPort(options) {
     return {
         async acquire() {
             const child = spawn(options.flockBinary ?? 'flock', ['--exclusive', '--nonblock', '--no-fork', options.lockPath, '/bin/cat'], { stdio: ['pipe', 'pipe', 'pipe'] });
+            const closed = childClosed(child);
             if (child.pid === undefined) {
+                await reapChild(child, closed);
                 throw new FlockResourceOwnershipError('helper started without a process id');
             }
             const holder = { pid: child.pid, startedAtEpochMs: Date.now() };
-            const closed = childClosed(child);
-            const started = await childStarted(child, options.lockPath, holder);
+            let started;
+            try {
+                started = await childStarted(child, options.lockPath, holder);
+            }
+            catch (error) {
+                await reapChild(child, closed);
+                throw error;
+            }
             if (started.status === 'closed') {
                 if (started.code === 1) {
                     const holder = await readHolder(options.lockPath);
@@ -55,36 +65,86 @@ function createLease(child, closed, holder) {
 function childClosed(child) {
     return new Promise((resolve) => child.once('close', () => resolve()));
 }
+async function reapChild(child, closed) {
+    if (child.exitCode === null && child.signalCode === null) {
+        child.kill('SIGKILL');
+    }
+    await closed;
+}
 function childStarted(child, lockPath, holder) {
     return new Promise((resolve, reject) => {
         let stdout = '';
         let stderr = '';
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let acknowledged = false;
         let settled = false;
+        const startupDeadline = setTimeout(() => fail(new FlockResourceOwnershipError('helper startup deadline exceeded')), STARTUP_DEADLINE_MS);
+        const cleanup = () => {
+            clearTimeout(startupDeadline);
+            child.stdout.off('data', onStdout);
+            child.stderr.off('data', onStderr);
+            child.off('close', onClose);
+            child.off('error', fail);
+            child.stdin.off('error', fail);
+        };
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
+            cleanup();
             resolve(result);
         };
-        child.stderr.on('data', (chunk) => {
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onStderr = (chunk) => {
+            stderrBytes += chunk.length;
+            if (stderrBytes > STARTUP_OUTPUT_LIMIT_BYTES) {
+                fail(new FlockResourceOwnershipError('helper startup output limit exceeded on stderr'));
+                return;
+            }
             stderr += chunk.toString('utf8');
-        });
-        child.stdout.on('data', (chunk) => {
+        };
+        const onStdout = (chunk) => {
+            stdoutBytes += chunk.length;
+            if (stdoutBytes > STARTUP_OUTPUT_LIMIT_BYTES) {
+                fail(new FlockResourceOwnershipError('helper startup output limit exceeded on stdout'));
+                return;
+            }
             stdout += chunk.toString('utf8');
             const newline = stdout.indexOf('\n');
             if (newline < 0)
                 return;
             const acquired = parseAcquiredLine(stdout.slice(0, newline));
-            if (acquired === undefined || settled)
+            if (acquired === undefined || acknowledged)
                 return;
-            settled = true;
-            void writeFile(lockPath, `${JSON.stringify(holder)}\n`, { mode: 0o600 }).then(() => resolve({ status: 'acquired', holder }), (error) => {
-                child.stdin.end();
-                reject(error);
+            acknowledged = true;
+            void writeFile(lockPath, `${JSON.stringify(holder)}\n`, { mode: 0o600 }).then(() => finish({ status: 'acquired', holder }), fail);
+        };
+        const onClose = (code) => finish({ status: 'closed', code, stderr: stderr.trim() });
+        child.stderr.on('data', onStderr);
+        child.stdout.on('data', onStdout);
+        child.once('close', onClose);
+        child.once('error', fail);
+        child.stdin.once('error', fail);
+        try {
+            child.stdin.write(`${JSON.stringify({ type: 'acquired', holder })}\n`, (error) => {
+                if (error !== null)
+                    fail(error);
             });
-        });
-        child.once('close', (code) => finish({ status: 'closed', code, stderr: stderr.trim() }));
-        child.stdin.write(`${JSON.stringify({ type: 'acquired', holder })}\n`);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                fail(error);
+                return;
+            }
+            fail(new FlockResourceOwnershipError('helper stdin failed with a non-error value'));
+        }
     });
 }
 function parseAcquiredLine(line) {

package/dist/transport/transport.d.ts

@@ -1,2 +1,21 @@
+import { type CreateClientOptions, type RawBus } from './dbus-native.js';
+import { TransportError } from './errors.js';
 import type { DbusTransport, DbusTransportOptions } from './types.js';
-export declare function createDbusTransport(options?: DbusTransportOptions): DbusTransport;
+export interface TransportTimingPolicy {
+    readonly connectTimeoutMs: number;
+    readonly callTimeoutMs: number;
+}
+export declare const DEFAULT_TRANSPORT_TIMING: TransportTimingPolicy;
+export interface DbusTransportSeamOptions extends DbusTransportOptions {
+    readonly timing?: Partial<TransportTimingPolicy>;
+}
+export type TransportTeardownPhase = 'disconnect' | 'establish-abort';
+export type TransportTeardownStep = 'bus-disconnect' | 'connection-end';
+export declare class TransportTeardownFailure extends TransportError {
+    readonly phase: TransportTeardownPhase;
+    readonly step: TransportTeardownStep;
+    constructor(phase: TransportTeardownPhase, step: TransportTeardownStep, cause: unknown);
+}
+export type BusFactory = (options: CreateClientOptions) => RawBus;
+export declare function createDbusTransport(options?: DbusTransportSeamOptions): DbusTransport;
+export declare function createDbusTransportForTest(options: DbusTransportSeamOptions, busFactory: BusFactory): DbusTransport;

package/dist/transport/transport.js

@@ -10,33 +10,65 @@ import { CallDispatcher, DEFAULT_CALL_TIMEOUT_MS } from './calls.js';
 import { createClient, } from './dbus-native.js';
 import { DisconnectedError, TransportError } from './errors.js';
 import { SignalRegistry } from './signals.js';
-// 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 = {
     enabled: true,
     initialDelayMs: 50,
     maxDelayMs: 2_000,
     maxAttempts: 0,
 };
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const DEFAULT_TRANSPORT_TIMING = {
+    connectTimeoutMs: 2_000,
+    callTimeoutMs: DEFAULT_CALL_TIMEOUT_MS,
+};
+function resolveTimingPolicy(options) {
+    return {
+        connectTimeoutMs: options.timing?.connectTimeoutMs ?? DEFAULT_TRANSPORT_TIMING.connectTimeoutMs,
+        callTimeoutMs: options.timing?.callTimeoutMs ??
+            options.callTimeoutMs ??
+            DEFAULT_TRANSPORT_TIMING.callTimeoutMs,
+    };
+}
+// A teardown step failed. This is REPORTED on the transport's existing `error` event and is
+// never thrown: by the time it happens the caller is already closing (or the establish error
+// is already on its way up), so escalating would replace the failure a caller must act on with
+// one they cannot. It is an `Error` subclass because everything else on that event is —
+// consumers narrow with `instanceof` and branch on `phase` / `step`.
+export class TransportTeardownFailure extends TransportError {
+    phase;
+    step;
+    constructor(phase, step, cause) {
+        super(`D-Bus transport teardown step "${step}" failed during ${phase}`, { cause });
+        this.name = 'TransportTeardownFailure';
+        this.phase = phase;
+        this.step = step;
+    }
+}
 class DbusTransportImpl {
     #options;
     #reconnect;
+    #timing;
+    #createBus;
     #emitter = new EventEmitter();
     #calls;
     #signals;
     #bus = null;
     #state = 'idle';
     #closing = false;
+    // The single live reconnect loop, retained rather than fired and forgotten: a second drop
+    // cannot start a second loop, and `disconnect()` has something to await so it can promise
+    // that no loop outlives it.
+    #reconnectLoopPromise = null;
+    // Set only while that loop is parked in its backoff sleep; calling it cuts the sleep short.
+    #wakeBackoff = null;
     // Bound once so the same references can be detached from a dead connection.
     #onMessage = (message) => this.#signals.dispatch(message);
     #onConnectionError = (cause) => this.#handleDrop(cause instanceof Error ? cause : new DisconnectedError(String(cause)));
     #onConnectionEnd = () => this.#handleDrop(new DisconnectedError('bus connection ended'));
-    constructor(options) {
+    constructor(options, createBus) {
         this.#options = options;
-        this.#calls = new CallDispatcher(options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
+        this.#createBus = createBus;
+        this.#timing = resolveTimingPolicy(options);
+        this.#calls = new CallDispatcher(this.#timing.callTimeoutMs);
         this.#signals = new SignalRegistry({
             currentBus: () => this.#bus,
             isConnected: () => this.#state === 'connected',
@@ -70,10 +102,17 @@ class DbusTransportImpl {
         this.#state = 'closed';
         const bus = this.#bus;
         this.#bus = null;
+        // Capture the loop BEFORE waking it: waking lets it run to completion, which clears the
+        // field, and a `disconnect()` that lost the handle could not wait for it.
+        const loop = this.#reconnectLoopPromise;
+        this.#cancelBackoff();
         this.#calls.rejectAll(new DisconnectedError('transport closed'));
         if (bus) {
             this.#quiesce(bus);
-            await bus.disconnect().catch(() => undefined);
+            await this.#closeBus(bus, 'disconnect');
+        }
+        if (loop) {
+            await loop;
         }
     }
     callMethod(call) {
@@ -100,7 +139,8 @@ class DbusTransportImpl {
         else if (this.#options.busAddress !== undefined) {
             options.busAddress = this.#options.busAddress;
         }
-        const bus = createClient(options);
+        const connectTimeoutMs = this.#timing.connectTimeoutMs;
+        const bus = this.#createBus(options);
         try {
             await new Promise((resolve, reject) => {
                 const onConnect = () => {
@@ -113,8 +153,8 @@ class DbusTransportImpl {
                 };
                 const timer = setTimeout(() => {
                     cleanup();
-                    reject(new TransportError(`bus connect timed out after ${CONNECT_TIMEOUT_MS}ms`));
-                }, CONNECT_TIMEOUT_MS);
+                    reject(new TransportError(`bus connect timed out after ${connectTimeoutMs}ms`));
+                }, connectTimeoutMs);
                 const cleanup = () => {
                     clearTimeout(timer);
                     bus.connection.removeListener('connect', onConnect);
@@ -128,6 +168,12 @@ class DbusTransportImpl {
             bus.connection.on('end', this.#onConnectionEnd);
             // Re-issue every live match rule so a reconnect resubscribes transparently.
             await this.#signals.reissueRules(bus);
+            if (this.#closing) {
+                // `disconnect()` landed while this attempt was in flight. Fail the attempt so the
+                // shared catch below tears the fresh connection down — a closed transport must
+                // never publish a live bus that nobody is left to close.
+                throw new TransportError('Transport is closed');
+            }
             this.#bus = bus;
             this.#state = 'connected';
         }
@@ -138,8 +184,12 @@ class DbusTransportImpl {
             try {
                 bus.connection.end();
             }
-            catch {
-                // The half-open connection is already dead; nothing to close.
+            catch (cause) {
+                // The half-open connection is usually already dead, so this ordinarily does
+                // nothing. When it does fail, that is a real teardown outcome and it is reported
+                // rather than discarded — but never rethrown, because `error` is the failure the
+                // caller actually needs to see.
+                this.#reportTeardownFailure('establish-abort', 'connection-end', cause);
             }
             throw error;
         }
@@ -156,6 +206,27 @@ class DbusTransportImpl {
         this.#detachHandlers(bus);
         bus.connection.on('error', () => undefined);
     }
+    // A rejected `bus.disconnect()` used to vanish into `.catch(() => undefined)`, leaving a
+    // consumer no way to learn that a socket it believed closed never actually was.
+    async #closeBus(bus, phase) {
+        try {
+            await bus.disconnect();
+        }
+        catch (cause) {
+            this.#reportTeardownFailure(phase, 'bus-disconnect', cause);
+        }
+    }
+    #reportTeardownFailure(phase, step, cause) {
+        this.#emitObservable('error', new TransportTeardownFailure(phase, step, cause));
+    }
+    // Node re-throws an unobserved EventEmitter 'error', which would turn a report ABOUT a
+    // failed teardown into a process crash on the path that is already unwinding.
+    #emitObservable(event, payload) {
+        if (event === 'error' && this.#emitter.listenerCount('error') === 0) {
+            return;
+        }
+        this.#emitter.emit(event, payload);
+    }
     #handleDrop(cause) {
         if (this.#closing) {
             return;
@@ -171,8 +242,25 @@ class DbusTransportImpl {
         this.#calls.rejectAll(cause);
         this.#emitter.emit('disconnected', cause);
         if (this.#reconnect.enabled) {
-            void this.#reconnectLoop();
+            this.#startReconnectLoop();
+        }
+    }
+    // The state guard above already blocks the common double-drop, but holding the promise
+    // makes the single-loop property structural instead of a consequence of state ordering,
+    // and it is what lets `disconnect()` wait for the loop it just cancelled.
+    #startReconnectLoop() {
+        if (this.#reconnectLoopPromise !== null) {
+            return;
         }
+        const loop = this.#reconnectLoop().catch((error) => {
+            this.#emitObservable('error', error);
+        });
+        this.#reconnectLoopPromise = loop;
+        void loop.then(() => {
+            if (this.#reconnectLoopPromise === loop) {
+                this.#reconnectLoopPromise = null;
+            }
+        });
     }
     async #reconnectLoop() {
         this.#state = 'reconnecting';
@@ -191,12 +279,41 @@ class DbusTransportImpl {
                     this.#emitter.emit('error', error);
                     return;
                 }
-                await sleep(delay);
+                await this.#backoff(delay);
                 delay = Math.min(delay * 2, this.#reconnect.maxDelayMs);
             }
         }
     }
+    // A plain `setTimeout` promise holds the loop — and the event loop — for the whole
+    // remaining delay after a caller has already asked for teardown. At the default 2s ceiling
+    // that is a 2s stall on every close landing mid-backoff, and an unbounded one for a caller
+    // that raised the ceiling.
+    #backoff(ms) {
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                if (this.#wakeBackoff === finish) {
+                    this.#wakeBackoff = null;
+                }
+                resolve();
+            };
+            const timer = setTimeout(finish, ms);
+            this.#wakeBackoff = finish;
+        });
+    }
+    #cancelBackoff() {
+        const wake = this.#wakeBackoff;
+        this.#wakeBackoff = null;
+        wake?.();
+    }
 }
 export function createDbusTransport(options = {}) {
-    return new DbusTransportImpl(options);
+    return new DbusTransportImpl(options, createClient);
+}
+// Deliberately NOT re-exported from `./index.ts`, whose public surface is pinned by
+// `no-library-leak.test.ts`. It exists so lifecycle failure paths — a bus whose `disconnect()`
+// rejects, a connection whose `end()` throws, a handshake that never completes — are reachable
+// deterministically, without a real `dbus-daemon` to break.
+export function createDbusTransportForTest(options, busFactory) {
+    return new DbusTransportImpl(options, busFactory);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/modem-control",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"type": "module",
 	"description": "Cellular modem control for CeraLive — ModemManager D-Bus backend, NetworkManager adapter, desired-state reconciler, USB composition-mode model, data-usage sampler.",
 	"license": "AGPL-3.0",