signalk-container 0.2.0 → 1.0.0

package/NOTICE

@@ -0,0 +1,22 @@
+signalk-container
+Copyright (c) 2026 Dirk Wahrheit
+
+This product includes a third-party icon:
+
+icon.svg — Lucide "container" icon
+  Source:  https://lucide.dev / https://github.com/lucide-icons/lucide
+  License: ISC License
+  Copyright (c) Lucide Icons and Contributors
+
+  Permission to use, copy, modify, and/or distribute this software for
+  any purpose with or without fee is hereby granted, provided that the
+  above copyright notice and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+  AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
+  DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
+  PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+  TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+  PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -13,7 +13,9 @@ Instead of each plugin implementing its own container orchestration, they delega
 - **Resource limits editor** -- interactive UI in the config panel for setting CPU/memory/PID caps per container. Values are applied live via `podman update` when possible (no downtime), falls back to recreate when needed. Stored overrides are minimized against the consumer plugin's defaults so a future default bump flows through automatically. See the [developer guide](doc/plugin-developer-guide.md#resource-limits).
 - **Reset to plugin default** -- one-click restore of a container's original resource limits, clearing any user override.
 - **Image management** -- scheduled pruning of dangling images (weekly/monthly)
-- **SELinux support** -- `:Z` volume flags for Podman on Fedora/RHEL
+- **Zero-config data dir sharing** -- `signalkDataMount` mounts the SignalK data directory into any managed container automatically, whether Signal K runs bare-metal, in Docker (named volume), or in Podman (named volume or bind mount). No host paths to configure.
+- **Zero-config container service connectivity** -- `signalkAccessiblePorts` lets the SignalK process connect back to a service running inside a managed container (e.g. an HTTP or TCP server). signalk-container picks the right networking strategy automatically — port binding on the host loopback for bare-metal deployments, or a shared Docker network with DNS for containerised ones. No host ports are exposed unnecessarily.
+- **SELinux support** -- `:Z` volume flags for Podman bind mounts on Fedora/RHEL; named volumes are handled correctly (`:Z` is not applied)
 - **Podman image qualification** -- automatically prefixes `docker.io/` for short image names
 - **Cross-plugin API** -- other plugins use `globalThis.__signalk_containerManager`
 
