@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/safety/flock-resource-ownership.d.ts

@@ -0,0 +1,11 @@
+import type { ResourceOwnershipPort } from '../ports/index.js';
+export type FlockResourceOwnershipOptions = {
+    readonly lockPath: string;
+    readonly flockBinary?: string;
+};
+export declare class FlockResourceOwnershipError extends Error {
+    readonly detail: string;
+    readonly name = "FlockResourceOwnershipError";
+    constructor(detail: string);
+}
+export declare function createFlockResourceOwnershipPort(options: FlockResourceOwnershipOptions): ResourceOwnershipPort;

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

@@ -0,0 +1,138 @@
+import { spawn } from 'node:child_process';
+import { readFile, writeFile } from 'node:fs/promises';
+export class FlockResourceOwnershipError extends Error {
+    detail;
+    name = 'FlockResourceOwnershipError';
+    constructor(detail) {
+        super(`flock ownership failed: ${detail}`);
+        this.detail = detail;
+    }
+}
+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'] });
+            if (child.pid === undefined) {
+                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);
+            if (started.status === 'closed') {
+                if (started.code === 1) {
+                    const holder = await readHolder(options.lockPath);
+                    return {
+                        status: 'refused',
+                        reason: 'already-owned',
+                        ...(holder !== undefined && pidIsAlive(holder.pid) ? { holder } : {}),
+                    };
+                }
+                throw new FlockResourceOwnershipError(`helper exited ${started.code ?? 'by signal'}${started.stderr ? `: ${started.stderr}` : ''}`);
+            }
+            return {
+                status: 'acquired',
+                lease: createLease(child, closed, started.holder),
+            };
+        },
+    };
+}
+function createLease(child, closed, holder) {
+    let released = false;
+    return {
+        holder,
+        lost: closed.then(() => ({ reason: 'holder-exited' })),
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (child.exitCode === null && child.signalCode === null) {
+                child.stdin.end();
+            }
+            await closed;
+        },
+    };
+}
+function childClosed(child) {
+    return new Promise((resolve) => child.once('close', () => resolve()));
+}
+function childStarted(child, lockPath, holder) {
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+            const newline = stdout.indexOf('\n');
+            if (newline < 0)
+                return;
+            const acquired = parseAcquiredLine(stdout.slice(0, newline));
+            if (acquired === undefined || settled)
+                return;
+            settled = true;
+            void writeFile(lockPath, `${JSON.stringify(holder)}\n`, { mode: 0o600 }).then(() => resolve({ status: 'acquired', holder }), (error) => {
+                child.stdin.end();
+                reject(error);
+            });
+        });
+        child.once('close', (code) => finish({ status: 'closed', code, stderr: stderr.trim() }));
+        child.stdin.write(`${JSON.stringify({ type: 'acquired', holder })}\n`);
+    });
+}
+function parseAcquiredLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== 'object' || parsed === null || !('holder' in parsed))
+            return undefined;
+        return parseHolder(parsed.holder);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+async function readHolder(lockPath) {
+    try {
+        return parseHolder(JSON.parse(await readFile(lockPath, 'utf8')));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+function parseHolder(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (!('pid' in value) || !('startedAtEpochMs' in value))
+        return undefined;
+    if (typeof value.pid !== 'number' || !Number.isSafeInteger(value.pid) || value.pid <= 0) {
+        return undefined;
+    }
+    if (typeof value.startedAtEpochMs !== 'number' || !Number.isFinite(value.startedAtEpochMs)) {
+        return undefined;
+    }
+    return { pid: value.pid, startedAtEpochMs: value.startedAtEpochMs };
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ESRCH')
+            return false;
+        return true;
+    }
+}

package/dist/safety/index.d.ts

@@ -0,0 +1,2 @@
+export * from './composition-root.js';
+export * from './flock-resource-ownership.js';

package/dist/safety/index.js

@@ -0,0 +1,2 @@
+export * from './composition-root.js';
+export * from './flock-resource-ownership.js';

package/dist/sms/dbus-messaging.d.ts

@@ -0,0 +1,17 @@
+import { type DecodedProps } from '../backend/managed-objects.js';
+import type { SmsMessage, SmsObservationPort } from '../ports/sms.js';
+import type { DbusTransport } from '../transport/index.js';
+/** `org.freedesktop.ModemManager1.Sms` — one message object. */
+export declare const SMS_IFACE = "org.freedesktop.ModemManager1.Sms";
+/** Build one message from an SMS object's decoded `Sms` properties. */
+export declare function smsFromProps(path: string, props: DecodedProps | undefined): SmsMessage;
+export interface DbusSmsPortOptions {
+    readonly transport: DbusTransport;
+    /** The modem's ModemManager object path. */
+    readonly modemPath: string;
+    readonly destination?: string;
+    readonly cap?: number;
+    /** Called when a fold-time error must be surfaced without failing a read. */
+    readonly onError?: (error: unknown) => void;
+}
+export declare function createDbusSmsPort(options: DbusSmsPortOptions): SmsObservationPort;

package/dist/sms/dbus-messaging.js

@@ -0,0 +1,185 @@
+// The ModemManager Messaging adapter — LIST ONCE, then follow Added / Deleted.
+//
+// Three verbs, all reads: `Messaging.List` for the object paths,
+// `Properties.GetAll` per message, and a subscription to `Added` / `Deleted`.
+// There is no `Create`, no `Send`, no `Delete`, and none may be added — see
+// `../ports/sms.ts` for why that is permanent rather than staged, and
+// `readonly-gate.test.ts` for the lock.
+//
+// NEVER RE-LIST ON A TICK. MM tells us about every change, so a poll would cost
+// one method call per stored message per tick and still could not report an
+// arrival sooner than the tick it happened to land on. The ONLY re-list is on a
+// source RECONNECT, where the events that occurred while the bus was down were
+// never delivered and folding is therefore impossible; that re-list is published
+// as `resynced` so the consumer replaces its rows instead of merging (see
+// `inbox-store.ts`).
+//
+// A MESSAGE THAT VANISHES BETWEEN THE LIST AND ITS READ IS ORDINARY. The modem's
+// own storage rotates, so a failed per-message read SKIPS that message rather
+// than failing the whole inbox. A failed LIST is different — nothing was read at
+// all — and answers a typed refusal.
+import { MM_BUS_NAME, PROPERTIES_IFACE } from '../backend/constants.js';
+import { numberProp, stringProp } from '../backend/managed-objects.js';
+// The one definition of MM's Messaging interface name lives with the capability
+// probe that also keys on it; duplicating it here is how the two drift apart.
+import { MESSAGING_IFACE } from '../capability/detect.js';
+import { classifySmsFailure } from './mmcli-parse.js';
+import { normalizeSmsState, SMS_INBOX_CAP, selectReadablePaths, sortAndCapSms } from './normalize.js';
+/** `org.freedesktop.ModemManager1.Sms` — one message object. */
+export const SMS_IFACE = 'org.freedesktop.ModemManager1.Sms';
+/**
+ * `MMSmsState` (ModemManager `mm-enums.h`) as the port's own vocabulary. The
+ * index IS the enum value; an out-of-range value folds to `unknown` through
+ * {@link normalizeSmsState}, so a future MM state can never surface as a raw
+ * number an operator cannot act on.
+ */
+const SMS_STATE_BY_ORDINAL = [
+    'unknown',
+    'stored',
+    'receiving',
+    'received',
+    'sending',
+    'sent',
+];
+function stateFromOrdinal(ordinal) {
+    if (ordinal === undefined) {
+        return 'unknown';
+    }
+    return normalizeSmsState(SMS_STATE_BY_ORDINAL[ordinal]);
+}
+/** Build one message from an SMS object's decoded `Sms` properties. */
+export function smsFromProps(path, props) {
+    const from = stringProp(props, 'Number');
+    const timestamp = stringProp(props, 'Timestamp');
+    const index = path.slice(path.lastIndexOf('/') + 1);
+    return {
+        id: index,
+        ...(from !== undefined && from !== '' ? { from } : {}),
+        ...(timestamp !== undefined && timestamp !== '' ? { timestamp } : {}),
+        // A data-only (WAP/PDU) message carries no text at all; `''` says so.
+        text: stringProp(props, 'Text') ?? '',
+        state: stateFromOrdinal(numberProp(props, 'State')),
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createDbusSmsPort(options) {
+    const { transport, modemPath } = options;
+    const destination = options.destination ?? MM_BUS_NAME;
+    const cap = options.cap ?? SMS_INBOX_CAP;
+    const listeners = new Set();
+    const subscriptions = [];
+    let wiring;
+    let stopped = false;
+    const emit = (event) => {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+        }
+    };
+    const readMessage = async (path) => {
+        try {
+            const reply = await transport.callMethod({
+                destination,
+                path,
+                interface: PROPERTIES_IFACE,
+                member: 'GetAll',
+                signature: 's',
+                args: [SMS_IFACE],
+            });
+            return smsFromProps(path, reply.body[0]);
+        }
+        catch {
+            // Vanished between the list and this read — ordinary storage rotation.
+            // Nothing is logged: the error text is the only place a body could hide.
+            return undefined;
+        }
+    };
+    const listInbox = async () => {
+        let paths;
+        try {
+            const reply = await transport.callMethod({
+                destination,
+                path: modemPath,
+                interface: MESSAGING_IFACE,
+                member: 'List',
+            });
+            paths = Array.isArray(reply.body[0]) ? reply.body[0] : [];
+        }
+        catch (error) {
+            return { ok: false, reason: classifySmsFailure(describe(error)) };
+        }
+        const candidates = selectReadablePaths(paths.filter((value) => typeof value === 'string'), cap);
+        const messages = [];
+        for (const path of candidates) {
+            const message = await readMessage(path);
+            if (message !== undefined) {
+                messages.push(message);
+            }
+        }
+        return { ok: true, messages: sortAndCapSms(messages, cap) };
+    };
+    const resync = async () => {
+        const result = await listInbox();
+        if (result.ok) {
+            emit({ kind: 'resynced', messages: result.messages });
+        }
+    };
+    const onAdded = async (body) => {
+        const path = body[0];
+        if (typeof path !== 'string') {
+            return;
+        }
+        const message = await readMessage(path);
+        if (message !== undefined) {
+            emit({ kind: 'added', message });
+        }
+    };
+    const wire = async () => {
+        const added = await transport.subscribeSignal({ interface: MESSAGING_IFACE, member: 'Added', path: modemPath }, (event) => {
+            void onAdded(event.body).catch((error) => options.onError?.(error));
+        });
+        const deleted = await transport.subscribeSignal({ interface: MESSAGING_IFACE, member: 'Deleted', path: modemPath }, (event) => {
+            const path = event.body[0];
+            if (typeof path === 'string') {
+                emit({ kind: 'deleted', id: path.slice(path.lastIndexOf('/') + 1) });
+            }
+        });
+        subscriptions.push(added, deleted);
+        transport.on('reconnected', reconnected);
+        // A subscription established AFTER the caller's own `list()` can have
+        // missed an arrival in between, so the wiring ends with one resync.
+        await resync();
+    };
+    const reconnected = () => {
+        void resync().catch((error) => options.onError?.(error));
+    };
+    return {
+        list: listInbox,
+        observe(listener) {
+            listeners.add(listener);
+            if (wiring === undefined && !stopped) {
+                wiring = wire().catch((error) => {
+                    options.onError?.(error);
+                });
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async stop() {
+            stopped = true;
+            listeners.clear();
+            transport.off('reconnected', reconnected);
+            await wiring?.catch(() => undefined);
+            wiring = undefined;
+            const held = subscriptions.splice(0, subscriptions.length);
+            await Promise.all(held.map((subscription) => subscription.unsubscribe()));
+        },
+    };
+}

package/dist/sms/inbox-store.d.ts

@@ -0,0 +1,10 @@
+import type { SmsInboxEvent, SmsMessage } from '../ports/sms.js';
+export interface SmsInboxStore {
+    /** Apply one event. Answers whether the visible inbox actually changed. */
+    apply(event: SmsInboxEvent): boolean;
+    /** The current inbox, newest-first and capped. */
+    snapshot(): SmsMessage[];
+    /** Number of retained rows, before the cap is applied. */
+    size(): number;
+}
+export declare function createSmsInboxStore(cap?: number): SmsInboxStore;

package/dist/sms/inbox-store.js

@@ -0,0 +1,82 @@
+// The inbox row store — folds `Added` / `Deleted` / resync events into one
+// newest-first, capped list.
+//
+// TWO PROPERTIES ARE THE WHOLE POINT OF THIS FILE, and both are failures a
+// signal-driven inbox produces on its own unless something stops them.
+//
+// DUPLICATE SUPPRESSION. ModemManager emits `Added` for a message it is
+// receiving AND again once it is stored, a re-subscribe after a bus hiccup can
+// replay one, and a consumer that also re-listed would hold the same message
+// twice. Rows are therefore keyed by object index and an `Added` carrying
+// nothing new is a NO-OP — `apply` answers `false` and no consumer is woken.
+//
+// RESTART RECOVERY. A source restart cannot be folded, because the events that
+// happened while it was down were never delivered. `resynced` therefore REPLACES
+// the whole row set rather than merging into it: merging would keep a message
+// deleted during the outage forever, and re-adding each row of a fresh list one
+// `added` at a time is exactly how a restart comes to duplicate the inbox it
+// already had.
+import { SMS_INBOX_CAP, sortAndCapSms } from './normalize.js';
+/** Two rows are the same message when every rendered field matches. */
+function sameMessage(a, b) {
+    return (a.id === b.id &&
+        a.text === b.text &&
+        a.state === b.state &&
+        a.from === b.from &&
+        a.timestamp === b.timestamp);
+}
+export function createSmsInboxStore(cap = SMS_INBOX_CAP) {
+    const rows = new Map();
+    const applyAdded = (message) => {
+        const held = rows.get(message.id);
+        // A repeated Added for a row we already hold VERBATIM is the duplicate
+        // this store exists to swallow. An Added that genuinely differs is a
+        // state transition (receiving -> received) and does update the row.
+        if (held !== undefined && sameMessage(held, message)) {
+            return false;
+        }
+        rows.set(message.id, message);
+        return true;
+    };
+    const applyResynced = (messages) => {
+        const next = new Map();
+        for (const message of messages) {
+            next.set(message.id, message);
+        }
+        // Report "unchanged" when the authoritative list matches what is already
+        // held, so a reconnect that found nothing new broadcasts nothing.
+        let changed = next.size !== rows.size;
+        if (!changed) {
+            for (const [id, message] of next) {
+                const held = rows.get(id);
+                if (held === undefined || !sameMessage(held, message)) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        rows.clear();
+        for (const [id, message] of next) {
+            rows.set(id, message);
+        }
+        return changed;
+    };
+    return {
+        apply(event) {
+            switch (event.kind) {
+                case 'added':
+                    return applyAdded(event.message);
+                case 'deleted':
+                    return rows.delete(event.id);
+                case 'resynced':
+                    return applyResynced(event.messages);
+            }
+        },
+        snapshot() {
+            return sortAndCapSms([...rows.values()], cap);
+        },
+        size() {
+            return rows.size;
+        },
+    };
+}

package/dist/sms/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dbus-messaging.js';
+export * from './inbox-store.js';
+export * from './mmcli-parse.js';
+export * from './normalize.js';

package/dist/sms/index.js

@@ -0,0 +1,10 @@
+// The read-only SMS surface: normalization, the `mmcli -K` grammar, the
+// Added/Deleted fold, and the ModemManager Messaging adapter.
+//
+// LIST / READ and observation ONLY. Nothing exported here composes, stores,
+// sends, or deletes a message; `readonly-gate.test.ts` fails the build if that
+// ever stops being true.
+export * from './dbus-messaging.js';
+export * from './inbox-store.js';
+export * from './mmcli-parse.js';
+export * from './normalize.js';

package/dist/sms/mmcli-parse.d.ts

@@ -0,0 +1,54 @@
+import type { SmsMessage, SmsReadRefusal } from '../ports/sms.js';
+/** A parse outcome. `detail` NEVER carries message content — key names only. */
+export type SmsParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly detail: string;
+};
+/**
+ * Undo `g_strescape()` on one `-K` value.
+ *
+ * mmcli does not print non-ASCII text — it prints the LITERAL ASCII characters
+ * of the octal escape. A Spanish message arrives on stdout as the eight
+ * characters `\`,`3`,`0`,`2`,`\`,`2`,`4`,`1` where the wire carried the two
+ * UTF-8 bytes `0xC2 0xA1` (confirmed on the bench board with `od -c`). The
+ * escapes are therefore per-BYTE, not per-character, and the only correct
+ * decode is to rebuild the byte sequence and read it back as UTF-8 — decoding
+ * each escape with `String.fromCharCode` instead turns `¡` into `¡`.
+ *
+ * Total and silent: it never throws and never logs, because the value it holds
+ * is message content. An escape outside the grammar is copied VERBATIM rather
+ * than dropped — mmcli cannot emit one, so meeting one means the value was
+ * never escaped and copying it is the only lossless answer.
+ */
+export declare function unescapeMmcliValue(value: string): string;
+/**
+ * Extract SMS object paths from `mmcli -K -m <id> --messaging-list-sms`.
+ *
+ * An inbox with no messages prints as `modem.messaging.sms: --`, whose `--`
+ * carries no entry — so an ABSENT key is a legitimate EMPTY INBOX, exactly as it
+ * is for `--3gpp-scan`, not drift. What IS drift, and what fails loud here, is
+ * output that never mentions the key at all (a renamed field, an error body
+ * reaching this parser): answering "no messages" to a read that never ran would
+ * be the worst possible lie about an inbox.
+ */
+export declare function parseSmsListOutput(raw: string): SmsParseResult<string[]>;
+/**
+ * Parse one `mmcli -K -s <path>` record.
+ *
+ * A malformed record reports the KEY NAMES it found and nothing else — see the
+ * content-free note at the top of this file.
+ */
+export declare function parseSmsRecordOutput(raw: string): SmsParseResult<SmsMessage>;
+/**
+ * Classify a source failure into a refusal the operator can act on.
+ *
+ * The three recognised strings are ModemManager 1.24's own, confirmed on the
+ * bench board: a modem with no Messaging interface, a radio that has not come up
+ * yet, and a selector nothing answers to. Anything else stays `read_failed`
+ * rather than being guessed at.
+ */
+export declare function classifySmsFailure(description: string): SmsReadRefusal;