signalk-container-helper 0.1.0

package/SPEC.md

@@ -0,0 +1,309 @@
+# signalk-container-helper — Specification
+
+An abstraction library (npm module) for Signal K plugin developers whose plugins run
+containers through the [signalk-container](https://github.com/dirkwa/signalk-container)
+plugin. It packages the container-integration patterns that every consumer plugin
+currently hand-copies — discovery, startup, readiness, updates, teardown — into a small,
+typed, zero-dependency API.
+
+## 1. Background: what the reference plugins actually do
+
+Four plugins were analyzed: `mayara-server-signalk-plugin`, `signalk-backup`,
+`signalk-doctor`, `signalk-updater`, plus the signalk-container source itself (v1.22.0).
+
+They fall into **two archetypes**:
+
+|                     | Managed (backup, mayara)                                  | Adopt-only (doctor, updater)                             |
+| ------------------- | --------------------------------------------------------- | -------------------------------------------------------- |
+| Container lifecycle | Owned by the plugin via `ensureRunning`/`recreate`/`stop` | Owned externally (systemd Quadlet); plugin never mutates |
+| Update service      | `register` + `checkOne` + apply route                     | `register`/`unregister` only                             |
+| Health              | HTTP-poll the containerized app                           | HTTP-probe with retry + slow detection                   |
+| Manager wait budget | 30–120 s                                                  | 30 s                                                     |
+
+Every plugin independently re-implements the same building blocks (all four have
+near-identical copies):
+
+1. **Manager discovery** — poll `globalThis.__signalk_containerManager` every 500 ms
+   until it exists AND `getRuntime()` is non-null (plugins load alphabetically, and
+   runtime probing is async). mayara adds a second phase using `whenReady()` (1.6.0+).
+2. **Hand-rolled type mirror** — each plugin maintains its own `src/types.ts` copy of
+   signalk-container's API (synced against different versions: 1.6.0, 1.10.2), because
+   importing signalk-container at compile time is forbidden (runtime-only coupling) and
+   npm `peerDependencies` break against its prereleases.
+3. **`buildContainerConfig(tag)`** — a function producing a declarative `ContainerConfig`
+   (split `image` + `tag`, resources defaults, restart `unless-stopped`), passed to
+   `ensureRunning` on every start; drift detection recreates as needed.
+4. **Tag validation** — `SAFE_TAG = /^[a-zA-Z0-9._-]+$/` before anything reaches the
+   runtime, plus optional `'auto'` → pinned-version resolution (backup).
+5. **Self-heal on startup** — compare the live container's image against the desired
+   `image:tag` via `listContainers()` (matching `sk-<name>`), and `recreate` when they
+   differ. Feature-detected (`recreate` is 1.12.0+).
+6. **Update apply** — `recreate(name, config)` with a legacy fallback of
+   `pullImage` → `remove` → `ensureRunning`, including the "removed but recreation
+   failed" limbo error message. Requested tag persisted via `savePluginOptions`
+   (persisting `'auto'`, not the resolved version).
+7. **Update registration** — `updates.register({pluginId, containerName, image,
+currentTag: () => …, versionSource: sources.githubReleases(repo), currentVersion?,
+checkInterval?})` at start; `unregister` at stop; both wrapped non-fatally.
+8. **Address resolution** — `resolveContainerAddress(name, port)` with a documented
+   production bug workaround: fall back to parsing `listContainers()[].ports` for a
+   `"host:port->port/tcp"` entry, because the resolver can return a stale port.
+9. **HTTP readiness** — poll the containerized app's own `/api/health` (deadline +
+   interval + per-request `AbortController` timeout). "Container running" ≠ "app ready".
+10. **HTTP health probe** — N attempts, per-attempt timeout, inter-attempt delay, and a
+    "reachable but slow" threshold (no SignalK warning tier, so slow → green status text).
+11. **Teardown** — `updates.unregister` then `containers.stop` (stop, never remove — the
+    container restarts instantly on re-enable), everything swallowed.
+12. **Never throw out of `start()`** — sync `start()` + `asyncStart().catch(err =>
+setPluginError(...))`, because the server does not await plugin `start()`.
+13. **Schema defaults merge** — `{...SCHEMA_DEFAULTS, ...rawConfig}` because Signal K
+    does not seed schema defaults at runtime.
+
+## 2. Goals
+
+- One import that provides the **managed-container lifecycle** end-to-end:
+  wait-for-manager → validate tag → self-heal → `ensureRunning` → register updates →
+  resolve address → wait-for-ready.
+- First-class support for the **adopt-only** archetype (update registration + HTTP
+  health probing without lifecycle mutation).
+- Ship the **canonical TypeScript mirror** of signalk-container's public API so plugins
+  stop hand-maintaining divergent copies. Runtime coupling stays via `globalThis` —
+  the library never imports signalk-container.
+- **Feature-detect** optional/newer manager methods (`recreate`, `resolveHostPath`,
+  `getLogs`, …) and provide legacy fallbacks, with version floors documented.
+- **Marine-grade error handling**: helpers never throw for expected conditions without
+  an actionable message; non-fatal operations are swallowed with `app.debug`; offline
+  is a normal state.
+- Zero runtime dependencies. ESM output + `.d.ts`. Node ≥ 24.
+
+## 3. Non-goals
+
+- Talking to Docker/Podman directly — everything goes through signalk-container.
+- Owning the plugin's config schema, webapp, or final status message.
+- Applying updates automatically (detection-only service stays user-confirmed;
+  `autoUpdateOnFloatingTag` remains a per-config opt-in the caller sets).
+- Wrapping `runJob`/one-shot jobs beyond re-exporting the types (no consumer among the
+  four uses them; can be added later).
+
+## 4. Public API
+
+```ts
+import {
+  // discovery
+  getContainerManager,
+  waitForContainerManager,
+  // archetypes
+  ManagedContainer,
+  AdoptedContainer,
+  // http utilities
+  fetchWithTimeout,
+  waitForHttpReady,
+  probeHttpHealth,
+  // misc utilities
+  startSafely,
+  errMsg,
+  isValidImageTag,
+  IMAGE_TAG_PATTERN,
+  ContainerHelperError,
+  // full type mirror
+  type ContainerManagerApi,
+  type ContainerConfig /* … */,
+} from "signalk-container-helper";
+```
+
+### 4.1 Discovery
+
+```ts
+getContainerManager(): ContainerManagerApi | undefined
+
+waitForContainerManager(options?: {
+  timeoutMs?: number       // default 60_000
+  intervalMs?: number      // default 500
+  onWaiting?: (phase: 'manager' | 'runtime') => void
+}): Promise<{ manager: ContainerManagerApi | undefined; runtime: ContainerRuntimeInfo | null }>
+```
+
+Two-phase wait: poll the global until present, then `whenReady()` (feature-detected,
+falling back to polling `getRuntime()`), then re-check `getRuntime()`. The result
+distinguishes the two failure modes every plugin reports differently:
+`manager === undefined` → "signalk-container is not installed/enabled";
+`manager && !runtime` → "no container runtime detected (podman/docker missing)".
+
+### 4.2 `ManagedContainer` (backup/mayara archetype)
+
+```ts
+const container = new ManagedContainer({
+  app,                                  // setPluginStatus/setPluginError/debug
+  pluginId: 'signalk-questdb',
+  name: 'questdb',                      // unprefixed container name
+  image: 'ghcr.io/questdb/questdb',     // registry path, no tag
+  buildConfig: (tag) => ({ image: 'ghcr.io/questdb/questdb', tag, /* … */ }),
+  defaultTag: 'latest',
+  resolveTag: (t) => t === 'auto' ? PINNED_VERSION : t,   // optional
+  managerTimeoutMs: 120_000,
+  readiness: { port: 9000, path: '/ping', maxMs: 60_000 },   // optional
+  updates: {                                                  // optional
+    versionSource: { githubReleases: 'questdb/questdb' },
+    currentTag: () => currentSettings?.version ?? 'auto',
+  },
+  ensureOptions: { onVolumeIssue, onContainerLog },           // passed through
+})
+
+await container.start(tag?)        // full bring-up; returns { manager, tag, address }
+await container.stop()             // unregister + stop (not remove); never throws
+await container.applyUpdate(tag)   // recreate, or legacy pull+remove+ensureRunning
+await container.checkForUpdate()   // updates.checkOne → UpdateCheckResult | null
+await container.getState()         // ContainerState ('unknown-manager' safe default)
+await container.getInfo()          // { state, image } for /status routes
+await container.resolveAddress(p)  // resolveContainerAddress + stale-port fallback
+await container.getLogs(opts?)     // feature-detected passthrough
+container.registerUpdateRoutes(router, { onApplied })  // GET check / POST apply
+```
+
+`start()` sequencing (each step from the reference plugins):
+
+1. `waitForContainerManager` — on failure sets an actionable `setPluginError` and throws
+   `ContainerHelperError` with `code: 'manager-unavailable' | 'no-runtime'` and
+   `reported: true` (so `startSafely` doesn't double-report).
+2. Validate requested tag (`IMAGE_TAG_PATTERN`), apply `resolveTag`.
+3. Self-heal: when `manager.recreate` exists, compare the live container's image
+   (matched by `unprefixedName`, falling back to `sk-<name>`) to `image:tag`; `recreate`
+   on mismatch. Probe failures are non-fatal (debug + fall through).
+4. Otherwise `ensureRunning(name, buildConfig(tag), ensureOptions)`.
+5. Register with the update service (non-fatal; `currentTag` defaults to a live getter
+   of the last started tag).
+6. If `readiness` is configured: resolve the address (throws `'address-unresolved'`
+   if impossible) and poll `http://<addr><path>` until ready (throws `'not-ready'` on
+   deadline).
+
+The helper emits progress via `setPluginStatus` ("Waiting for…", "Starting…",
+"Recreating…") but **never sets the final "Running" status** — the plugin owns that.
+
+### 4.3 `AdoptedContainer` (doctor/updater archetype)
+
+```ts
+const adopted = new AdoptedContainer({
+  app,
+  pluginId: "signalk-doctor",
+  containerName: "signalk-doctor-server",
+  image: "ghcr.io/dirkwa/signalk-doctor-server",
+  currentTag: "latest", // string or () => string
+  currentVersion: () => fetchEngineVersion(), // optional, preferred by comparator
+  versionSource: { githubReleases: "dirkwa/signalk-doctor-server" },
+  checkInterval: "24h",
+  managerTimeoutMs: 30_000,
+});
+
+await adopted.register(); // waits for manager; false + setPluginError if unavailable
+adopted.unregister(); // best-effort, never throws
+await adopted.checkForUpdate();
+```
+
+No lifecycle mutation, matching the "adopt, don't manage" rule.
+
+### 4.4 HTTP utilities
+
+```ts
+fetchWithTimeout(url, { timeoutMs = 10_000, fetchImpl = fetch, ...init });
+waitForHttpReady(url, {
+  maxMs = 60_000,
+  intervalMs = 1_000,
+  requestTimeoutMs = 2_000,
+});
+probeHttpHealth(url, {
+  attempts = 3,
+  attemptTimeoutMs = 5_000,
+  retryDelayMs = 2_000,
+  slowMs = 1_500,
+});
+// → { reachable: boolean, slowMs?: number } — never throws
+```
+
+Defaults are the constants shared across the four plugins. `fetchImpl` is injectable
+for tests.
+
+### 4.5 Misc
+
+```ts
+startSafely(app, () => asyncStart(config));
+// sync wrapper for plugin.start(): catches, reports via setPluginError unless the
+// error is a ContainerHelperError already reported by the helper
+
+errMsg(err); // unknown → string
+isValidImageTag(tag); // SAFE_TAG check
+class ContainerHelperError extends Error {
+  code:
+    | "manager-unavailable"
+    | "no-runtime"
+    | "invalid-tag"
+    | "address-unresolved"
+    | "not-ready"
+    | "recreate-limbo";
+  reported: boolean; // true when the helper already called setPluginError
+}
+```
+
+### 4.6 Types module
+
+A documented mirror of signalk-container's public surface, synced against **v1.22.0**:
+`ContainerManagerApi`, `ContainerConfig` (incl. `signalkDataMount`,
+`signalkConfigRootMount`, `signalkAccessiblePorts`, `healthcheck`, `ulimits`, `labels`,
+`digest`, `updateChannel`, `autoUpdateOnFloatingTag`, `user`, `extraHosts`),
+`EnsureRunningOptions`, `VolumeSpec`/`VolumeIssue`, `ContainerResourceLimits`,
+`ContainerInfo`, `ContainerJobConfig`/`Result`, `UpdateServiceApi` and friends, and the
+`globalThis` declaration. Methods newer than the **1.6.0 baseline** are optional in the
+type, forcing feature-detection at call sites:
+
+| Optional member                         | Version floor                               |
+| --------------------------------------- | ------------------------------------------- |
+| `getLogs`                               | 1.7.0                                       |
+| `resolveHostPath`                       | 1.7.0 (partial earlier)                     |
+| `doctor.*`                              | 1.8.0–1.10.0                                |
+| `recreate`                              | 1.12.0                                      |
+| `execInContainer`, network methods      | varies                                      |
+| `removeManagedData`                     | 1.18.0                                      |
+| `manifest.*`                            | 1.13.0+                                     |
+| Config fields `healthcheck` / `ulimits` | 1.14.0 / 1.17.0 (ignored by older versions) |
+
+## 5. Error-handling philosophy
+
+- `stop()`, `unregister()`, `getInfo()`, `checkForUpdate()` never throw — degraded
+  results (`null`, `'unknown'`) plus `app.debug`.
+- `start()` / `applyUpdate()` throw typed `ContainerHelperError`s with actionable
+  messages; the helper sets `setPluginError` first and marks the error `reported`.
+- The legacy update path preserves the "Container removed but recreation failed —
+  retry" limbo message (`code: 'recreate-limbo'`).
+- Offline is normal: nothing in the helper converts a network failure into a fatal.
+
+## 6. Packaging & compatibility
+
+- npm module `signalk-container-helper`, Apache-2.0, zero runtime dependencies.
+- TypeScript → **ESM** (`dist/`) + declarations; `engines.node >= 24`. The package is
+  `"type": "module"`; relative imports carry `.js` extensions (NodeNext resolution).
+- Consumers must NOT add signalk-container to `dependencies`/`peerDependencies`
+  (its prereleases break npm semver ranges); declare it via `"signalk": { "requires":
+["signalk-container"] }` in package.json. The README documents this.
+- Supported signalk-container **runtime** baseline: **≥ 1.6.0** (for `whenReady`);
+  newer features degrade gracefully via feature detection.
+- The library's own type mirror is validated at build time against
+  **signalk-container ≥ 1.23.2** (the `signalk-container/types` entrypoint, whose
+  update-service types and their options 1.23.1–1.23.2 completed) via a `tsc`-checked contract test
+  (`test/types-contract.test-d.ts`), so drift from the canonical public API fails
+  CI. This is a dev-only devDependency; it imposes nothing on consumers.
+
+## 7. Test plan
+
+Unit tests (vitest) against a fake manager installed on `globalThis` and an injected
+`fetchImpl` — no real containers or network:
+
+- discovery: late-appearing manager, `whenReady` path, legacy polling path, runtime
+  failure vs manager absence, timeout.
+- `ManagedContainer.start`: ensureRunning call shape, self-heal recreate on image
+  drift, non-fatal probe failure, update registration, address resolution incl.
+  stale-port fallback parse, readiness polling, tag validation, error codes.
+- `applyUpdate`: recreate path, legacy triplet fallback, limbo error.
+- `stop`: unregister + stop ordering, error swallowing.
+- update routes: 503 without manager, check passthrough, apply happy path/400/500.
+- `AdoptedContainer`: register/unregister, manager-missing reporting.
+- http: `probeHttpHealth` retry/slow/exhaustion; `waitForHttpReady` deadline.
+- utils: tag pattern, `errMsg`, `startSafely` double-report suppression.

package/dist/adopted-container.d.ts

@@ -0,0 +1,55 @@
+import type { AppLike, ContainerManagerApi, UpdateCheckResult } from "./types.js";
+import { type VersionSourceSpec } from "./version-source.js";
+export interface AdoptedContainerOptions {
+    app: AppLike;
+    /** Your plugin id — update-service registration key. */
+    pluginId: string;
+    /**
+     * The container's name for display/registration. Adopted containers are
+     * usually NOT namespace-prefixed (systemd/Quadlet-managed peers), so
+     * manager.getState() cannot see them — probe their HTTP health directly
+     * (see probeHttpHealth) instead.
+     */
+    containerName: string;
+    /** Image repo without tag. */
+    image: string;
+    /** The tag the deployment pins (e.g. "latest"); string or live getter. */
+    currentTag: string | (() => string);
+    /**
+     * Ask the running app for its honest version (e.g. GET /api/health
+     * .version). Preferred over currentTag by the update comparator —
+     * essential when currentTag is floating.
+     */
+    currentVersion?: () => Promise<string | null>;
+    versionSource: VersionSourceSpec;
+    /** e.g. "24h" (default), "1h" minimum. */
+    checkInterval?: string;
+    /** Budget for waiting on signalk-container + runtime. Default 30_000. */
+    managerTimeoutMs?: number;
+    /** Poll interval while waiting for the manager global. Default 500. */
+    managerPollIntervalMs?: number;
+}
+/**
+ * "Adopt, don't manage" integration — the signalk-doctor / signalk-updater
+ * archetype. The container's lifecycle is owned elsewhere (systemd Quadlet,
+ * external host); the plugin only enrolls it with signalk-container's
+ * update-detection service and probes its health over HTTP.
+ */
+export declare class AdoptedContainer {
+    readonly options: AdoptedContainerOptions;
+    manager: ContainerManagerApi | undefined;
+    private registered;
+    constructor(options: AdoptedContainerOptions);
+    /**
+     * Wait for the manager, then register for update detection. Returns false
+     * (after setPluginError with an actionable message) when signalk-container
+     * or a runtime never becomes available — the plugin can continue degraded.
+     * Never throws.
+     */
+    register(): Promise<boolean>;
+    /** Best-effort deregistration for plugin.stop(). Never throws. */
+    unregister(): void;
+    /** updates.checkOne — null when the manager is unavailable. */
+    checkForUpdate(): Promise<UpdateCheckResult | null>;
+}
+//# sourceMappingURL=adopted-container.d.ts.map

package/dist/adopted-container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopted-container.d.ts","sourceRoot":"","sources":["../src/adopted-container.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAG7B,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,OAAO,CAAC;IACb,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9C,aAAa,EAAE,iBAAiB,CAAC;IACjC,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAEzC,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,uBAAuB;IAI5C;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAmDlC,kEAAkE;IAClE,UAAU,IAAI,IAAI;IAYlB,+DAA+D;IACzD,cAAc,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAK1D"}

package/dist/adopted-container.js

@@ -0,0 +1,76 @@
+import { getContainerManager, waitForContainerManager } from "./manager.js";
+import { buildVersionSource, } from "./version-source.js";
+import { errMsg } from "./util.js";
+/**
+ * "Adopt, don't manage" integration — the signalk-doctor / signalk-updater
+ * archetype. The container's lifecycle is owned elsewhere (systemd Quadlet,
+ * external host); the plugin only enrolls it with signalk-container's
+ * update-detection service and probes its health over HTTP.
+ */
+export class AdoptedContainer {
+    options;
+    manager;
+    registered = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Wait for the manager, then register for update detection. Returns false
+     * (after setPluginError with an actionable message) when signalk-container
+     * or a runtime never becomes available — the plugin can continue degraded.
+     * Never throws.
+     */
+    async register() {
+        const { app, pluginId, containerName, image, currentTag, currentVersion, versionSource, checkInterval, managerTimeoutMs = 30_000, managerPollIntervalMs = 500, } = this.options;
+        const { manager, runtime } = await waitForContainerManager({
+            timeoutMs: managerTimeoutMs,
+            intervalMs: managerPollIntervalMs,
+        });
+        if (!manager) {
+            app.setPluginError("signalk-container is not loaded — install it and restart the server. Update detection is disabled without it.");
+            return false;
+        }
+        if (!runtime) {
+            app.setPluginError("No container runtime detected (Podman or Docker) — update detection is disabled.");
+            return false;
+        }
+        this.manager = manager;
+        try {
+            manager.updates.register({
+                pluginId,
+                containerName,
+                image,
+                currentTag: typeof currentTag === "function" ? currentTag : () => currentTag,
+                currentVersion,
+                checkInterval,
+                versionSource: buildVersionSource(manager.updates, versionSource),
+            });
+            this.registered = true;
+            return true;
+        }
+        catch (err) {
+            app.setPluginError(`update registration failed: ${errMsg(err)}`);
+            return false;
+        }
+    }
+    /** Best-effort deregistration for plugin.stop(). Never throws. */
+    unregister() {
+        if (!this.registered)
+            return;
+        try {
+            (this.manager ?? getContainerManager())?.updates.unregister(this.options.pluginId);
+        }
+        catch (err) {
+            this.options.app.debug(`updates.unregister failed: ${errMsg(err)}`);
+        }
+        this.registered = false;
+    }
+    /** updates.checkOne — null when the manager is unavailable. */
+    async checkForUpdate() {
+        const manager = this.manager ?? getContainerManager();
+        if (!manager)
+            return null;
+        return manager.updates.checkOne(this.options.pluginId);
+    }
+}
+//# sourceMappingURL=adopted-container.js.map

package/dist/adopted-container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adopted-container.js","sourceRoot":"","sources":["../src/adopted-container.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EACL,kBAAkB,GAEnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAgCnC;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAA0B;IAC1C,OAAO,CAAkC;IAEjC,UAAU,GAAG,KAAK,CAAC;IAE3B,YAAY,OAAgC;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,EACJ,GAAG,EACH,QAAQ,EACR,aAAa,EACb,KAAK,EACL,UAAU,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,gBAAgB,GAAG,MAAM,EACzB,qBAAqB,GAAG,GAAG,GAC5B,GAAG,IAAI,CAAC,OAAO,CAAC;QAEjB,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,uBAAuB,CAAC;YACzD,SAAS,EAAE,gBAAgB;YAC3B,UAAU,EAAE,qBAAqB;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,cAAc,CAChB,+GAA+G,CAChH,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,GAAG,CAAC,cAAc,CAChB,kFAAkF,CACnF,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,IAAI,CAAC;YACH,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACvB,QAAQ;gBACR,aAAa;gBACb,KAAK;gBACL,UAAU,EACR,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,UAAU;gBAClE,cAAc;gBACd,aAAa;gBACb,aAAa,EAAE,kBAAkB,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,CAAC;aAClE,CAAC,CAAC;YACH,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,cAAc,CAAC,+BAA+B,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,UAAU;YAAE,OAAO;QAC7B,IAAI,CAAC;YACH,CAAC,IAAI,CAAC,OAAO,IAAI,mBAAmB,EAAE,CAAC,EAAE,OAAO,CAAC,UAAU,CACzD,IAAI,CAAC,OAAO,CAAC,QAAQ,CACtB,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,8BAA8B,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,cAAc;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,mBAAmB,EAAE,CAAC;QACtD,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/http.d.ts

@@ -0,0 +1,66 @@
+/** Injectable fetch for tests; matches the global fetch signature loosely. */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+    [key: string]: unknown;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface FetchWithTimeoutOptions {
+    /** Per-request timeout via AbortController. Default 10_000. */
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+    [key: string]: unknown;
+}
+/**
+ * `fetch` with an AbortController timeout — the bare pattern every reference
+ * plugin re-implements for talking to the app inside its container.
+ */
+export declare function fetchWithTimeout(url: string, options?: FetchWithTimeoutOptions): Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface WaitForHttpReadyOptions {
+    /** Overall deadline. Default 60_000. */
+    maxMs?: number;
+    /** Delay between attempts. Default 1_000. */
+    intervalMs?: number;
+    /** Per-request timeout. Default 2_000. */
+    requestTimeoutMs?: number;
+    fetchImpl?: FetchLike;
+}
+/**
+ * Poll a URL until it answers 2xx, or throw when the deadline passes.
+ * "Container running" is not "app ready" — every managed plugin polls the
+ * containerized app's own health endpoint after ensureRunning.
+ */
+export declare function waitForHttpReady(url: string, options?: WaitForHttpReadyOptions): Promise<void>;
+export interface ProbeHttpHealthOptions {
+    /** Total attempts. Default 3. */
+    attempts?: number;
+    /** Per-attempt timeout. Default 5_000. */
+    attemptTimeoutMs?: number;
+    /** Delay between attempts. Default 2_000. */
+    retryDelayMs?: number;
+    /**
+     * Threshold above which a successful probe is flagged slow (likely disk
+     * I/O contention on SD-card hosts). Default 1_500.
+     */
+    slowMs?: number;
+    fetchImpl?: FetchLike;
+}
+export interface HealthProbeResult {
+    reachable: boolean;
+    /** Set when reachable but the successful attempt exceeded `slowMs`. */
+    slowMs?: number;
+}
+/**
+ * Retrying liveness probe with slow-response detection. Signal K's plugin
+ * API has no warning tier, so callers typically report a slow-but-healthy
+ * result through `setPluginStatus` rather than `setPluginError`.
+ * Never throws.
+ */
+export declare function probeHttpHealth(url: string, options?: ProbeHttpHealthOptions): Promise<HealthProbeResult>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,KACpD,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAUpE;AAED,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CA0B5B"}

package/dist/http.js

@@ -0,0 +1,76 @@
+import { errMsg, sleep } from "./util.js";
+/**
+ * `fetch` with an AbortController timeout — the bare pattern every reference
+ * plugin re-implements for talking to the app inside its container.
+ */
+export async function fetchWithTimeout(url, options = {}) {
+    const { timeoutMs = 10_000, fetchImpl, ...init } = options;
+    const impl = fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await impl(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Poll a URL until it answers 2xx, or throw when the deadline passes.
+ * "Container running" is not "app ready" — every managed plugin polls the
+ * containerized app's own health endpoint after ensureRunning.
+ */
+export async function waitForHttpReady(url, options = {}) {
+    const { maxMs = 60_000, intervalMs = 1_000, requestTimeoutMs = 2_000, fetchImpl, } = options;
+    const deadline = Date.now() + maxMs;
+    let lastErr;
+    for (;;) {
+        try {
+            const res = await fetchWithTimeout(url, {
+                timeoutMs: requestTimeoutMs,
+                fetchImpl,
+            });
+            if (res.ok)
+                return;
+            lastErr = new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+        if (Date.now() >= deadline)
+            break;
+        await sleep(intervalMs);
+    }
+    throw new Error(`${url} did not become ready within ${maxMs}ms: ${errMsg(lastErr)}`);
+}
+/**
+ * Retrying liveness probe with slow-response detection. Signal K's plugin
+ * API has no warning tier, so callers typically report a slow-but-healthy
+ * result through `setPluginStatus` rather than `setPluginError`.
+ * Never throws.
+ */
+export async function probeHttpHealth(url, options = {}) {
+    const { attempts = 3, attemptTimeoutMs = 5_000, retryDelayMs = 2_000, slowMs = 1_500, fetchImpl, } = options;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt > 0)
+            await sleep(retryDelayMs);
+        const started = Date.now();
+        try {
+            const res = await fetchWithTimeout(url, {
+                timeoutMs: attemptTimeoutMs,
+                fetchImpl,
+            });
+            if (!res.ok)
+                continue;
+            const elapsed = Date.now() - started;
+            return elapsed > slowMs
+                ? { reachable: true, slowMs: elapsed }
+                : { reachable: true };
+        }
+        catch {
+            // try again
+        }
+    }
+    return { reachable: false };
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./types.js";
+export { getContainerManager, waitForContainerManager } from "./manager.js";
+export type { WaitForManagerOptions, ManagerWaitResult } from "./manager.js";
+export { ManagedContainer } from "./managed-container.js";
+export type { ManagedContainerOptions, ManagedUpdateOptions, ReadinessOptions, StartResult, RouterLike, ResponseLike, UpdateRoutesOptions, } from "./managed-container.js";
+export { AdoptedContainer } from "./adopted-container.js";
+export type { AdoptedContainerOptions } from "./adopted-container.js";
+export { buildVersionSource } from "./version-source.js";
+export type { VersionSourceSpec } from "./version-source.js";
+export { fetchWithTimeout, waitForHttpReady, probeHttpHealth } from "./http.js";
+export type { FetchLike, FetchWithTimeoutOptions, WaitForHttpReadyOptions, ProbeHttpHealthOptions, HealthProbeResult, } from "./http.js";
+export { startSafely, errMsg, isValidImageTag, IMAGE_TAG_PATTERN, ContainerHelperError, } from "./util.js";
+export type { ContainerHelperErrorCode } from "./util.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,GACpB,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,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAChF,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,WAAW,EACX,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export { getContainerManager, waitForContainerManager } from "./manager.js";
+export { ManagedContainer } from "./managed-container.js";
+export { AdoptedContainer } from "./adopted-container.js";
+export { buildVersionSource } from "./version-source.js";
+export { fetchWithTimeout, waitForHttpReady, probeHttpHealth } from "./http.js";
+export { startSafely, errMsg, isValidImageTag, IMAGE_TAG_PATTERN, ContainerHelperError, } from "./util.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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;AAU1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAQhF,OAAO,EACL,WAAW,EACX,MAAM,EACN,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,WAAW,CAAC"}