@@ -71,12 +73,19 @@ if (!containers) {
 await containers.ensureRunning("my-service", {
   image: "myorg/myimage",
   tag: "latest",
-  ports: { "8080/tcp": "127.0.0.1:8080" },
-  volumes: { "/data": app.getDataDirPath() },
+  signalkDataMount: "/data", // resolves to the SignalK data dir, regardless of deployment
+  signalkAccessiblePorts: [8080], // port 8080 in the container must be reachable by SignalK
   env: { MY_VAR: "value" },
   restart: "unless-stopped",
 });
 
+// Get the actual address to connect to (resolved after ensureRunning)
+const addr = await containers.resolveContainerAddress("my-service", 8080);
+if (!addr) throw new Error("Container address not available");
+// bare-metal  → "127.0.0.1:8080"  (or "127.0.0.1:8081" if 8080 was taken)
+// containerised → "sk-my-service:8080"  (Docker DNS, no host port exposed)
+const response = await fetch(`http://${addr}/status`);
+
 // Run a one-shot job
 const result = await containers.runJob({
   image: "myorg/converter",
@@ -91,31 +100,33 @@ See [doc/plugin-developer-guide.md](doc/plugin-developer-guide.md) for the full
 
 ## API
 
-| Method                                  | Description                                                  |
-| --------------------------------------- | ------------------------------------------------------------ |
-| `getRuntime()`                          | Returns `{ runtime, version, isPodmanDockerShim }` or `null` |
-| `pullImage(image, onProgress?)`         | Pull a container image (auto-qualifies for Podman)           |
-| `imageExists(image)`                    | Check if image exists locally                                |
-| `getImageDigest(imageOrContainer)`      | Local image ID (sha256) for an image:tag or container        |
-| `ensureRunning(name, config, options?)` | Create and start container if not running                    |
-| `start(name)`                           | Start a stopped container                                    |
-| `stop(name)`                            | Stop a running container                                     |
-| `remove(name)`                          | Stop and remove a container                                  |
-| `getState(name)`                        | Returns `running`, `stopped`, `missing`, or `no-runtime`     |
-| `runJob(config)`                        | Execute a one-shot container job                             |
-| `prune()`                               | Remove dangling images                                       |
-| `listContainers()`                      | List all `sk-` prefixed containers                           |
-| `execInContainer(name, command)`        | Run a command inside a running container                     |
-| `ensureNetwork(name)`                   | Create a Podman/Docker network if it doesn't exist           |
-| `removeNetwork(name)`                   | Remove a network                                             |
-| `connectToNetwork(container, network)`  | Add a container to a network (bridge mode only)              |
-| `disconnectFromNetwork(container, net)` | Remove a container from a network                            |
-| `updates.register(reg)`                 | Register a container for update detection                    |
-| `updates.unregister(pluginId)`          | Stop tracking updates for a plugin                           |
-| `updates.checkOne(pluginId)`            | Force a fresh update check (or coalesce with in-flight)      |
-| `updates.getLastResult(pluginId)`       | Cached last result, no network                               |
-| `updateResources(name, limits)`         | Apply new resource limits live, fall back to recreate        |
-| `getResources(name)`                    | Currently effective limits (plugin defaults ⊕ user override) |
+| Method                                  | Description                                                                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getRuntime()`                          | Returns `{ runtime, version, isPodmanDockerShim }` or `null`                                                                                                  |
+| `pullImage(image, onProgress?)`         | Pull a container image (auto-qualifies for Podman)                                                                                                            |
+| `imageExists(image)`                    | Check if image exists locally                                                                                                                                 |
+| `getImageDigest(imageOrContainer)`      | Local image ID (sha256) for an image:tag or container                                                                                                         |
+| `ensureRunning(name, config, options?)` | Create and start container if not running                                                                                                                     |
+| `start(name)`                           | Start a stopped container                                                                                                                                     |
+| `stop(name)`                            | Stop a running container                                                                                                                                      |
+| `remove(name)`                          | Stop and remove a container                                                                                                                                   |
+| `getState(name)`                        | Returns `running`, `stopped`, `missing`, or `no-runtime`                                                                                                      |
+| `runJob(config)`                        | Execute a one-shot container job                                                                                                                              |
+| `prune()`                               | Remove dangling images                                                                                                                                        |
+| `listContainers()`                      | List all `sk-` prefixed containers                                                                                                                            |
+| `execInContainer(name, command)`        | Run a command inside a running container                                                                                                                      |
+| `ensureNetwork(name)`                   | Create a Podman/Docker network if it doesn't exist                                                                                                            |
+| `removeNetwork(name)`                   | Remove a network                                                                                                                                              |
+| `connectToNetwork(container, network)`  | Add a container to a network (bridge mode only)                                                                                                               |
+| `disconnectFromNetwork(container, net)` | Remove a container from a network                                                                                                                             |
+| `updates.register(reg)`                 | Register a container for update detection                                                                                                                     |
+| `updates.unregister(pluginId)`          | Stop tracking updates for a plugin                                                                                                                            |
+| `updates.checkOne(pluginId)`            | Force a fresh update check (or coalesce with in-flight)                                                                                                       |
+| `updates.getLastResult(pluginId)`       | Cached last result, no network                                                                                                                                |
+| `updateResources(name, limits)`         | Apply new resource limits live, fall back to recreate                                                                                                         |
+| `getResources(name)`                    | Currently effective limits (plugin defaults ⊕ user override)                                                                                                  |
+| `resolveSignalkDataMount()`             | Resolve the volume name or host path that backs `app.getDataDirPath()` in the current deployment; returns `null` if the runtime is not yet initialised        |
+| `resolveContainerAddress(name, port)`   | Return the `host:port` string to reach `port` on a managed container from the SignalK process; call after `ensureRunning()` with `signalkAccessiblePorts` set |
 
 ## REST Endpoints
 
@@ -148,6 +159,88 @@ All mounted at `/plugins/signalk-container/api/`:
 | Background update checks | `true`   | Periodically check for updates in the background. Disable on metered connections — manual checks via the UI button still work. |
 | Container overrides      | `{}`     | Per-container resource limits (CPU, memory, PIDs). Field-level merged on top of consumer plugin defaults. See dev guide.       |
 
+## Mounting the SignalK data directory (`signalkDataMount`)
+
+When a managed container needs to read or write files that Signal K also accesses (e.g. HLS segments, exports, caches), use `signalkDataMount` instead of computing and hardcoding a host path or volume name.
+
+```typescript
+const SK_MOUNT = "/signalk-data";
+
+await containers.ensureRunning("my-worker", {
+  image: "myorg/myworker",
+  tag: "latest",
+  signalkDataMount: SK_MOUNT, // ← mount the SignalK data dir here
+  command: ["--output", path.join(SK_MOUNT, "my-plugin/output/result.bin")],
+});
+```
+
+signalk-container resolves the correct source automatically:
+
+| Deployment                     | What gets mounted                                                 |
+| ------------------------------ | ----------------------------------------------------------------- |
+| Bare-metal Signal K            | `app.getDataDirPath()` as a bind mount (already a host path)      |
+| Docker, volume-backed data dir | the named volume (e.g. `mystack_signalk-data`)                    |
+| Docker, bind-backed data dir   | the exact host path, even when a parent directory is bind-mounted |
+| Podman (rootless or root)      | same logic; named volumes receive no `:Z` flag                    |
+
+The content at `SK_MOUNT` inside the managed container always corresponds to the root of `app.getDataDirPath()`. Build paths using `path.join`:
+
+```typescript
+// Path inside managed container that corresponds to an absolute SignalK path:
+const containerPath = path.join(
+  SK_MOUNT,
+  path.relative(app.getDataDirPath(), absSignalkPath),
+);
+```
+
+> [!note]
+> Docker/Podman do not support subpath mounts on named volumes. If your data directory
+> is backed by a named volume, the entire volume is mounted at `SK_MOUNT`. Avoid writing
+> to paths inside `SK_MOUNT` that are also bind-mounted in the Signal K container (e.g.
+> a plugin's own directory if mounted with `./:/home/node/.signalk/node_modules/my-plugin`)
+> — those paths are not visible from inside the managed container.
+
+You can also call `containers.resolveSignalkDataMount()` if you need to inspect the resolved source at runtime (e.g. for logging).
+
+## Connecting back to a container service (`signalkAccessiblePorts`)
+
+When a managed container exposes an HTTP, TCP, or other service that the SignalK process itself needs to connect to (e.g. a video stream, a database, an inference engine), use `signalkAccessiblePorts` instead of hardcoding port bindings or writing deployment-detection logic in your plugin.
+
+```typescript
+const STREAM_PORT = 8090;
+
+await containers.ensureRunning("my-streamer", {
+  image: "myorg/streamer",
+  tag: "latest",
+  signalkAccessiblePorts: [STREAM_PORT],
+  restart: "unless-stopped",
+  command: ["--listen", String(STREAM_PORT)],
+});
+
+const addr = await containers.resolveContainerAddress(
+  "my-streamer",
+  STREAM_PORT,
+);
+if (!addr) throw new Error("Container address not available");
+// Connect from the SignalK process — addr is always the right host:port:
+http.get(`http://${addr}/stream`, handleResponse);
+```
+
+signalk-container resolves the correct networking strategy automatically:
+
+| Deployment                             | Strategy                                                                        | Address returned                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| Bare-metal Signal K                    | Port bound to `127.0.0.1` (first free port ≥ declared value)                    | `127.0.0.1:8090` (or `127.0.0.1:8091` if 8090 was taken) |
+| Containerised, user-defined network    | Container attached to SignalK's own Docker/Podman network; no host port exposed | `sk-my-streamer:8090` (Docker DNS)                       |
+| Containerised, default bridge (no DNS) | Container shares SignalK's network namespace                                    | `127.0.0.1:8090`                                         |
+
+The allocated address is cached for the lifetime of the plugin session, so repeated `ensureRunning()` calls never trigger an unwanted container recreate due to a port number change.
+
+> [!note]
+> `signalkAccessiblePorts` sets up networking automatically. Do not combine it with
+> a manual `ports` or `networkMode` entry for the same container — the field takes
+> full ownership of those concerns.
+
 ## Setting Resource Limits
 
 On a boat with limited compute (typically a Pi 4/5 or low-power x86 mini PC), one runaway container can starve Signal K, raise NMEA decode latency, trigger thermal throttling, or even take the host down via OOM. signalk-container exposes podman/docker resource flags so consumer plugins can set sensible defaults — and you, as the user, can tune them per-container in two ways: **the config panel UI (recommended)** or direct JSON edit (for scripted/automated setups).
@@ -340,3 +433,9 @@ ecosystem (signalk-questdb, signalk-grafana) are designed for this case.
 ## License
 
 MIT
+
+## Acknowledgements
+
+The plugin icon (`icon.svg`) is the **container** glyph from
+[Lucide Icons](https://lucide.dev), used under the ISC License. See
+[`NOTICE`](NOTICE) for the full attribution.

package/dist/containers.d.ts

@@ -1,4 +1,16 @@
 import { ContainerConfig, ContainerInfo, ContainerRuntimeInfo, ContainerState, HealthCheckOptions } from "./types";
+/**
+ * Build the value for a `-v <source>:<dest>[:flags]` argument with the
+ * correct SELinux relabel suffix for the runtime.
+ *
+ * `:Z` is for SELinux relabelling of bind-mount host paths under Podman
+ * on Fedora/RHEL. Named volumes (no leading '/' or '.') reject `:Z` with
+ * "invalid option z for named volume", so we omit the flag for them.
+ *
+ * Used by both ContainerConfig.volumes (containers.ts) and JobConfig
+ * inputs/outputs (jobs.ts) so the named-volume guard stays in one place.
+ */
+export declare function volumeArg(hostPath: string, containerPath: string, runtime: ContainerRuntimeInfo, readOnly?: boolean): string;
 export declare function qualifyImage(image: string, runtime: ContainerRuntimeInfo): string;
 export declare function imageExists(runtime: ContainerRuntimeInfo, image: string): Promise<boolean>;
 /**
@@ -63,6 +75,66 @@ export declare function ensureNetwork(runtime: ContainerRuntimeInfo, name: strin
 export declare function removeNetwork(runtime: ContainerRuntimeInfo, name: string): Promise<void>;
 export declare function connectToNetwork(runtime: ContainerRuntimeInfo, containerName: string, networkName: string): Promise<void>;
 export declare function disconnectFromNetwork(runtime: ContainerRuntimeInfo, containerName: string, networkName: string): Promise<void>;
+/**
+ * Resolve what to mount in a managed container to give it access to
+ * the SignalK data directory, regardless of how SignalK itself is deployed.
+ *
+ * Returns the string to use as the LEFT side of a `-v <source>:<dest>` flag:
+ *   - Bare-metal SignalK: returns dataDir directly (it is already a host path).
+ *   - SignalK in Docker, volume-backed dataDir: returns the named volume.
+ *   - SignalK in Docker, bind-backed dataDir: returns the exact host path
+ *     (computing the subpath when a parent directory is bind-mounted).
+ *   - Fallback (mount not found): returns dataDir — the caller's `-v` will
+ *     fail gracefully at container-create time with a clear Docker error.
+ *
+ * The result can be used directly as `volumes: { [mountPoint]: source }` in
+ * a ContainerConfig.  The content visible at mountPoint inside the managed
+ * container will always correspond to the root of dataDir.
+ */
+export declare function resolveSignalkDataSource(dataDir: string, runtime: ContainerRuntimeInfo, debug?: (msg: string) => void): Promise<string>;
+/**
+ * Release a port that was reserved by `findAvailablePort()`.
+ * Must be called after the container runtime has successfully bound the port
+ * (so the OS-level bind now prevents collisions), or when the container
+ * creation failed (so the next attempt can re-probe freely).
+ */
+export declare function releaseReservedPort(port: number): void;
+/**
+ * Find the lowest available TCP port on 127.0.0.1 starting at `preferred`.
+ *
+ * Probes by briefly binding a server socket and also skips ports that are
+ * already reserved in-process by a concurrent `findAvailablePort()` call,
+ * eliminating the TOCTOU window between the probe and the container create.
+ *
+ * The chosen port is added to the process-local `reservedPorts` set before
+ * this function resolves.  The caller is responsible for releasing it via
+ * `releaseReservedPort()` once the runtime holds the binding or the attempt
+ * fails.
+ *
+ * Used by the `signalkAccessiblePorts` bare-metal path to prefer the
+ * declared port number while gracefully stepping over conflicts.
+ */
+export declare function findAvailablePort(preferred: number): Promise<number>;
+/**
+ * Return the user-defined Docker/Podman networks that the current SignalK
+ * container is connected to (i.e. networks other than the default `bridge`,
+ * `host`, or `none`).
+ *
+ * Used by the `signalkAccessiblePorts` containerized path to attach a
+ * managed container to SignalK's own network so the two can communicate
+ * via DNS name without exposing any host port.
+ *
+ * Returns:
+ *   - `null`    when running bare-metal, HOSTNAME is unset, or `docker inspect`
+ *               fails (e.g. host-network mode where HOSTNAME is the machine
+ *               name, not a container ID).  Callers should treat this like
+ *               bare-metal and publish ports instead.
+ *   - `string[]` (possibly empty) when inspect succeeds.  An empty array means
+ *               SignalK is only on the default bridge — callers should fall
+ *               back to `networkMode: container:<HOSTNAME>`.  A non-empty
+ *               array contains the user-defined network names to attach to.
+ */
+export declare function resolveSignalkNetworks(runtime: ContainerRuntimeInfo, debug?: (msg: string) => void): Promise<string[] | null>;
 export declare function waitForReady(url: string, timeoutMs?: number, intervalMs?: number): Promise<void>;
 export {};
 //# sourceMappingURL=containers.d.ts.map

package/dist/containers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"containers.d.ts","sourceRoot":"","sources":["../src/containers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"containers.d.ts","sourceRoot":"","sources":["../src/containers.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAYjB;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,GAAE,OAAe,GACxB,MAAM,CAOR;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAgBR;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,oBAAoB,EAC7B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0BxB;AAED,wBAAsB,SAAS,CAC7B,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GACjC,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAoB,GACzB,OAAO,CAAC,cAAc,CAAC,CAoCzB;AAED;;;GAGG;AACH,KAAK,MAAM,GAAG,CACZ,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,MAAoB,GACzB,OAAO,CAAC,OAAO,SAAS,EAAE,uBAAuB,CAAC,CA2EpD;AAqED,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAE5B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAMf;AAkCD,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CA6B1B;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5D;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAG/D;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,oBAAoB,EAC7B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,oBAAoB,EAC7B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,KAAK,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe,GACtC,OAAO,CAAC,MAAM,CAAC,CAyEjB;AAcD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtD;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS1E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,EAC7B,KAAK,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAe,GACtC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAiC1B;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,MAAc,EACzB,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/containers.js

@@ -1,5 +1,39 @@
 "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.volumeArg = volumeArg;
 exports.qualifyImage = qualifyImage;
 exports.imageExists = imageExists;
 exports.getImageDigest = getImageDigest;
@@ -17,7 +51,12 @@ exports.ensureNetwork = ensureNetwork;
 exports.removeNetwork = removeNetwork;
 exports.connectToNetwork = connectToNetwork;
 exports.disconnectFromNetwork = disconnectFromNetwork;
+exports.resolveSignalkDataSource = resolveSignalkDataSource;
+exports.releaseReservedPort = releaseReservedPort;
+exports.findAvailablePort = findAvailablePort;
+exports.resolveSignalkNetworks = resolveSignalkNetworks;
 exports.waitForReady = waitForReady;
+const net = __importStar(require("net"));
 const runtime_1 = require("./runtime");
 const resources_1 = require("./resources");
 const CONTAINER_PREFIX = "sk-";
@@ -26,6 +65,27 @@ function prefixedName(name) {
         ? name
         : `${CONTAINER_PREFIX}${name}`;
 }
+/**
+ * Build the value for a `-v <source>:<dest>[:flags]` argument with the
+ * correct SELinux relabel suffix for the runtime.
+ *
+ * `:Z` is for SELinux relabelling of bind-mount host paths under Podman
+ * on Fedora/RHEL. Named volumes (no leading '/' or '.') reject `:Z` with
+ * "invalid option z for named volume", so we omit the flag for them.
+ *
+ * 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) {
+    const isNamedVolume = !hostPath.startsWith("/") && !hostPath.startsWith(".");
+    const flags = [];
+    if (readOnly)
+        flags.push("ro");
+    if (runtime.runtime === "podman" && !isNamedVolume)
+        flags.push("Z");
+    const suffix = flags.length > 0 ? `:${flags.join(",")}` : "";
+    return `${hostPath}:${containerPath}${suffix}`;
+}
 function qualifyImage(image, runtime) {
     // Podman requires fully qualified image names when unqualified-search
     // registries are not configured. Prefix docker.io/ if missing.
@@ -244,8 +304,7 @@ function buildRunArgs(name, config, runtime) {
     }
     if (config.volumes) {
         for (const [containerPath, hostPath] of Object.entries(config.volumes)) {
-            const suffix = runtime.runtime === "podman" ? ":Z" : "";
-            args.push("-v", `${hostPath}:${containerPath}${suffix}`);
+            args.push("-v", volumeArg(hostPath, containerPath, runtime));
         }
     }
     if (config.env) {
@@ -440,6 +499,180 @@ async function disconnectFromNetwork(runtime, containerName, networkName) {
         throw new Error(`Failed to disconnect ${fullName} from ${networkName}: ${result.stderr}`);
     }
 }
+/**
+ * Resolve what to mount in a managed container to give it access to
+ * the SignalK data directory, regardless of how SignalK itself is deployed.
+ *
+ * Returns the string to use as the LEFT side of a `-v <source>:<dest>` flag:
+ *   - Bare-metal SignalK: returns dataDir directly (it is already a host path).
+ *   - SignalK in Docker, volume-backed dataDir: returns the named volume.
+ *   - SignalK in Docker, bind-backed dataDir: returns the exact host path
+ *     (computing the subpath when a parent directory is bind-mounted).
+ *   - Fallback (mount not found): returns dataDir — the caller's `-v` will
+ *     fail gracefully at container-create time with a clear Docker error.
+ *
+ * The result can be used directly as `volumes: { [mountPoint]: source }` in
+ * 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)()) {
+        // Running bare-metal: dataDir is already a host filesystem path.
+        return dataDir;
+    }
+    // Running inside a container. Docker/Podman set HOSTNAME to the
+    // (short) container ID, which is enough for `inspect`.
+    const selfId = process.env.HOSTNAME ?? "";
+    if (!selfId) {
+        debug(`resolveSignalkDataSource: HOSTNAME unset, falling back to dataDir=${dataDir}`);
+        return dataDir;
+    }
+    const result = await (0, runtime_1.execRuntime)(runtime, [
+        "inspect",
+        "--format",
+        "{{range .Mounts}}{{.Type}}|{{.Name}}|{{.Source}}|{{.Destination}}\n{{end}}",
+        selfId,
+    ]);
+    if (result.exitCode !== 0) {
+        debug(`resolveSignalkDataSource: inspect ${selfId} failed (exit=${result.exitCode}): ${result.stderr.trim()}; falling back to dataDir=${dataDir}`);
+        return dataDir;
+    }
+    const mounts = result.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const [type, name, source, dest] = line.split("|");
+        return { type, name, source, dest };
+    });
+    // Find the mount whose Destination is the longest prefix of dataDir
+    // (handles both exact matches and parent-directory bind mounts).
+    let best = null;
+    for (const m of mounts) {
+        if (dataDir === m.dest || dataDir.startsWith(m.dest + "/")) {
+            if (!best || m.dest.length > best.dest.length) {
+                best = m;
+            }
+        }
+    }
+    if (!best) {
+        debug(`resolveSignalkDataSource: no mount covers dataDir=${dataDir}; mounts=${JSON.stringify(mounts)}; falling back to dataDir`);
+        return dataDir;
+    }
+    if (best.type === "volume") {
+        // Named volume. Docker doesn't support subpath mounts on volumes,
+        // so we return the volume name as-is. The consumer's mount point
+        // will correspond to best.dest; if that equals dataDir (the common
+        // case) the consumer can use mountPoint directly. If best.dest is a
+        // parent of dataDir, the consumer must append the relative suffix —
+        // signalk-container surfaces this via ContainerManagerApi if needed.
+        return best.name;
+    }
+    // Bind mount. Compute the exact host path that corresponds to dataDir,
+    // even when the bind covers a parent directory.
+    return best.source + dataDir.slice(best.dest.length);
+}
+/**
+ * Process-local set of ports that are currently reserved by an in-flight
+ * `findAvailablePort()` call.  Prevents two concurrent `ensureRunning()`
+ * calls from probing and claiming the same host port before either
+ * container has actually been created.
+ *
+ * Ports are added here just before `findAvailablePort()` resolves and
+ * removed via `releaseReservedPort()` once the container runtime holds the
+ * binding (successful create) or the attempt fails.
+ */
+const reservedPorts = new Set();
+/**
+ * Release a port that was reserved by `findAvailablePort()`.
+ * Must be called after the container runtime has successfully bound the port
+ * (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) {
+    reservedPorts.delete(port);
+}
+/**
+ * Test whether `port` is bindable on 127.0.0.1.
+ * Returns `true` if the socket can be opened and closed without error.
+ */
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => server.close(() => resolve(true)));
+        server.listen(port, "127.0.0.1");
+    });
+}
+/**
+ * Find the lowest available TCP port on 127.0.0.1 starting at `preferred`.
+ *
+ * Probes by briefly binding a server socket and also skips ports that are
+ * already reserved in-process by a concurrent `findAvailablePort()` call,
+ * eliminating the TOCTOU window between the probe and the container create.
+ *
+ * The chosen port is added to the process-local `reservedPorts` set before
+ * this function resolves.  The caller is responsible for releasing it via
+ * `releaseReservedPort()` once the runtime holds the binding or the attempt
+ * fails.
+ *
+ * Used by the `signalkAccessiblePorts` bare-metal path to prefer the
+ * declared port number while gracefully stepping over conflicts.
+ */
+async function findAvailablePort(preferred) {
+    for (let port = preferred; port <= 65535; port++) {
+        if (reservedPorts.has(port))
+            continue;
+        if (await isPortAvailable(port)) {
+            reservedPorts.add(port);
+            return port;
+        }
+    }
+    throw new Error("No available port found in range 1024–65535");
+}
+/**
+ * Return the user-defined Docker/Podman networks that the current SignalK
+ * container is connected to (i.e. networks other than the default `bridge`,
+ * `host`, or `none`).
+ *
+ * Used by the `signalkAccessiblePorts` containerized path to attach a
+ * managed container to SignalK's own network so the two can communicate
+ * via DNS name without exposing any host port.
+ *
+ * Returns:
+ *   - `null`    when running bare-metal, HOSTNAME is unset, or `docker inspect`
+ *               fails (e.g. host-network mode where HOSTNAME is the machine
+ *               name, not a container ID).  Callers should treat this like
+ *               bare-metal and publish ports instead.
+ *   - `string[]` (possibly empty) when inspect succeeds.  An empty array means
+ *               SignalK is only on the default bridge — callers should fall
+ *               back to `networkMode: container:<HOSTNAME>`.  A non-empty
+ *               array contains the user-defined network names to attach to.
+ */
+async function resolveSignalkNetworks(runtime, debug = () => { }) {
+    if (!(0, runtime_1.isContainerized)())
+        return null;
+    const selfId = process.env.HOSTNAME ?? "";
+    if (!selfId) {
+        debug("resolveSignalkNetworks: HOSTNAME unset, returning null");
+        return null;
+    }
+    const result = await (0, runtime_1.execRuntime)(runtime, [
+        "inspect",
+        "--format",
+        "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}\n{{end}}",
+        selfId,
+    ]);
+    if (result.exitCode !== 0) {
+        debug(`resolveSignalkNetworks: inspect ${selfId} failed (exit=${result.exitCode}): ${result.stderr.trim()} — treating as bare-metal`);
+        return null;
+    }
+    const all = result.stdout.split("\n").filter(Boolean);
+    // The default bridge network does not support container-name DNS
+    // resolution, so exclude it along with the virtual modes.
+    const userDefined = all.filter((n) => n !== "bridge" && n !== "host" && n !== "none");
+    debug(`resolveSignalkNetworks: all=${all.join(",")} userDefined=${userDefined.join(",")}`);
+    return userDefined;
+}
 async function waitForReady(url, timeoutMs = 30000, intervalMs = 500) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {