signalk-container-helper 0.12.0 → 0.13.0

package/README.md

@@ -154,12 +154,14 @@ rewrites `app.getDataDirPath()` per plugin, and signalk-container resolves that
 field from _its own_ app object — so you get
 `<configRoot>/plugin-config-data/signalk-container/`, not yours.
 
-| You want                                    | Use                                              |
-| ------------------------------------------- | ------------------------------------------------ |
-| A private writable area in the SK data tree | `signalkDataMount` (signalk-container's)         |
-| The whole SK config root                    | `signalkConfigRootMount` (incl. `security.json`) |
-| **Your own plugin's data dir**              | **`resolveMount()`** + a `volumes` entry         |
-| **Is there a GPU / device on the host?**    | **`probeHostDevice()`**                          |
+| You want                                      | Use                                              |
+| --------------------------------------------- | ------------------------------------------------ |
+| A private writable area in the SK data tree   | `signalkDataMount` (signalk-container's)         |
+| The whole SK config root                      | `signalkConfigRootMount` (incl. `security.json`) |
+| **Your own plugin's data dir**                | **`resolveMount()`** + a `volumes` entry         |
+| **Is there a GPU / device on the host?**      | **`probeHostDevice()`**                          |
+| **Which USB serial devices are plugged in?**  | **`listHostSerialDevices()`**                    |
+| **Act when a USB device is pulled/replugged** | **`watchHostDevice()`**                          |
 
 Either mount field resolves to a host path or a named volume, depending on the
 deployment. A named volume always arrives whole: signalk-container sends no
@@ -192,6 +194,58 @@ report it as absent. Throws `ContainerHelperError('unsupported-manager')` on
 signalk-container older than 1.30.0, so catch it if you would rather degrade
 than fail. Works on both Docker and rootless podman.
 
+### USB devices that come and go
+
+A container gets its device nodes when it is created. Pull a USB stick while
+it runs and the program inside usually exits, and `unless-stopped` restarts it
+against a node that is gone; plug it back in and it may come up as another
+node (`ttyUSB1` for `ttyUSB0`) that the old container never sees.
+
+`listHostSerialDevices(manager)` lists the host's `/dev/serial/by-id` links as
+full, sorted paths. Their names carry vendor, product and serial number, so a
+plugin can recognise its hardware without asking the user for a path, and the
+link is the path to pass to the container: it survives a replug that changes
+the `ttyUSB` number. `[]` means nothing is plugged in, `null` that the host
+could not be asked. A containerized Signal K needs signalk-container 1.37.2 or
+later to list the links.
+
+`watchHostDevice(options)` follows one device and tells the plugin when to act;
+what acting means stays with the plugin:
+
+```ts
+import { watchHostDevice } from "signalk-container-helper";
+
+const watch = watchHostDevice({
+  manager,
+  path: "/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_…",
+  isStarted: () => started,
+  isHealthy: () => bridge.online, // undefined when you cannot tell
+  onEvent: async (event) => {
+    if (event === "unplugged") await manager.stop(name);
+    else await container.applyUpdate(tag); // pluggedIn or stuck: recreate
+  },
+});
+// in plugin.stop():
+await watch.stop();
+```
+
+| Event       | When                                                                                      |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `unplugged` | The device went away under a started container. Once per unplug.                          |
+| `pluggedIn` | The device is back after an unplug, or appeared while nothing was started.                |
+| `stuck`     | The device is there and the workload stayed unhealthy for `stuckMs`. Repeats until fixed. |
+
+The host is probed only while the container is not started or not healthy,
+so a working setup costs nothing (a probe is a short-lived container under a
+containerized Signal K). A probe that cannot tell changes nothing, and with
+health unknown no `stuck` is raised. Ticks run every `intervalMs` (default
+30 s, the first one interval after the call), handlers never overlap, a
+throwing handler is logged through `debug`, and `stop()` waits for a tick in
+progress (from inside `onEvent` it returns at once). Pass
+`initiallyAbsent: true` when the device was missing at start, so its arrival
+is reported as `pluggedIn`. `decideDeviceEvent` is the pure decision behind
+it, exported for plugins that run their own timer.
+
 `resolveMount` translates any absolute host path into a mount the container
 runtime can actually bind, on bare-metal and containerized Signal K alike:
 
@@ -783,6 +837,9 @@ Adopt these even where you don't use the components:
 | `managedModeSchema(opts)`                               | The two config fields as plain JSON Schema + matching defaults (`signalk-container-helper/schema`)                                                                                                                                                                                       |
 | `waitForHttpReady(url, opts)`                           | Poll until 2xx or deadline (throws)                                                                                                                                                                                                                                                      |
 | `retryForever(fn, opts)`                                | Retry until success — 15s doubling to a 120s ceiling, no attempt cap. `ManagedContainer` takes it as `readinessRetry`; exported standalone for work this library does not manage                                                                                                         |
+| `probeHostDevice(manager, path)`                        | Whether the host has a device, with its node names and groups; `null` when unknown                                                                                                                                                                                                       |
+| `listHostSerialDevices(manager)`                        | The host's `/dev/serial/by-id` links as full paths; `[]` when none, `null` when unknown                                                                                                                                                                                                  |
+| `watchHostDevice(opts)`                                 | Poll a host device while its container is unhealthy or not started; reports `unplugged`, `pluggedIn`, `stuck` (see [USB devices that come and go](#usb-devices-that-come-and-go))                                                                                                        |
 | `anySignal(signals)`                                    | Compose several `AbortSignal`s into one that aborts when any does (`undefined` when none are given)                                                                                                                                                                                      |
 | `probeHttpHealth(url, opts)`                            | Retrying liveness probe with slow-response detection (never throws)                                                                                                                                                                                                                      |
 | `fetchWithTimeout(url, opts)`                           | `fetch` with an `AbortController` timeout                                                                                                                                                                                                                                                |

package/dist/device-watch.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Following a host device that can be unplugged while its container runs.
+ *
+ * A container gets its device nodes when it is created. When the device is
+ * pulled, the program inside usually exits, and `unless-stopped` restarts it
+ * against a node that is gone, over and over. When the device comes back it
+ * may get another node (ttyUSB1 for ttyUSB0), which the old container never
+ * sees. Nothing in the runtime notices either event, so the plugin has to.
+ *
+ * `watchHostDevice` polls the host through {@link probeHostDevice} and tells
+ * the plugin when to stop its container, when to (re)create it, and when a
+ * container that has its device has stayed unhealthy too long. What "stop" and
+ * "recreate" mean stays with the plugin.
+ */
+import type { ContainerManagerApi } from "./types.js";
+/** Default poll interval. signalk-container caches a probe for 60 s. */
+export declare const DEVICE_WATCH_INTERVAL_MS = 30000;
+/** Default time a container may stay unhealthy with its device present. */
+export declare const DEVICE_STUCK_MS = 180000;
+export interface DeviceWatchState {
+    /** The device was missing on the last tick that could tell. */
+    absent: boolean;
+    /** When the container was first seen unhealthy with its device present. */
+    unhealthySince?: number;
+}
+export interface DeviceObservation {
+    /** The host probe: undefined when it could not tell. */
+    present: boolean | undefined;
+    /** The plugin has created the container. */
+    started: boolean;
+    /** The workload's health; undefined when the plugin cannot tell. */
+    healthy: boolean | undefined;
+    now: number;
+    stuckMs: number;
+}
+/**
+ * - `unplugged`: the device went away under a started container.
+ * - `pluggedIn`: the device is back (or appeared for the first time).
+ * - `stuck`: the device is there, the container is not healthy.
+ */
+export type DeviceWatchEvent = "unplugged" | "pluggedIn" | "stuck";
+/** Whether a tick needs to ask the host at all. */
+export declare function deviceProbeNeeded(started: boolean, healthy: boolean | undefined): boolean;
+/** The decision of one tick, and the state for the next one. */
+export declare function decideDeviceEvent(state: DeviceWatchState, obs: DeviceObservation): {
+    event: DeviceWatchEvent | undefined;
+    next: DeviceWatchState;
+};
+export interface WatchHostDeviceOptions {
+    manager: ContainerManagerApi;
+    /** Host path of the device, ideally a `/dev/serial/by-id/…` link. */
+    path: string;
+    /** Whether the plugin has created the container for this device. */
+    isStarted: () => boolean;
+    /**
+     * Whether the workload works. Return undefined when the plugin cannot tell
+     * (its own connection to the workload is down): no `stuck` is raised then.
+     */
+    isHealthy: () => boolean | undefined;
+    /**
+     * Called for each event, never while the previous call runs and never after
+     * `stop()`. `unplugged` and `pluggedIn` fire once per transition; `stuck`
+     * repeats every `stuckMs` while the workload stays unhealthy. A rejection is
+     * logged through `debug` and the watch moves on: a recreate that failed shows
+     * up again as `stuck`.
+     */
+    onEvent: (event: DeviceWatchEvent) => Promise<void> | void;
+    /** The device was missing when the plugin last looked. Default false. */
+    initiallyAbsent?: boolean;
+    intervalMs?: number;
+    stuckMs?: number;
+    debug?: (msg: string) => void;
+}
+export interface HostDeviceWatch {
+    /**
+     * Stops polling and waits for a tick in progress. Called from inside
+     * `onEvent` it returns at once instead of waiting for itself.
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Poll the host for `path` and report its transitions.
+ *
+ * ```ts
+ * const watch = watchHostDevice({
+ *   manager,
+ *   path: "/dev/serial/by-id/usb-…",
+ *   isStarted: () => started,
+ *   isHealthy: () => bridge.online,
+ *   onEvent: async (event) => {
+ *     if (event === "unplugged") await manager.stop(name);
+ *     else await container.applyUpdate(tag); // recreate with the new node
+ *   },
+ * });
+ * // plugin.stop():
+ * await watch.stop();
+ * ```
+ *
+ * A healthy started container is never probed, so the cost of a probe (a
+ * short-lived container under a containerized Signal K) is paid only while
+ * something is wrong. A probe that cannot tell (`null`, or an older
+ * signalk-container) changes nothing. The first tick runs one interval after
+ * the call. `stuck` repeats every `stuckMs` (plus up to one interval) for as
+ * long as the workload stays unhealthy with its device present.
+ */
+export declare function watchHostDevice(options: WatchHostDeviceOptions): HostDeviceWatch;
+//# sourceMappingURL=device-watch.d.ts.map

package/dist/device-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-watch.d.ts","sourceRoot":"","sources":["../src/device-watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,wEAAwE;AACxE,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,2EAA2E;AAC3E,eAAO,MAAM,eAAe,SAAU,CAAC;AAEvC,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;AAEnE,mDAAmD;AACnD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAET;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,iBAAiB,GACrB;IAAE,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAuBjE;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB;;;OAGG;IACH,SAAS,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACrC;;;;;;OAMG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3D,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CA0DjB"}

package/dist/device-watch.js

@@ -0,0 +1,139 @@
+/**
+ * Following a host device that can be unplugged while its container runs.
+ *
+ * A container gets its device nodes when it is created. When the device is
+ * pulled, the program inside usually exits, and `unless-stopped` restarts it
+ * against a node that is gone, over and over. When the device comes back it
+ * may get another node (ttyUSB1 for ttyUSB0), which the old container never
+ * sees. Nothing in the runtime notices either event, so the plugin has to.
+ *
+ * `watchHostDevice` polls the host through {@link probeHostDevice} and tells
+ * the plugin when to stop its container, when to (re)create it, and when a
+ * container that has its device has stayed unhealthy too long. What "stop" and
+ * "recreate" mean stays with the plugin.
+ */
+import { probeHostDevice } from "./host-device.js";
+import { errMsg } from "./util.js";
+/** Default poll interval. signalk-container caches a probe for 60 s. */
+export const DEVICE_WATCH_INTERVAL_MS = 30_000;
+/** Default time a container may stay unhealthy with its device present. */
+export const DEVICE_STUCK_MS = 180_000;
+/** Whether a tick needs to ask the host at all. */
+export function deviceProbeNeeded(started, healthy) {
+    return !started || healthy !== true;
+}
+/** The decision of one tick, and the state for the next one. */
+export function decideDeviceEvent(state, obs) {
+    if (obs.started && obs.healthy === true) {
+        return { event: undefined, next: { absent: false } };
+    }
+    if (obs.present === undefined)
+        return { event: undefined, next: state };
+    if (!obs.present) {
+        return {
+            event: obs.started && !state.absent ? "unplugged" : undefined,
+            next: { absent: true },
+        };
+    }
+    if (state.absent || !obs.started) {
+        return {
+            event: state.absent ? "pluggedIn" : undefined,
+            next: { absent: false },
+        };
+    }
+    if (obs.healthy === undefined)
+        return { event: undefined, next: state };
+    const unhealthySince = state.unhealthySince ?? obs.now;
+    if (obs.now - unhealthySince >= obs.stuckMs) {
+        return { event: "stuck", next: { absent: false } };
+    }
+    return { event: undefined, next: { absent: false, unhealthySince } };
+}
+/**
+ * Poll the host for `path` and report its transitions.
+ *
+ * ```ts
+ * const watch = watchHostDevice({
+ *   manager,
+ *   path: "/dev/serial/by-id/usb-…",
+ *   isStarted: () => started,
+ *   isHealthy: () => bridge.online,
+ *   onEvent: async (event) => {
+ *     if (event === "unplugged") await manager.stop(name);
+ *     else await container.applyUpdate(tag); // recreate with the new node
+ *   },
+ * });
+ * // plugin.stop():
+ * await watch.stop();
+ * ```
+ *
+ * A healthy started container is never probed, so the cost of a probe (a
+ * short-lived container under a containerized Signal K) is paid only while
+ * something is wrong. A probe that cannot tell (`null`, or an older
+ * signalk-container) changes nothing. The first tick runs one interval after
+ * the call. `stuck` repeats every `stuckMs` (plus up to one interval) for as
+ * long as the workload stays unhealthy with its device present.
+ */
+export function watchHostDevice(options) {
+    const debug = options.debug ?? (() => undefined);
+    const stuckMs = options.stuckMs ?? DEVICE_STUCK_MS;
+    let state = { absent: options.initiallyAbsent ?? false };
+    let stopped = false;
+    let tick;
+    let inHandler = false;
+    const once = async () => {
+        const started = options.isStarted();
+        const healthy = options.isHealthy();
+        let present;
+        if (deviceProbeNeeded(started, healthy)) {
+            try {
+                present = (await probeHostDevice(options.manager, options.path))
+                    ?.exists;
+            }
+            catch (err) {
+                debug(`watchHostDevice: probing ${options.path}: ${errMsg(err)}`);
+            }
+            if (stopped)
+                return;
+        }
+        const { event, next } = decideDeviceEvent(state, {
+            present,
+            started,
+            healthy,
+            now: Date.now(),
+            stuckMs,
+        });
+        state = next;
+        if (event === undefined)
+            return;
+        debug(`watchHostDevice: ${options.path} ${event}`);
+        inHandler = true;
+        try {
+            await options.onEvent(event);
+        }
+        finally {
+            inHandler = false;
+        }
+    };
+    const timer = setInterval(() => {
+        if (stopped || tick !== undefined)
+            return;
+        tick = once()
+            .catch((err) => {
+            debug(`watchHostDevice: ${options.path}: ${errMsg(err)}`);
+        })
+            .finally(() => {
+            tick = undefined;
+        });
+    }, options.intervalMs ?? DEVICE_WATCH_INTERVAL_MS);
+    return {
+        async stop() {
+            stopped = true;
+            clearInterval(timer);
+            // Awaiting the tick from inside its own handler would never resolve.
+            if (!inHandler)
+                await tick;
+        },
+    };
+}
+//# sourceMappingURL=device-watch.js.map

package/dist/device-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-watch.js","sourceRoot":"","sources":["../src/device-watch.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -9,6 +9,9 @@ export { buildVersionSource } from "./version-source.js";
 export type { VersionSourceSpec } from "./version-source.js";
 export { resolveMount } from "./host-path.js";
 export { probeHostDevice } from "./host-device.js";
+export { listHostSerialDevices, SERIAL_BY_ID_DIR } from "./serial-devices.js";
+export { watchHostDevice, decideDeviceEvent, deviceProbeNeeded, DEVICE_WATCH_INTERVAL_MS, DEVICE_STUCK_MS, } from "./device-watch.js";
+export type { DeviceWatchEvent, DeviceWatchState, DeviceObservation, WatchHostDeviceOptions, HostDeviceWatch, } from "./device-watch.js";
 export type { HostMount, ResolveMountOptions } from "./host-path.js";
 export { retryForever, anySignal } from "./retry.js";
 export type { RetryForeverOptions } from "./retry.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5E,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5E,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -5,6 +5,8 @@ export { AdoptedContainer } from "./adopted-container.js";
 export { buildVersionSource } from "./version-source.js";
 export { resolveMount } from "./host-path.js";
 export { probeHostDevice } from "./host-device.js";
+export { listHostSerialDevices, SERIAL_BY_ID_DIR } from "./serial-devices.js";
+export { watchHostDevice, decideDeviceEvent, deviceProbeNeeded, DEVICE_WATCH_INTERVAL_MS, DEVICE_STUCK_MS, } from "./device-watch.js";
 export { retryForever, anySignal } from "./retry.js";
 export { fetchWithTimeout, waitForHttpReady, probeHttpHealth } from "./http.js";
 export { resolveEndpoint, waitForEndpointReady, isManagedMode, describeEndpoint, } from "./endpoint.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAY1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAchD,OAAO,EACL,WAAW,EACX,cAAc,EACd,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAY1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAchD,OAAO,EACL,WAAW,EACX,cAAc,EACd,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}

package/dist/serial-devices.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Finding USB serial devices on the host by name.
+ *
+ * udev gives every USB serial device a link in `/dev/serial/by-id` named after
+ * its vendor, product and serial number
+ * (`usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_…-if00-port0`), and removes it
+ * when the device is unplugged. That name is what lets a plugin recognise its
+ * hardware without asking the user for a path, and the link is the path to
+ * hand to the container: it survives a replug that changes the ttyUSB number.
+ */
+import type { ContainerManagerApi } from "./types.js";
+export declare const SERIAL_BY_ID_DIR = "/dev/serial/by-id";
+/**
+ * The `/dev/serial/by-id` links on the host, as full paths, sorted.
+ *
+ * Returns `[]` when no USB serial device is plugged in, and **null when the
+ * host could not be asked** — see {@link probeHostDevice}. With nothing
+ * plugged in udev removes the directory itself, which a containerized Signal K
+ * cannot mount, so there null usually means "none". A containerized Signal K
+ * needs signalk-container 1.37.2 or later; older ones list nothing.
+ *
+ * @throws ContainerHelperError `unsupported-manager` on signalk-container
+ * older than 1.30.0.
+ */
+export declare function listHostSerialDevices(manager: ContainerManagerApi): Promise<string[] | null>;
+//# sourceMappingURL=serial-devices.d.ts.map

package/dist/serial-devices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-devices.d.ts","sourceRoot":"","sources":["../src/serial-devices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAK1B"}

package/dist/serial-devices.js

@@ -0,0 +1,33 @@
+/**
+ * Finding USB serial devices on the host by name.
+ *
+ * udev gives every USB serial device a link in `/dev/serial/by-id` named after
+ * its vendor, product and serial number
+ * (`usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_…-if00-port0`), and removes it
+ * when the device is unplugged. That name is what lets a plugin recognise its
+ * hardware without asking the user for a path, and the link is the path to
+ * hand to the container: it survives a replug that changes the ttyUSB number.
+ */
+import { probeHostDevice } from "./host-device.js";
+export const SERIAL_BY_ID_DIR = "/dev/serial/by-id";
+/**
+ * The `/dev/serial/by-id` links on the host, as full paths, sorted.
+ *
+ * Returns `[]` when no USB serial device is plugged in, and **null when the
+ * host could not be asked** — see {@link probeHostDevice}. With nothing
+ * plugged in udev removes the directory itself, which a containerized Signal K
+ * cannot mount, so there null usually means "none". A containerized Signal K
+ * needs signalk-container 1.37.2 or later; older ones list nothing.
+ *
+ * @throws ContainerHelperError `unsupported-manager` on signalk-container
+ * older than 1.30.0.
+ */
+export async function listHostSerialDevices(manager) {
+    const probe = await probeHostDevice(manager, SERIAL_BY_ID_DIR);
+    if (probe === null)
+        return null;
+    if (!probe.exists)
+        return [];
+    return probe.nodes.map((name) => `${SERIAL_BY_ID_DIR}/${name}`).sort();
+}
+//# sourceMappingURL=serial-devices.js.map

package/dist/serial-devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial-devices.js","sourceRoot":"","sources":["../src/serial-devices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAA4B;IAE5B,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC/D,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAC7B,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,gBAAgB,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACzE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-container-helper",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Helper library for Signal K plugins that manage containers via the signalk-container plugin",
   "type": "module",
   "main": "dist/index.js",
@@ -36,8 +36,7 @@
     "lint": "eslint --fix",
     "format": "npm run prettier && npm run lint",
     "ci-lint": "eslint && prettier --check .",
-    "prepublishOnly": "npm run build && npm test",
-    "release": "git tag -d v$npm_package_version; git tag v$npm_package_version && git push && git push origin v$npm_package_version"
+    "prepublishOnly": "npm run build && npm test"
   },
   "repository": {
     "type": "git",