signalk-container 1.7.0 → 1.8.0

package/dist/containers.js

@@ -1,83 +1,7 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_TAIL = void 0;
-exports.volumeArg = volumeArg;
-exports.classifyVolumeSources = classifyVolumeSources;
-exports.collectRecoveredVolumes = collectRecoveredVolumes;
-exports.safeInvokeVolumeIssue = safeInvokeVolumeIssue;
-exports.safeInvokeContainerLog = safeInvokeContainerLog;
-exports.tailContainerLogs = tailContainerLogs;
-exports.parsePositiveIntQuery = parsePositiveIntQuery;
-exports.getContainerLogs = getContainerLogs;
-exports.qualifyImage = qualifyImage;
-exports.imageExists = imageExists;
-exports.getImageDigest = getImageDigest;
-exports.pullImage = pullImage;
-exports.getContainerState = getContainerState;
-exports.getLiveResources = getLiveResources;
-exports.parsePortBindings = parsePortBindings;
-exports.getActualPortBindings = getActualPortBindings;
-exports.getLiveContainerConfig = getLiveContainerConfig;
-exports.diffContainerConfig = diffContainerConfig;
-exports.ensureRunning = ensureRunning;
-exports.startContainer = startContainer;
-exports.stopContainer = stopContainer;
-exports.removeContainer = removeContainer;
-exports.listContainers = listContainers;
-exports.pruneImages = pruneImages;
-exports.execInContainer = execInContainer;
-exports.ensureNetwork = ensureNetwork;
-exports.removeNetwork = removeNetwork;
-exports.connectToNetwork = connectToNetwork;
-exports.disconnectFromNetwork = disconnectFromNetwork;
-exports.parseSelfContainerIdFromCgroup = parseSelfContainerIdFromCgroup;
-exports.parseSelfContainerIdsFromCgroupFile = parseSelfContainerIdsFromCgroupFile;
-exports.readSelfContainerIdsFromCgroup = readSelfContainerIdsFromCgroup;
-exports.findSelfContainerId = findSelfContainerId;
-exports.resolveSignalkDataSource = resolveSignalkDataSource;
-exports.resolveHostPathFromMounts = resolveHostPathFromMounts;
-exports.resolveHostPath = resolveHostPath;
-exports.releaseReservedPort = releaseReservedPort;
-exports.findAvailablePort = findAvailablePort;
-exports.resolveSignalkNetworks = resolveSignalkNetworks;
-exports.waitForReady = waitForReady;
-const net = __importStar(require("net"));
-const node_fs_1 = require("node:fs");
-const runtime_1 = require("./runtime");
-const resources_1 = require("./resources");
+import * as net from "node:net";
+import { existsSync, readFileSync } from "node:fs";
+import { execRuntime, execRuntimeLong, isContainerized, spawnRuntimeStreaming, userMappingFlags, } from "./runtime.js";
+import { resourceFlagsForRun } from "./resources.js";
 const CONTAINER_PREFIX = "sk-";
 function prefixedName(name) {
     return name.startsWith(CONTAINER_PREFIX)
@@ -95,7 +19,7 @@ function prefixedName(name) {
  * Used by both ContainerConfig.volumes (containers.ts) and JobConfig
  * inputs/outputs (jobs.ts) so the named-volume guard stays in one place.
  */
-function volumeArg(hostPath, containerPath, runtime, readOnly = false) {
+export function volumeArg(hostPath, containerPath, runtime, readOnly = false) {
     const isNamedVolume = !hostPath.startsWith("/") && !hostPath.startsWith(".");
     const flags = [];
     if (readOnly)
@@ -140,7 +64,7 @@ function volumeSource(raw) {
  * `probe` is the host-path existence check; defaults to `existsSync`.
  * Tests inject a stub so they don't touch the filesystem.
  */
-function classifyVolumeSources(volumes, probe = node_fs_1.existsSync) {
+export function classifyVolumeSources(volumes, probe = existsSync) {
     const kept = {};
     const skipped = [];
     const aborted = [];
@@ -195,7 +119,7 @@ function classifyVolumeSources(volumes, probe = node_fs_1.existsSync) {
  *
  * Pure function — no I/O.
  */
-function collectRecoveredVolumes(prior, currentSkipped, currentAborted, kept) {
+export function collectRecoveredVolumes(prior, currentSkipped, currentAborted, kept) {
     if (!prior)
         return [];
     const stillMissing = new Set([...currentSkipped, ...currentAborted].map((v) => v.containerPath));
@@ -228,7 +152,7 @@ function collectRecoveredVolumes(prior, currentSkipped, currentAborted, kept) {
  * Pure-by-design: `reportError` is injected so tests can capture
  * the message instead of writing to `app.error`.
  */
-function safeInvokeVolumeIssue(handler, event, reportError) {
+export function safeInvokeVolumeIssue(handler, event, reportError) {
     if (!handler)
         return;
     try {
@@ -249,7 +173,7 @@ function safeInvokeVolumeIssue(handler, event, reportError) {
  * doc for why the `try { Promise.resolve(...).catch(...) }` dance
  * is needed.
  */
-function safeInvokeContainerLog(handler, line, reportError) {
+export function safeInvokeContainerLog(handler, line, reportError) {
     if (!handler)
         return;
     try {
@@ -271,8 +195,8 @@ function safeInvokeContainerLog(handler, line, reportError) {
  *
  * `spawn` is exposed for tests (defaults to `spawnRuntimeStreaming`).
  */
-function tailContainerLogs(runtime, name, onLine, options) {
-    const spawnFn = options?.spawn ?? runtime_1.spawnRuntimeStreaming;
+export function tailContainerLogs(runtime, name, onLine, options) {
+    const spawnFn = options?.spawn ?? spawnRuntimeStreaming;
     const fullName = prefixedName(name);
     const tail = String(normalizeTail(options?.startTail, 0));
     return spawnFn(runtime, ["logs", "-f", "--tail", tail, fullName], onLine, {
@@ -289,7 +213,7 @@ function tailContainerLogs(runtime, name, onLine, options) {
     });
 }
 /** Upper bound for `--tail N` accepted at the public boundary. */
-exports.MAX_TAIL = 10000;
+export const MAX_TAIL = 10000;
 /**
  * Coerce an optional caller-supplied tail count to a finite,
  * non-negative integer so a buggy or hostile caller can never
@@ -301,7 +225,7 @@ exports.MAX_TAIL = 10000;
 function normalizeTail(value, fallback) {
     if (value === undefined || !Number.isFinite(value))
         return fallback;
-    return Math.min(Math.max(0, Math.floor(value)), exports.MAX_TAIL);
+    return Math.min(Math.max(0, Math.floor(value)), MAX_TAIL);
 }
 /**
  * Validate an optional unsigned-integer query parameter (e.g.
@@ -314,7 +238,7 @@ function normalizeTail(value, fallback) {
  * instead of forwarding silently-coerced values to runtime-facing
  * logic.  Exported so the parser is testable in isolation.
  */
-function parsePositiveIntQuery(raw, field) {
+export function parsePositiveIntQuery(raw, field) {
     if (raw === undefined || raw === "")
         return { value: undefined };
     if (typeof raw !== "string")
@@ -356,7 +280,7 @@ function parsePositiveIntQuery(raw, field) {
  * Used both by the `GET /containers/:name/logs` REST route and by
  * `ContainerManagerApi.getLogs` for in-process consumer-plugin calls.
  */
-async function getContainerLogs(runtime, name, options, exec = runtime_1.execRuntime) {
+export async function getContainerLogs(runtime, name, options, exec = execRuntime) {
     const tail = normalizeTail(options?.tail, 200);
     const args = ["logs", "--tail", String(tail)];
     if (options?.since !== undefined &&
@@ -384,15 +308,31 @@ async function getContainerLogs(runtime, name, options, exec = runtime_1.execRun
     };
     return [...toLines(result.stdout), ...toLines(result.stderr)];
 }
-function qualifyImage(image, runtime) {
+/**
+ * Bare image id: 64 hex chars, optionally with the `sha256:` prefix
+ * podman/docker print for `Config.Image`. Such ids must never be
+ * qualified with a registry — they're addressable by content, not by
+ * name.
+ */
+const BARE_IMAGE_ID = /^(?:sha256:)?[a-f0-9]{64}$/;
+export function qualifyImage(image, runtime) {
     // Podman requires fully qualified image names when unqualified-search
     // registries are not configured. Prefix docker.io/ if missing.
     if (runtime.runtime === "podman") {
-        const parts = image.split("/");
+        // Bare image ids (e.g. `sha256:abc…` or `abc…`) are content-addressed
+        // and never need a registry prefix; pass through.
+        if (BARE_IMAGE_ID.test(image))
+            return image;
+        // Strip any `@sha256:...` digest before splitting — for an
+        // unqualified ref like `alpine@sha256:abc...` the digest's `:`
+        // would otherwise make us think the first segment is `host:port`.
+        const refWithoutDigest = image.split("@", 1)[0];
+        const parts = refWithoutDigest.split("/");
         // Treat first component as a registry only if it has a dot, a colon
-        // (port), or is exactly "localhost". Otherwise, prefix docker.io/.
+        // (port) appearing in a multi-segment ref, or is exactly "localhost".
+        // Otherwise, prefix docker.io/.
         const looksLikeRegistry = parts[0].includes(".") ||
-            parts[0].includes(":") ||
+            (parts.length > 1 && parts[0].includes(":")) ||
             parts[0] === "localhost";
         if (parts.length <= 2 && !looksLikeRegistry) {
             return `docker.io/${image}`;
@@ -400,7 +340,7 @@ function qualifyImage(image, runtime) {
     }
     return image;
 }
-async function imageExists(runtime, image, exec = runtime_1.execRuntime) {
+export async function imageExists(runtime, image, exec = execRuntime) {
     const result = await exec(runtime, ["image", "inspect", image]);
     return result.exitCode === 0;
 }
@@ -413,10 +353,10 @@ async function imageExists(runtime, image, exec = runtime_1.execRuntime) {
  * pulled image, or a container name to inspect the image a running
  * container is using.
  */
-async function getImageDigest(runtime, imageOrContainer) {
+export async function getImageDigest(runtime, imageOrContainer, exec = execRuntime) {
     // Try image inspect first; fall back to container inspect for names.
     const qualified = qualifyImage(imageOrContainer, runtime);
-    const imgResult = await (0, runtime_1.execRuntime)(runtime, [
+    const imgResult = await exec(runtime, [
         "image",
         "inspect",
         "--format",
@@ -427,7 +367,7 @@ async function getImageDigest(runtime, imageOrContainer) {
         return imgResult.stdout.trim();
     }
     // Maybe it's a container name; .Image on a container returns the image ID.
-    const ctrResult = await (0, runtime_1.execRuntime)(runtime, [
+    const ctrResult = await exec(runtime, [
         "inspect",
         "--format",
         "{{.Image}}",
@@ -438,13 +378,74 @@ async function getImageDigest(runtime, imageOrContainer) {
     }
     return null;
 }
-async function pullImage(runtime, image, onProgress) {
-    const { exitCode, log } = await (0, runtime_1.execRuntimeLong)(runtime, ["pull", image], onProgress, 300000);
+/**
+ * Return the first RepoDigest for an image reference, as
+ * `sha256:<hex>` (without the `image@` prefix). This is the
+ * *manifest* digest — what consumer plugins and CI tools speak —
+ * distinct from the local image ID returned by `getImageDigest`.
+ *
+ * Returns null when the image has no RepoDigests, which happens for:
+ *   - locally-built images never pushed to a registry
+ *   - images side-loaded via `podman load` from a tarball
+ *
+ * The resolver falls back to a `local:<image-id>` synthetic identity
+ * in that case so the manifest entry still round-trips.
+ */
+export async function getRepoDigest(runtime, image, exec = execRuntime) {
+    const qualified = qualifyImage(image, runtime);
+    // The {{if .RepoDigests}}{{end}} guard avoids `[<no value>]` output
+    // that some podman versions emit when RepoDigests is empty.
+    const result = await exec(runtime, [
+        "image",
+        "inspect",
+        "--format",
+        "{{if .RepoDigests}}{{index .RepoDigests 0}}{{end}}",
+        qualified,
+    ]);
+    if (result.exitCode !== 0)
+        return null;
+    const raw = result.stdout.trim();
+    if (!raw)
+        return null;
+    const at = raw.lastIndexOf("@");
+    if (at < 0)
+        return null;
+    const digest = raw.slice(at + 1);
+    return /^sha256:[a-f0-9]{64}$/.test(digest) ? digest : null;
+}
+/**
+ * Return the digest of the image a *running* container is actually
+ * using, in the form `sha256:<hex>` or `local:<image-id>`.
+ *
+ * Distinct from "what `image:tag` resolves to right now": if someone
+ * `podman pull`'d the image after the container started, the local
+ * tag moved but the container is still on the old bits. This walks
+ * from the container's image-id (immutable for its lifetime) to its
+ * RepoDigests.
+ *
+ * Returns null if the container doesn't exist or the runtime can't
+ * read its image-id.
+ */
+export async function getLiveContainerDigest(runtime, containerName, exec = execRuntime) {
+    // The caller passes the unprefixed name from `ensureRunning`; the
+    // running container always carries the `sk-` prefix.
+    const imageId = await getImageDigest(runtime, prefixedName(containerName), exec);
+    if (!imageId)
+        return null;
+    const repoDigest = await getRepoDigest(runtime, imageId, exec);
+    if (repoDigest)
+        return repoDigest;
+    // Locally-built image with no RepoDigests — return the local id
+    // under the same `local:` namespace the resolver uses.
+    return `local:${imageId}`;
+}
+export async function pullImage(runtime, image, onProgress) {
+    const { exitCode, log } = await execRuntimeLong(runtime, ["pull", image], onProgress, 300000);
     if (exitCode !== 0) {
         throw new Error(`Failed to pull ${image}: ${log.slice(-5).join("\n")}`);
     }
 }
-async function getContainerState(runtime, name, exec = runtime_1.execRuntime) {
+export async function getContainerState(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     // Query multiple state fields and treat the container as running if
     // ANY of them indicate running. Rationale: rootless podman on some
@@ -502,7 +503,7 @@ async function getContainerState(runtime, name, exec = runtime_1.execRuntime) {
  *
  * `exec` defaults to the production execRuntime; tests pass a stub.
  */
-async function getLiveResources(runtime, name, exec = runtime_1.execRuntime) {
+export async function getLiveResources(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     // Use Go-template format for reliable parsing across podman/docker.
     // Each line is one numeric or string value; empty/zero means "unset".
@@ -599,7 +600,7 @@ function bytesToString(bytes) {
  * already handle "no binding found" so a parse error degrades gracefully into
  * "leave the existing cache alone".
  */
-function parsePortBindings(json) {
+export function parsePortBindings(json) {
     const out = new Map();
     if (!json || json === "null")
         return out;
@@ -648,7 +649,7 @@ function parsePortBindings(json) {
  * Returns an empty map on inspect failure; callers fall back to whatever they
  * had pre-validation.
  */
-async function getActualPortBindings(runtime, name, exec = runtime_1.execRuntime) {
+export async function getActualPortBindings(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     const result = await exec(runtime, [
         "inspect",
@@ -669,7 +670,7 @@ async function getActualPortBindings(runtime, name, exec = runtime_1.execRuntime
  * what the container was actually created with, so a recreate can fire
  * automatically instead of silently ignoring the new config until restart.
  */
-async function getLiveContainerConfig(runtime, name, exec = runtime_1.execRuntime) {
+export async function getLiveContainerConfig(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     // Sentinel between sections — `\x1f` (ASCII unit separator) avoids any
     // collision with shell-meta or path characters that might appear inside
@@ -685,28 +686,40 @@ async function getLiveContainerConfig(runtime, name, exec = runtime_1.execRuntim
         SEP +
         "{{json .Config.Env}}" +
         SEP +
-        "{{json .HostConfig.PortBindings}}";
+        "{{json .HostConfig.PortBindings}}" +
+        SEP +
+        "{{json .HostConfig.ExtraHosts}}" +
+        SEP +
+        "{{.Config.User}}";
     const result = await exec(runtime, ["inspect", "--format", fmt, fullName]);
     if (result.exitCode !== 0)
         return null;
     const parts = result.stdout.split(SEP);
-    if (parts.length !== 6)
+    if (parts.length !== 8)
         return null;
-    const [rawImage, rawCmd, rawNetworkMode, rawBinds, rawEnv, rawPortBindings] = parts;
-    // Split image into image+tag on the LAST colon (registries can carry
-    // ports like `localhost:5000/foo:tag`). If no tag, default to "latest"
-    // — matches what `qualifyImage` would have produced.
+    const [rawImage, rawCmd, rawNetworkMode, rawBinds, rawEnv, rawPortBindings, rawExtraHosts, rawUser,] = parts;
+    // Split image into image+tag (and optional digest). Config.Image can
+    // be `repo:tag`, `repo@sha256:...`, or `repo:tag@sha256:...`.
+    // Registries with ports (`localhost:5000/foo:tag`) push the
+    // image-vs-tag colon past the last slash.
     const imageRef = rawImage.trim();
-    const lastColon = imageRef.lastIndexOf(":");
-    const lastSlash = imageRef.lastIndexOf("/");
+    let imageAndTag = imageRef;
+    let digest = null;
+    const atIdx = imageRef.indexOf("@sha256:");
+    if (atIdx >= 0) {
+        imageAndTag = imageRef.slice(0, atIdx);
+        digest = imageRef.slice(atIdx + 1);
+    }
+    const lastColon = imageAndTag.lastIndexOf(":");
+    const lastSlash = imageAndTag.lastIndexOf("/");
     let image;
     let tag;
     if (lastColon > lastSlash) {
-        image = imageRef.slice(0, lastColon);
-        tag = imageRef.slice(lastColon + 1);
+        image = imageAndTag.slice(0, lastColon);
+        tag = imageAndTag.slice(lastColon + 1);
     }
     else {
-        image = imageRef;
+        image = imageAndTag;
         tag = "latest";
     }
     let command = null;
@@ -770,7 +783,39 @@ async function getLiveContainerConfig(runtime, name, exec = runtime_1.execRuntim
         // leave empty
     }
     const portBindings = parsePortBindingsFromJsonString(rawPortBindings);
-    return { image, tag, command, networkMode, env, binds, portBindings };
+    const extraHosts = new Map();
+    try {
+        const parsed = JSON.parse(rawExtraHosts);
+        if (Array.isArray(parsed)) {
+            for (const entry of parsed) {
+                if (typeof entry !== "string")
+                    continue;
+                // ExtraHosts format: "hostname:ipaddress"
+                const colon = entry.indexOf(":");
+                if (colon < 0)
+                    continue;
+                const hostname = entry.slice(0, colon);
+                const ip = entry.slice(colon + 1);
+                extraHosts.set(hostname, ip);
+            }
+        }
+    }
+    catch {
+        // leave empty
+    }
+    const user = (rawUser ?? "").trim();
+    return {
+        image,
+        tag,
+        digest,
+        command,
+        networkMode,
+        env,
+        binds,
+        portBindings,
+        extraHosts,
+        user,
+    };
 }
 /**
  * Wrapper around `parsePortBindings` that keeps the container-port key as
@@ -897,10 +942,12 @@ function bindingsEqual(a, b) {
  *   - ports: container-port key compared as runtime-emitted (`9000/tcp`).
  *     Multiple host bindings per container port compared as a sorted set.
  */
-function diffContainerConfig(requested, live, runtime, prior) {
+export function diffContainerConfig(requested, live, runtime, prior) {
     const drifted = [];
-    const requestedImageRef = qualifyImage(`${requested.image}:${requested.tag}`, runtime);
-    const liveImageRef = qualifyImage(`${live.image}:${live.tag}`, runtime);
+    const requestedImageRef = qualifyImage(requested.digest
+        ? `${requested.image}@${requested.digest}`
+        : `${requested.image}:${requested.tag}`, runtime);
+    const liveImageRef = qualifyImage(live.digest ? `${live.image}@${live.digest}` : `${live.image}:${live.tag}`, runtime);
     if (requestedImageRef !== liveImageRef)
         drifted.push("image+tag");
     if (requested.command !== undefined) {
@@ -989,11 +1036,55 @@ function diffContainerConfig(requested, live, runtime, prior) {
     }
     if (portsDrift)
         drifted.push("ports");
+    // ExtraHosts: build canonical Map<hostname, ip> for each side.
+    const requestedExtraHosts = new Map();
+    if (requested.extraHosts) {
+        for (const [hostname, ip] of Object.entries(requested.extraHosts)) {
+            requestedExtraHosts.set(hostname, ip);
+        }
+    }
+    // This plugin injects host.containers.internal:host-gateway in
+    // buildRunArgs() for Docker so containers can reach the host the
+    // same way Podman does natively. Mirror that here so the live
+    // ExtraHosts (which records the flag) doesn't fire false drift —
+    // but only when the user didn't supply their own override for the
+    // same key.
+    if (runtime.runtime === "docker" &&
+        !requestedExtraHosts.has("host.containers.internal")) {
+        requestedExtraHosts.set("host.containers.internal", "host-gateway");
+    }
+    let extraHostsDrift = requestedExtraHosts.size !== live.extraHosts.size;
+    if (!extraHostsDrift) {
+        for (const [hostname, ip] of requestedExtraHosts) {
+            if (live.extraHosts.get(hostname) !== ip) {
+                extraHostsDrift = true;
+                break;
+            }
+        }
+    }
+    if (extraHostsDrift)
+        drifted.push("extraHosts");
+    // User/ownership drift. Compute the `--user uid:gid` form the
+    // translator would emit and compare to live `Config.User`. The
+    // `--userns=keep-id` flag (rootless Podman) doesn't surface in
+    // `Config.User`, so we only fire drift when the expected form is
+    // a `--user` flag — that is, opt-out, rootless-Podman, and
+    // unavailable-hostUser all suppress drift on this field by design.
+    const expectedUserFlags = userMappingFlags(runtime, requested.user);
+    const userIdx = expectedUserFlags.indexOf("--user");
+    const expectedUser = userIdx >= 0 && userIdx + 1 < expectedUserFlags.length
+        ? expectedUserFlags[userIdx + 1]
+        : null;
+    if (expectedUser !== null && expectedUser !== live.user) {
+        drifted.push("user");
+    }
     return { drifted };
 }
 function buildRunArgs(name, config, runtime) {
     const fullName = prefixedName(name);
-    const imageRef = qualifyImage(`${config.image}:${config.tag}`, runtime);
+    const imageRef = qualifyImage(config.digest
+        ? `${config.image}@${config.digest}`
+        : `${config.image}:${config.tag}`, runtime);
     const args = ["run", "-d", "--name", fullName];
     if (config.restart && config.restart !== "no") {
         args.push("--restart", config.restart);
@@ -1001,6 +1092,11 @@ function buildRunArgs(name, config, runtime) {
     if (config.networkMode) {
         args.push("--network", config.networkMode);
     }
+    // UID/GID alignment so files created inside the container on bind-
+    // mounted host paths land owned by the host caller. Same decision
+    // matrix as `runJob` (see `userMappingFlags`). `config.user === false`
+    // opts out; the in-image UID/GID defaults to 0 when not declared.
+    args.push(...userMappingFlags(runtime, config.user));
     if (config.ports) {
         for (const [containerPort, hostBind] of Object.entries(config.ports)) {
             const port = containerPort.replace(/\/tcp$/, "");
@@ -1017,17 +1113,32 @@ function buildRunArgs(name, config, runtime) {
             args.push("-e", `${key}=${value}`);
         }
     }
+    // Add extra hosts: user-provided + (for Docker) the
+    // host.containers.internal:host-gateway mapping Podman provides
+    // natively. Skip the Docker injection if the user already supplied
+    // their own value for the same key to avoid duplicate /etc/hosts
+    // entries and the implicit first-match-wins override.
+    const userHasInternalOverride = !!config.extraHosts &&
+        Object.prototype.hasOwnProperty.call(config.extraHosts, "host.containers.internal");
+    if (config.extraHosts) {
+        for (const [hostname, ip] of Object.entries(config.extraHosts)) {
+            args.push("--add-host", `${hostname}:${ip}`);
+        }
+    }
+    if (runtime.runtime === "docker" && !userHasInternalOverride) {
+        args.push("--add-host", "host.containers.internal:host-gateway");
+    }
     // Resource limits (--cpus, --memory, --pids-limit, etc.)
     // Fields whose backing cgroup controller is unavailable on this
     // runtime are silently dropped.
-    args.push(...(0, resources_1.resourceFlagsForRun)(config.resources, runtime));
+    args.push(...resourceFlagsForRun(config.resources, runtime));
     args.push(imageRef);
     if (config.command) {
         args.push(...config.command);
     }
     return args;
 }
-async function ensureRunning(runtime, name, config, debug, options, exec = runtime_1.execRuntime, 
+export async function ensureRunning(runtime, name, config, debug, options, exec = execRuntime, 
 /**
  * Prior `ContainerConfig` from the previous `ensureRunning` call within
  * this signalk-container lifetime, if any. Used to detect "unset" drift
@@ -1039,7 +1150,9 @@ async function ensureRunning(runtime, name, config, debug, options, exec = runti
 prior, _postRecreate = false) {
     const state = await getContainerState(runtime, name, exec);
     const fullName = prefixedName(name);
-    const imageRef = qualifyImage(`${config.image}:${config.tag}`, runtime);
+    const imageRef = qualifyImage(config.digest
+        ? `${config.image}@${config.digest}`
+        : `${config.image}:${config.tag}`, runtime);
     // Drift detection is needed for both "running" and "stopped" — a stopped
     // container with stale env/volumes/ports/command would otherwise be
     // re-started with the OLD config. Inspect works on both states.
@@ -1106,14 +1219,14 @@ prior, _postRecreate = false) {
         }
     }
 }
-async function startContainer(runtime, name) {
+export async function startContainer(runtime, name) {
     const fullName = prefixedName(name);
-    const result = await (0, runtime_1.execRuntime)(runtime, ["start", fullName]);
+    const result = await execRuntime(runtime, ["start", fullName]);
     if (result.exitCode !== 0) {
         throw new Error(`Failed to start ${fullName}: ${result.stderr}`);
     }
 }
-async function fixVolumePermissions(runtime, name, exec = runtime_1.execRuntime) {
+async function fixVolumePermissions(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     const state = await getContainerState(runtime, name, exec);
     if (state !== "running")
@@ -1134,10 +1247,10 @@ async function fixVolumePermissions(runtime, name, exec = runtime_1.execRuntime)
     // back silently if chmod isn't available in the image (distroless etc.).
     await exec(runtime, ["exec", fullName, "chmod", "-R", "o+rwX", ...mounts]);
 }
-async function stopContainer(runtime, name) {
+export async function stopContainer(runtime, name) {
     const fullName = prefixedName(name);
     await fixVolumePermissions(runtime, name).catch(() => { });
-    const result = await (0, runtime_1.execRuntime)(runtime, ["stop", fullName]);
+    const result = await execRuntime(runtime, ["stop", fullName]);
     if (result.exitCode !== 0) {
         const state = await getContainerState(runtime, name);
         if (state !== "stopped" && state !== "missing") {
@@ -1145,7 +1258,7 @@ async function stopContainer(runtime, name) {
         }
     }
 }
-async function removeContainer(runtime, name, exec = runtime_1.execRuntime) {
+export async function removeContainer(runtime, name, exec = execRuntime) {
     const fullName = prefixedName(name);
     await fixVolumePermissions(runtime, name, exec).catch(() => { });
     await exec(runtime, ["stop", fullName]);
@@ -1154,8 +1267,8 @@ async function removeContainer(runtime, name, exec = runtime_1.execRuntime) {
         throw new Error(`Failed to remove ${fullName}: ${result.stderr}`);
     }
 }
-async function listContainers(runtime) {
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+export async function listContainers(runtime) {
+    const result = await execRuntime(runtime, [
         "ps",
         "-a",
         "--filter",
@@ -1183,8 +1296,8 @@ async function listContainers(runtime) {
         };
     });
 }
-async function pruneImages(runtime) {
-    const result = await (0, runtime_1.execRuntime)(runtime, ["image", "prune", "-f"]);
+export async function pruneImages(runtime) {
+    const result = await execRuntime(runtime, ["image", "prune", "-f"]);
     if (result.exitCode !== 0) {
         throw new Error(`Prune failed: ${result.stderr}`);
     }
@@ -1195,28 +1308,28 @@ async function pruneImages(runtime) {
         spaceReclaimed: reclaimedMatch?.[1] ?? "0 B",
     };
 }
-async function execInContainer(runtime, name, command) {
+export async function execInContainer(runtime, name, command) {
     const fullName = prefixedName(name);
-    return (0, runtime_1.execRuntime)(runtime, ["exec", fullName, ...command]);
+    return execRuntime(runtime, ["exec", fullName, ...command]);
 }
-async function ensureNetwork(runtime, name) {
-    const inspect = await (0, runtime_1.execRuntime)(runtime, ["network", "inspect", name]);
+export async function ensureNetwork(runtime, name) {
+    const inspect = await execRuntime(runtime, ["network", "inspect", name]);
     if (inspect.exitCode !== 0) {
-        const create = await (0, runtime_1.execRuntime)(runtime, ["network", "create", name]);
+        const create = await execRuntime(runtime, ["network", "create", name]);
         if (create.exitCode !== 0 && !create.stderr.includes("already exists")) {
             throw new Error(`Failed to create network ${name}: ${create.stderr}`);
         }
     }
 }
-async function removeNetwork(runtime, name) {
-    const result = await (0, runtime_1.execRuntime)(runtime, ["network", "rm", name]);
+export async function removeNetwork(runtime, name) {
+    const result = await execRuntime(runtime, ["network", "rm", name]);
     if (result.exitCode !== 0 && !result.stderr.includes("not found")) {
         throw new Error(`Failed to remove network ${name}: ${result.stderr}`);
     }
 }
-async function connectToNetwork(runtime, containerName, networkName) {
+export async function connectToNetwork(runtime, containerName, networkName) {
     const fullName = prefixedName(containerName);
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "network",
         "connect",
         networkName,
@@ -1230,9 +1343,9 @@ async function connectToNetwork(runtime, containerName, networkName) {
         throw new Error(`Failed to connect ${fullName} to ${networkName}: ${result.stderr}`);
     }
 }
-async function disconnectFromNetwork(runtime, containerName, networkName) {
+export async function disconnectFromNetwork(runtime, containerName, networkName) {
     const fullName = prefixedName(containerName);
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "network",
         "disconnect",
         networkName,
@@ -1266,7 +1379,7 @@ async function disconnectFromNetwork(runtime, containerName, networkName) {
  * 12+ hex char run; `docker inspect` will reject false positives
  * (e.g. systemd slice names that happen to be hex).
  */
-function parseSelfContainerIdFromCgroup(line) {
+export function parseSelfContainerIdFromCgroup(line) {
     // 1) cgroup v1 path: `/<runtime>/<id>` where runtime is `docker`,
     //    `kubepods/...`, etc.
     const v1 = line.match(/[/]([0-9a-f]{12,64})(?:[/.]|$)/i);
@@ -1287,7 +1400,7 @@ function parseSelfContainerIdFromCgroup(line) {
  * tests can drive the multi-line / dedup logic without touching
  * `/proc/self/cgroup` (which varies across test hosts).
  */
-function parseSelfContainerIdsFromCgroupFile(content) {
+export function parseSelfContainerIdsFromCgroupFile(content) {
     const seen = new Set();
     const ids = [];
     for (const line of content.split("\n")) {
@@ -1316,10 +1429,10 @@ function parseSelfContainerIdsFromCgroupFile(content) {
  *
  * Skipped in production paths when `isContainerized()` is false.
  */
-function readSelfContainerIdsFromCgroup() {
+export function readSelfContainerIdsFromCgroup() {
     let content;
     try {
-        content = (0, node_fs_1.readFileSync)("/proc/self/cgroup", "utf8");
+        content = readFileSync("/proc/self/cgroup", "utf8");
     }
     catch {
         return [];
@@ -1337,7 +1450,7 @@ function readSelfContainerIdsFromCgroup() {
 async function tryInspect(runtime, candidateId, debug, source) {
     if (!candidateId)
         return null;
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "inspect",
         "--format",
         "{{.Id}}",
@@ -1371,7 +1484,7 @@ async function tryInspect(runtime, candidateId, debug, source) {
  * unset" behaviour — fall back to bare-metal-style handling, or
  * return null to the caller (depends on the consumer).
  */
-async function findSelfContainerId(runtime, debug = () => { }) {
+export async function findSelfContainerId(runtime, debug = () => { }) {
     // 1. Explicit override — no `inspect` validation needed since the
     //    operator chose this deliberately.  An invalid value here
     //    surfaces as the same downstream error the user would have
@@ -1413,8 +1526,8 @@ async function findSelfContainerId(runtime, debug = () => { }) {
  * a ContainerConfig.  The content visible at mountPoint inside the managed
  * container will always correspond to the root of dataDir.
  */
-async function resolveSignalkDataSource(dataDir, runtime, debug = () => { }) {
-    if (!(0, runtime_1.isContainerized)()) {
+export async function resolveSignalkDataSource(dataDir, runtime, debug = () => { }) {
+    if (!isContainerized()) {
         // Running bare-metal: dataDir is already a host filesystem path.
         return dataDir;
     }
@@ -1427,7 +1540,7 @@ async function resolveSignalkDataSource(dataDir, runtime, debug = () => { }) {
         debug(`resolveSignalkDataSource: could not detect self container id; falling back to dataDir=${dataDir}`);
         return dataDir;
     }
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "inspect",
         "--format",
         "{{range .Mounts}}{{.Type}}|{{.Name}}|{{.Source}}|{{.Destination}}\n{{end}}",
@@ -1477,7 +1590,7 @@ async function resolveSignalkDataSource(dataDir, runtime, debug = () => { }) {
  * logic can be unit-tested independently of the runtime.  Returns null
  * when no mount covers `absPath`.
  */
-function resolveHostPathFromMounts(absPath, mounts) {
+export function resolveHostPathFromMounts(absPath, mounts) {
     // Longest-prefix match.  Same logic as resolveSignalkDataSource — handles
     // exact matches and parent-directory mounts uniformly.
     let best = null;
@@ -1531,8 +1644,8 @@ function resolveHostPathFromMounts(absPath, mounts) {
  *     should surface an actionable error (not silently fall through, as
  *     `resolveSignalkDataSource` does for backwards-compat).
  */
-async function resolveHostPath(absPath, runtime, debug = () => { }) {
-    if (!(0, runtime_1.isContainerized)()) {
+export async function resolveHostPath(absPath, runtime, debug = () => { }) {
+    if (!isContainerized()) {
         // Bare-metal: the absolute path IS the host path.  No subpath needed.
         return { source: absPath, subPath: "" };
     }
@@ -1544,7 +1657,7 @@ async function resolveHostPath(absPath, runtime, debug = () => { }) {
         debug(`resolveHostPath: could not detect self container id; cannot resolve ${absPath}`);
         return null;
     }
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "inspect",
         "--format",
         "{{range .Mounts}}{{.Type}}|{{.Name}}|{{.Source}}|{{.Destination}}\n{{end}}",
@@ -1584,7 +1697,7 @@ const reservedPorts = new Set();
  * (so the OS-level bind now prevents collisions), or when the container
  * creation failed (so the next attempt can re-probe freely).
  */
-function releaseReservedPort(port) {
+export function releaseReservedPort(port) {
     reservedPorts.delete(port);
 }
 /**
@@ -1614,7 +1727,7 @@ function isPortAvailable(port) {
  * Used by the `signalkAccessiblePorts` bare-metal path to prefer the
  * declared port number while gracefully stepping over conflicts.
  */
-async function findAvailablePort(preferred) {
+export async function findAvailablePort(preferred) {
     for (let port = preferred; port <= 65535; port++) {
         if (reservedPorts.has(port))
             continue;
@@ -1645,8 +1758,8 @@ async function findAvailablePort(preferred) {
  *               back to `networkMode: container:<self-container-id>`.  A non-empty
  *               array contains the user-defined network names to attach to.
  */
-async function resolveSignalkNetworks(runtime, debug = () => { }) {
-    if (!(0, runtime_1.isContainerized)())
+export async function resolveSignalkNetworks(runtime, debug = () => { }) {
+    if (!isContainerized())
         return null;
     // Cascade detection — see `findSelfContainerId`.  Critically this fixes
     // `network_mode: host` deployments where HOSTNAME is the host machine
@@ -1656,7 +1769,7 @@ async function resolveSignalkNetworks(runtime, debug = () => { }) {
         debug("resolveSignalkNetworks: could not detect self container id, returning null");
         return null;
     }
-    const result = await (0, runtime_1.execRuntime)(runtime, [
+    const result = await execRuntime(runtime, [
         "inspect",
         "--format",
         "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}\n{{end}}",
@@ -1673,7 +1786,7 @@ async function resolveSignalkNetworks(runtime, debug = () => { }) {
     debug(`resolveSignalkNetworks: all=${all.join(",")} userDefined=${userDefined.join(",")}`);
     return userDefined;
 }
-async function waitForReady(url, timeoutMs = 30000, intervalMs = 500) {
+export async function waitForReady(url, timeoutMs = 30000, intervalMs = 500) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         try {