ombi: reach sonarr, radarr and lidarr through the mesh

ombi keeps its Servarr connections in its own database, so the mesh has no file to write them into. A run-once step reads the three bindings and pair credentials and writes host, port, TLS, base path and key into ombi through ombi's own API - only when they differ, and nothing else ombi keeps. Until the operator accepts an app's key for this pair the mesh delivers a value it minted, which no Servarr app accepts. The step tries the key against the app first and, refused, writes nothing and fails naming the secret accept that fixes it, so the old working key in ombi is never replaced by a dead one. Declared last so its failing gates nothing else of ombi (ADR 0136), and restart-on its six inputs so it runs again when a provider moves (ADR 0099).
sonarr, radarr, lidarr: provide their API to the mesh
2026-09-30 00:39:19 +02:00 · 2026-09-30 00:39:19 +02:00 · 2026-09-30 00:25:55 +02:00 · 2026-09-29 23:50:19 +02:00 · 2026-09-29 23:38:56 +02:00
17 changed files with 656 additions and 66 deletions
@@ -94,7 +94,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
+        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
        "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
        "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
        "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
@@ -76,7 +76,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
      },
      "artifact": "runtime"
@@ -24,13 +24,6 @@ function meshConfig(file?: string): Record<string, string> {
  catch { return {}; }
 }

-/** A secret delivered as a file, trimmed; undefined when there is none, so the caller can fall back. */
-function tokenFromFile(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim() || undefined; }
-  catch { return undefined; }
-}
-
 export class InfluxDBClient {
  readonly baseUrl: string;

@@ -50,10 +43,8 @@ export class InfluxDBClient {
  static fromEnv(env: NodeJS.ProcessEnv = process.env): InfluxDBClient {
    const cfg = meshConfig(env.MESH_INFLUXDB_CONFIG_FILE);
    const url = cfg.url ?? env.MESH_INFLUXDB_URL ?? `http://127.0.0.1:${env.INFLUXDB_PORT ?? "8086"}`;
-    // The token reaches the process as a file (novox/hq ADR 0086); the environment variable stays
-    // only for a workstation running the tools by hand.
-    const token = cfg.token ?? tokenFromFile(env.MESH_INFLUXDB_TOKEN_FILE) ?? env.MESH_INFLUXDB_TOKEN;
-    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN_FILE");
+    const token = cfg.token ?? env.MESH_INFLUXDB_TOKEN;
+    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN");
    const org = cfg.org ?? env.MESH_INFLUXDB_ORG ?? "mesh";
    return new InfluxDBClient(url, token, org);
  }
@@ -13,7 +13,7 @@
      "port": 8086,
      "protocol": "tcp",
      "from": "mesh",
-      "why": "queries, writes and the web UI, over http; a name is a route grant"
+      "why": "queries and writes, over http"
    }
  ],
  "resources": [
@@ -26,45 +26,46 @@
    {
      "id": "state",
      "type": "directory",
-      "mode": "0700",
-      "place": "."
+      "path": "/var/lib/influxdb-module",
+      "mode": "0700"
+    },
+    {
+      "id": "server-env",
+      "type": "file",
+      "path": "/var/lib/influxdb-module/server.env",
+      "mode": "0600",
+      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD=${secret:admin}\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${secret:admin-token}\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
    },
    {
      "id": "data",
      "type": "directory",
+      "path": "/services/influxdb/data",
      "mode": "0700",
      "owner": "1000:1000"
    },
    {
      "id": "config",
      "type": "directory",
+      "path": "/services/influxdb/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "${dir:state}/server.env",
-      "mode": "0600",
-      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD_FILE=/run/secrets/admin\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE=/run/secrets/admin-token\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
-    },
    {
      "id": "server",
      "type": "container",
      "name": "influxdb",
      "image": "influxdb@sha256:f75e48af0598e8aec7986e991a848d19a119101a7d563a2e5db1dfaac9c45daa",
      "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/influxdb-module/server.env"
      ],
      "ports": [
        "8086"
      ],
      "volumes": [
-        "${dir:data}:/var/lib/influxdb2",
-        "${dir:config}:/etc/influxdb2",
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro"
-      ]
+        "/services/influxdb/data:/var/lib/influxdb2",
+        "/services/influxdb/config:/etc/influxdb2"
+      ],
+      "secrets-in-environment": "the image honours DOCKER_INFLUXDB_INIT_PASSWORD_FILE and _ADMIN_TOKEN_FILE; convertible, awaiting a bed that proves it"
    },
    {
      "id": "runtime-config",
@@ -82,13 +83,13 @@
      "volumes": [
        "/var/lib/mesh/influxdb/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/influxdb/config.json:/run/config/config.json:ro",
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro"
+        "/services/influxdb/config:/var/lib/influxdb/config:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
+        "MESH_INFLUXDB_URL": "http://127.0.0.1:8086",
        "MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
-        "MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token"
+        "MESH_INFLUXDB_CONFIG_DIR": "/var/lib/influxdb/config"
      },
      "restart-on": [
        "runtime-config"
@@ -96,22 +97,6 @@
      "artifact": "runtime"
    }
  ],
-  "requires": [
-    "route",
-    "secret"
-  ],
-  "contributes": {
-    "route": {
-      "label": "influxdb",
-      "endpoint": "api"
-    }
-  },
-  "secrets": {
-    "secret": {
-      "admin": "${dir:state}/admin.secret",
-      "admin-token": "${dir:state}/admin-token.secret"
-    }
-  },
  "build": {
    "on": [
      {
@@ -132,5 +117,14 @@
        "from": "Dockerfile"
      }
    ]
+  },
+  "requires": [
+    "secret"
+  ],
+  "secrets": {
+    "secret": {
+      "admin": "/var/lib/influxdb-module/admin.secret",
+      "admin-token": "/var/lib/influxdb-module/admin-token.secret"
+    }
  }
 }
@@ -1,6 +1,19 @@
 {
  "module": "lidarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "lidarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "lidarr-api": {
+      "scheme": "http",
+      "port": 8686,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -75,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
+        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
        "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
      },
      "artifact": "runtime"
@@ -81,7 +81,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
+        "MESH_NZBGET_URL": "http://127.0.0.1:${port:6789}",
        "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
        "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
        "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"
@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/ombi
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts \
      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist

 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/ombi/dist /app/modules/ombi/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/ombi/dist/index.js,/app/modules/ombi/dist/tools/index.js
+# NOT dist/servarr/index.js: that is a step the host runs to completion, named by the `servarr`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.
@@ -28,10 +28,15 @@
      "path": "/var/lib/mesh/ombi",
      "mode": "0700"
    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
    {
      "id": "config",
      "type": "directory",
-      "path": "/services/ombi/config",
      "mode": "0700",
      "owner": "1000:1000"
    },
@@ -39,7 +44,7 @@
      "id": "server",
      "type": "container",
      "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
+      "image": "lscr.io/linuxserver/ombi@sha256:22d6ebadbaaa728571353e74dc2173719e0fb02d4eaec551a7e9d2ee99ef68ac",
      "env": {
        "PUID": "1000",
        "PGID": "1000",
@@ -49,7 +54,7 @@
        "3579"
      ],
      "volumes": [
-        "/services/ombi/config:/config"
+        "${dir:config}:/config"
      ]
    },
    {
@@ -68,24 +73,59 @@
      "volumes": [
        "/var/lib/mesh/ombi/broker:/run/secrets/broker:ro",
        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
-        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro",
-        "/services/ombi/config:/var/lib/ombi/config:ro"
+        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro"
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_OMBI_URL": "http://127.0.0.1:3579",
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json",
-        "MESH_OMBI_CONFIG_DIR": "/var/lib/ombi/config"
+        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
        "runtime-config"
      ],
      "artifact": "runtime"
+    },
+    {
+      "id": "servarr",
+      "type": "container",
+      "name": "mesh-ombi-servarr",
+      "network": "host",
+      "run-once": true,
+      "volumes": [
+        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
+        "${dir:state}/sonarr-api.json:/run/servarr/sonarr-api.json:ro",
+        "${dir:state}/sonarr-api.secret:/run/servarr/sonarr-api.secret:ro",
+        "${dir:state}/radarr-api.json:/run/servarr/radarr-api.json:ro",
+        "${dir:state}/radarr-api.secret:/run/servarr/radarr-api.secret:ro",
+        "${dir:state}/lidarr-api.json:/run/servarr/lidarr-api.json:ro",
+        "${dir:state}/lidarr-api.secret:/run/servarr/lidarr-api.secret:ro"
+      ],
+      "env": {
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
+        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
+        "MESH_SERVARR_DIR": "/run/servarr"
+      },
+      "args": [
+        "run",
+        "/app/modules/ombi/dist/servarr/index.js"
+      ],
+      "restart-on": [
+        "bound-sonarr-api",
+        "secret-sonarr-api",
+        "bound-radarr-api",
+        "secret-radarr-api",
+        "bound-lidarr-api",
+        "secret-lidarr-api"
+      ],
+      "artifact": "runtime"
    }
  ],
  "requires": [
-    "route"
+    "lidarr-api",
+    "radarr-api",
+    "route",
+    "sonarr-api"
  ],
  "contributes": {
    "route": {
@@ -94,7 +134,15 @@
    }
  },
  "binds": {
-    "route": "/var/lib/mesh/ombi/route.json"
+    "route": "${dir:state}/route.json",
+    "sonarr-api": "${dir:state}/sonarr-api.json",
+    "radarr-api": "${dir:state}/radarr-api.json",
+    "lidarr-api": "${dir:state}/lidarr-api.json"
+  },
+  "secrets": {
+    "sonarr-api": "${dir:state}/sonarr-api.secret",
+    "radarr-api": "${dir:state}/radarr-api.secret",
+    "lidarr-api": "${dir:state}/lidarr-api.secret"
  },
  "build": {
    "on": [
@@ -4,6 +4,11 @@
  "description": "ombi — media requests. Its API client, tools and events live here (novox/hq ADR 0039).",
  "type": "module",
  "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
  "dependencies": {
    "@novox/mesh-sdk": "^0.1.0"
  },
@@ -0,0 +1,59 @@
+// ombi's Servarr step — run once by the host after ombi's server starts, and run again whenever a
+// binding or pair credential it reads changes (the container's `restart-on`, novox/hq ADR 0099).
+//
+// **A step, not a loop**, for the reason route-adapter gives: everything it does is a function of
+// files the mesh writes, and the host already knows when they change. It connects to no broker.
+//
+// Exits non-zero when any app could not be put right — a refused credential, an unreachable app, an
+// ombi that cannot reach it — so the node reports the step failed and the host runs it again on the
+// next apply. It is declared last in the manifest, so its failing gates nothing else of ombi's
+// (novox/hq ADR 0136).
+//
+// Reads, per app, `<dir>/<provision>.json` (the binding) and `<dir>/<provision>.secret` (the pair
+// credential), where <dir> is MESH_SERVARR_DIR. Never prints a key.
+
+import { join } from "node:path";
+
+import { APPS, ombiReady, readBinding, readIfThere, reconcileApp, type Http } from "./settings.js";
+
+const dir = process.env.MESH_SERVARR_DIR ?? "/run/servarr";
+const url = process.env.MESH_OMBI_URL ?? "http://127.0.0.1:3579";
+const apiKey = (await readIfThere(process.env.MESH_OMBI_API_KEY_FILE))?.trim() ?? process.env.MESH_OMBI_API_KEY ?? "";
+const waitSeconds = Number(process.env.MESH_OMBI_WAIT_SECONDS ?? "180");
+
+const http: Http = { fetch: (u, init) => fetch(u, init) };
+
+if (!apiKey) {
+  console.error("[ombi-servarr] no ombi API key — ombi's own `api-key` secret has not been accepted");
+  process.exit(1);
+}
+const ombi = { url, apiKey };
+
+if (!(await ombiReady(http, ombi, waitSeconds * 1000))) {
+  console.error(`[ombi-servarr] ombi did not answer at ${url} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+let failed = 0;
+for (const spec of APPS) {
+  const outcome = await reconcileApp(
+    http,
+    ombi,
+    spec,
+    await readBinding(join(dir, `${spec.provision}.json`)),
+    await readIfThere(join(dir, `${spec.provision}.secret`)),
+  );
+  switch (outcome.result) {
+    case "unchanged":
+      console.log(`[ombi-servarr] ${outcome.app}: already as the mesh says; connection tested`);
+      break;
+    case "written":
+      console.log(`[ombi-servarr] ${outcome.app}: wrote ${outcome.fields.join(", ")}; connection tested`);
+      break;
+    case "refused":
+      failed++;
+      console.error(`[ombi-servarr] ${outcome.app}: ${outcome.problem}`);
+      break;
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;
@@ -0,0 +1,304 @@
+// Where ombi reaches Sonarr, Radarr and Lidarr — decided by the mesh, written into ombi by ombi's
+// own API.
+//
+// **Why this exists.** ombi keeps its connection to each Servarr app in its own database
+// (OmbiSettings.db), not in a file, so the mesh has nowhere to write `${bound:sonarr-api:at}` for it.
+// ombi requires `sonarr-api`, `radarr-api` and `lidarr-api`; the mesh delivers, for each, a binding
+// (where the app is: `at`, and what it serves: `port`, `scheme`, `url-base`) and a pair credential
+// (the app's API key, accepted by the operator — a Servarr app has exactly one key and the mesh
+// cannot mint it). This step reads those files and makes ombi's settings say the same thing.
+//
+// **Only the connection, and only when it differs.** Host, port, TLS, base path and API key. The
+// quality profile, root folder, language profile, tags, "enabled" and every other choice an operator
+// made in ombi's settings screen are left exactly as they are: the mesh knows where the app is, not
+// what ombi should do with it. Radarr's 4K instance is a different Radarr and is not touched.
+//
+// **A credential the app refuses is never written.** Until the operator accepts the app's API key
+// for this pair, the mesh delivers a value it minted itself, which no Servarr app will ever accept
+// (novox/hq ADR 0092). Writing it would replace a working key in ombi with a dead one. So the key is
+// tried against the app first; refused, nothing for that app is written and the step fails naming
+// the `secret accept` that fixes it.
+//
+// Pure logic and a small HTTP seam, so it is tested against fake servers (test/servarr.test.ts).
+
+import { readFile } from "node:fs/promises";
+
+/** One Servarr app ombi connects to, and the shape of that connection in ombi's API. */
+export interface ServarrApp {
+  /** The app, as ombi's API names it: /Settings/<app>, /Tester/<app>. */
+  app: "sonarr" | "radarr" | "lidarr";
+  /** The provision it is required as — the manifest's `requires`, `binds` and `secrets` key. */
+  provision: string;
+  /** The app's own status endpoint, which answers 401 to a wrong key. */
+  statusPath: string;
+  /**
+   * Where the one connection sits in ombi's settings document. Radarr's is `{radarr, radarr4K}`
+   * (two Radarr instances); only `radarr` is this provision's.
+   */
+  within?: string;
+}
+
+export const APPS: readonly ServarrApp[] = [
+  { app: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
+  { app: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status", within: "radarr" },
+  { app: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
+];
+
+/** The connection fields ombi keeps for an app — the only ones this step ever writes. */
+export interface Connection {
+  ip: string;
+  port: number;
+  ssl: boolean;
+  /** ombi's name for the app's URL base; null when the app is served at the root. */
+  subDir: string | null;
+  apiKey: string;
+}
+
+/** What the mesh wrote at `binds.<provision>`: the binding document (controller's boundFile). */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+export type Wanted = { ok: true; connection: Connection; from: string } | { ok: false; problem: string };
+
+/**
+ * The connection the mesh says ombi should use, from the binding and the pair credential.
+ *
+ * Refused rather than guessed when the binding cannot be dialled from ombi's own container: a
+ * loopback `at` — what the mesh hands a machine that is not on the private network — is ombi's
+ * container itself, not the app.
+ */
+export function wanted(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Wanted {
+  if (!binding) {
+    return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
+  }
+  const at = typeof binding.at === "string" ? binding.at.trim() : "";
+  const serves = binding.serves ?? {};
+  const port = Number(serves.port);
+  if (!at) {
+    return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
+  }
+  if (isLoopback(at)) {
+    return {
+      ok: false,
+      problem:
+        `the ${spec.provision} binding says ${spec.app} is at ${at}, which from ombi's own container is ` +
+        `ombi itself. The mesh hands loopback to a machine that is not on the private network; put it ` +
+        `on the private network so ${spec.app} has an address ombi can dial`,
+    };
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(serves.port)})` };
+  }
+  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
+  if (scheme !== "http" && scheme !== "https") {
+    return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}, which ombi cannot dial` };
+  }
+  const key = (credential ?? "").trim();
+  if (!key) {
+    return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
+  }
+  return {
+    ok: true,
+    from: typeof binding.from === "string" ? binding.from : "",
+    connection: { ip: at, port, ssl: scheme === "https", subDir: subDirOf(serves["url-base"]), apiKey: key },
+  };
+}
+
+/** ombi's `subDir`: the URL base with its slashes trimmed, null when there is none. */
+export function subDirOf(urlBase: unknown): string | null {
+  const trimmed = typeof urlBase === "string" ? urlBase.trim().replace(/^\/+|\/+$/g, "") : "";
+  return trimmed === "" ? null : trimmed;
+}
+
+function isLoopback(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
+}
+
+/** Which connection fields differ between what ombi holds and what the mesh says. Names only. */
+export function differing(current: Record<string, unknown> | undefined, want: Connection): (keyof Connection)[] {
+  const now = current ?? {};
+  const out: (keyof Connection)[] = [];
+  if (String(now.ip ?? "") !== want.ip) out.push("ip");
+  if (Number(now.port ?? 0) !== want.port) out.push("port");
+  if (Boolean(now.ssl) !== want.ssl) out.push("ssl");
+  if (subDirOf(now.subDir) !== want.subDir) out.push("subDir");
+  if (String(now.apiKey ?? "") !== want.apiKey) out.push("apiKey");
+  return out;
+}
+
+/** ombi's settings for the app with the connection laid over them and nothing else changed. */
+export function withConnection(current: Record<string, unknown> | undefined, want: Connection): Record<string, unknown> {
+  return { ...(current ?? {}), ip: want.ip, port: want.port, ssl: want.ssl, subDir: want.subDir, apiKey: want.apiKey };
+}
+
+/** The app's base URL as the step dials it — the same host and port ombi will be given. */
+export function appUrl(want: Connection): string {
+  const scheme = want.ssl ? "https" : "http";
+  const host = want.ip.includes(":") && !want.ip.startsWith("[") ? `[${want.ip}]` : want.ip;
+  return `${scheme}://${host}:${want.port}${want.subDir ? `/${want.subDir}` : ""}`;
+}
+
+/** How one app came out. */
+export type Outcome =
+  | { app: string; result: "unchanged" }
+  | { app: string; result: "written"; fields: string[] }
+  | { app: string; result: "refused"; problem: string };
+
+/** The HTTP the step needs, so a test can stand fakes in for ombi and the apps. */
+export interface Http {
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{
+    status: number;
+    text(): Promise<string>;
+  }>;
+}
+
+export interface Ombi {
+  url: string;
+  apiKey: string;
+}
+
+async function ombiCall(http: Http, ombi: Ombi, method: string, path: string, body?: unknown): Promise<unknown> {
+  const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1${path}`, {
+    method,
+    headers: {
+      ApiKey: ombi.apiKey,
+      Accept: "application/json",
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (res.status < 200 || res.status >= 300) {
+    // The body is ombi's error, never a request echo, so it carries no key.
+    throw new Error(`ombi ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+  }
+  return text ? (JSON.parse(text) as unknown) : undefined;
+}
+
+/**
+ * Does the app take this key? `true` it does, `false` it refused it (401/403), and a thrown error
+ * when it could not be asked — unreachable, or answering something that is neither.
+ */
+export async function appTakes(http: Http, spec: ServarrApp, want: Connection): Promise<boolean> {
+  const res = await http.fetch(`${appUrl(want)}${spec.statusPath}`, {
+    method: "GET",
+    headers: { "X-Api-Key": want.apiKey, Accept: "application/json" },
+  });
+  if (res.status === 401 || res.status === 403) return false;
+  if (res.status >= 200 && res.status < 300) return true;
+  throw new Error(`${spec.app} answered ${res.status} at ${spec.statusPath}`);
+}
+
+/** The remedy for a refused key, in the controller's own words (ADR 0092). */
+export function acceptRemedy(spec: ServarrApp, from: string): string {
+  return (
+    `${spec.app} refuses the ${spec.provision} credential the mesh delivered, so it was not written ` +
+    `into ombi. A Servarr app has one API key and the mesh cannot make it: accept ${spec.app}'s own ` +
+    `key for this pair — \`secret accept <this node> ombi ${spec.provision} --provider ${from || "<its node>"} ` +
+    `--from <file holding ${spec.app}'s ApiKey>\``
+  );
+}
+
+/**
+ * Bring ombi's connection to one app in line with the mesh: check the key against the app, compare,
+ * write only the connection fields when they differ, then have ombi test the connection from its own
+ * container. Never throws: every failure is an outcome with a reason.
+ */
+export async function reconcileApp(
+  http: Http,
+  ombi: Ombi,
+  spec: ServarrApp,
+  binding: Binding | undefined,
+  credential: string | undefined,
+): Promise<Outcome> {
+  const w = wanted(spec, binding, credential);
+  // `in`, not `!w.ok`: the Dockerfile compiles without strict, where a boolean discriminant does not
+  // narrow.
+  if ("problem" in w) return { app: spec.app, result: "refused", problem: w.problem };
+  const want = w.connection;
+
+  try {
+    if (!(await appTakes(http, spec, want))) {
+      return { app: spec.app, result: "refused", problem: acceptRemedy(spec, w.from) };
+    }
+  } catch (err) {
+    return {
+      app: spec.app,
+      result: "refused",
+      problem: `${spec.app} could not be asked whether it takes the key at ${want.ip}:${want.port}: ${message(err)}`,
+    };
+  }
+
+  try {
+    const document = (await ombiCall(http, ombi, "GET", `/Settings/${spec.app}`)) as Record<string, unknown> | undefined;
+    const current = spec.within ? (document?.[spec.within] as Record<string, unknown> | undefined) : document;
+    const fields = differing(current, want);
+    if (fields.length > 0) {
+      const next = withConnection(current, want);
+      const body = spec.within ? { ...(document ?? {}), [spec.within]: next } : next;
+      const saved = await ombiCall(http, ombi, "POST", `/Settings/${spec.app}`, body);
+      if (saved === false) {
+        return { app: spec.app, result: "refused", problem: `ombi declined to save its ${spec.app} settings` };
+      }
+    }
+    // ombi's own test, from ombi's own container — the path the step's check above did not take.
+    const tested = (await ombiCall(http, ombi, "POST", `/Tester/${spec.app}`, withConnection(current, want))) as
+      | { isValid?: boolean; expectedSubDir?: string | null }
+      | undefined;
+    if (!tested?.isValid) {
+      const hint = tested?.expectedSubDir ? ` (ombi expected the base path ${tested.expectedSubDir})` : "";
+      return {
+        app: spec.app,
+        result: "refused",
+        problem:
+          `ombi cannot reach ${spec.app} at ${want.ip}:${want.port} from its own container${hint}` +
+          (fields.length > 0 ? `; its settings were written (${fields.join(", ")})` : ""),
+      };
+    }
+    return fields.length > 0 ? { app: spec.app, result: "written", fields } : { app: spec.app, result: "unchanged" };
+  } catch (err) {
+    return { app: spec.app, result: "refused", problem: message(err) };
+  }
+}
+
+/** Wait for ombi to answer, because the step runs right after its container starts. */
+export async function ombiReady(http: Http, ombi: Ombi, waitMs: number, pauseMs = 2000): Promise<boolean> {
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1/Status`, { method: "GET" });
+      if (res.status === 200) return true;
+    } catch {
+      // not listening yet
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, pauseMs));
+  }
+}
+
+/** A file the mesh wrote, or undefined when it is not there. */
+export async function readIfThere(path: string | undefined): Promise<string | undefined> {
+  if (!path) return undefined;
+  return readFile(path, "utf8").catch(() => undefined);
+}
+
+/** A binding file parsed, or undefined when absent or not JSON. */
+export async function readBinding(path: string | undefined): Promise<Binding | undefined> {
+  const raw = await readIfThere(path);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as Binding;
+  } catch {
+    return undefined;
+  }
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
@@ -0,0 +1,147 @@
+// What holds ombi's Servarr step (servarr/settings.ts): the connection ombi keeps for each app is
+// made to say what the mesh bound — host, port, TLS, base path, key — and nothing else it keeps is
+// touched; nothing is written when nothing differs; Radarr's 4K instance is left alone; and a key the
+// app refuses (the mesh's own minted value, before the operator accepts the app's key) is never
+// written, with the `secret accept` that fixes it named.
+//
+// ombi and the apps are fakes: the routes the step touches, answering as the real ones do (checked
+// against lscr.io/linuxserver/ombi 4.53.10 and the catalogue's pinned sonarr/radarr/lidarr).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { APPS, differing, reconcileApp, subDirOf, wanted, type Binding, type Http, type ServarrApp } from "../servarr/settings.ts";
+
+const SONARR = APPS.find((a) => a.app === "sonarr") as ServarrApp;
+const RADARR = APPS.find((a) => a.app === "radarr") as ServarrApp;
+const LIDARR = APPS.find((a) => a.app === "lidarr") as ServarrApp;
+const THE_KEY = "the-apps-own-key";
+
+function binding(provision: string, port: number, at = "ace.internal"): Binding {
+  return { binding: 1, provision, from: "ace", at, as: "mesh_ace_ombi", serves: { scheme: "http", port, "url-base": "" } } as Binding;
+}
+
+interface Call {
+  method: string;
+  url: string;
+  body?: unknown;
+}
+
+/** ombi's settings store and the apps' key check, behind one fetch. */
+function fakes(settings: Record<string, unknown>, opts: { appKey?: string; reachable?: boolean } = {}) {
+  const calls: Call[] = [];
+  const appKey = opts.appKey ?? THE_KEY;
+  const http: Http = {
+    async fetch(url, init) {
+      const method = init?.method ?? "GET";
+      const body = init?.body ? (JSON.parse(init.body) as unknown) : undefined;
+      calls.push({ method, url, body });
+      const reply = (status: number, value?: unknown) => ({
+        status,
+        text: async () => (value === undefined ? "" : JSON.stringify(value)),
+      });
+      const u = new URL(url);
+      if (u.pathname.endsWith("/system/status")) {
+        if (opts.reachable === false) throw new Error("connect ECONNREFUSED");
+        return init?.headers?.["X-Api-Key"] === appKey ? reply(200, { version: "4" }) : reply(401);
+      }
+      if (init?.headers?.ApiKey !== "ombi-key") return reply(401);
+      const m = u.pathname.match(/^\/api\/v1\/(Settings|Tester)\/(\w+)$/);
+      if (!m) return reply(404);
+      const [, kind, app] = m;
+      if (kind === "Settings" && method === "GET") return reply(200, settings[app]);
+      if (kind === "Settings" && method === "POST") {
+        settings[app] = body;
+        return reply(200, true);
+      }
+      const tried = body as { apiKey?: string };
+      return reply(200, { isValid: tried.apiKey === appKey, expectedSubDir: null });
+    },
+  };
+  return { http, calls, settings };
+}
+
+const OMBI = { url: "http://127.0.0.1:3579", apiKey: "ombi-key" };
+
+const operatorSonarr = () => ({
+  enabled: true, apiKey: "old-key", qualityProfile: "3", seasonFolders: true, rootPath: "10",
+  qualityProfileAnime: "7", rootPathAnime: "9", languageProfile: 1, ssl: false, subDir: null,
+  ip: "sonarr", port: 8989, id: 5,
+});
+
+test("it writes the connection the mesh bound, and keeps every other setting ombi had", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), `${THE_KEY}\n`);
+  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["ip", "port", "apiKey"] });
+  assert.deepEqual(f.settings.sonarr, {
+    ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY, ssl: false, subDir: null,
+  });
+  // Checked against the app itself, at the bound address, before anything was written.
+  assert.equal(f.calls[0].url, "http://ace.internal:20101/api/v3/system/status");
+});
+
+test("nothing is written when ombi already says what the mesh says", async () => {
+  const f = fakes({ sonarr: { ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY } });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.deepEqual(out, { app: "sonarr", result: "unchanged" });
+  assert.equal(f.calls.filter((c) => c.method === "POST" && c.url.includes("/Settings/")).length, 0);
+});
+
+test("a key the app refuses is never written, and the accept that fixes it is named", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), "a-value-the-mesh-minted");
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /secret accept <this node> ombi sonarr-api --provider ace/);
+  assert.doesNotMatch((out as { problem: string }).problem, /a-value-the-mesh-minted/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr(), "ombi's working settings were left alone");
+  assert.equal(f.calls.some((c) => c.url.includes("/api/v1/")), false, "ombi was not even asked");
+});
+
+test("an app it cannot reach is reported, and ombi is left alone", async () => {
+  const f = fakes({ sonarr: operatorSonarr() }, { reachable: false });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /could not be asked.*ECONNREFUSED/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr());
+});
+
+test("radarr's connection is written inside its combined document, and the 4K instance is untouched", async () => {
+  const fourK = { enabled: true, apiKey: "4k-key", ip: "radarr4k", port: 7879, defaultQualityProfile: "9", id: 7 };
+  const f = fakes({ radarr: { radarr: { enabled: true, apiKey: "old", ip: "radarr", port: 7878, defaultRootPath: "/movies", id: 6 }, radarr4K: fourK } });
+  const out = await reconcileApp(f.http, OMBI, RADARR, binding("radarr-api", 20102), THE_KEY);
+  assert.equal(out.result, "written");
+  const doc = f.settings.radarr as { radarr: Record<string, unknown>; radarr4K: unknown };
+  assert.deepEqual(doc.radarr4K, fourK);
+  assert.equal(doc.radarr.ip, "ace.internal");
+  assert.equal(doc.radarr.port, 20102);
+  assert.equal(doc.radarr.defaultRootPath, "/movies");
+});
+
+test("lidarr is checked on its own API version", async () => {
+  const f = fakes({ lidarr: { enabled: true, apiKey: null, ip: null, port: 0, id: 0 } });
+  const out = await reconcileApp(f.http, OMBI, LIDARR, binding("lidarr-api", 20103), THE_KEY);
+  assert.equal(out.result, "written");
+  assert.equal(f.calls[0].url, "http://ace.internal:20103/api/v1/system/status");
+});
+
+test("a loopback binding is refused: from ombi's container it is ombi itself", () => {
+  const w = wanted(SONARR, binding("sonarr-api", 20101, "127.0.0.1"), THE_KEY);
+  assert.equal(w.ok, false);
+  assert.match((w as { problem: string }).problem, /private network/);
+});
+
+test("the base path is ombi's subDir, slashes trimmed; empty is none", () => {
+  assert.equal(subDirOf(""), null);
+  assert.equal(subDirOf("/sonarr/"), "sonarr");
+  assert.deepEqual(
+    differing({ ip: "h", port: 1, ssl: false, subDir: "", apiKey: "k" }, { ip: "h", port: 1, ssl: false, subDir: null, apiKey: "k" }),
+    [],
+  );
+});
+
+test("an https binding sets ombi's ssl flag", () => {
+  const b = binding("sonarr-api", 443);
+  (b.serves as Record<string, unknown>).scheme = "https";
+  const w = wanted(SONARR, b, THE_KEY);
+  assert.equal(w.ok && w.connection.ssl, true);
+});
@@ -8,5 +8,5 @@
    "skipLibCheck": true,
    "noEmit": true
  },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts", "servarr/settings.ts", "servarr/index.ts"]
 }
@@ -82,7 +82,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8080}",
        "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
        "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
        "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"
@@ -1,6 +1,19 @@
 {
  "module": "radarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "radarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "radarr-api": {
+      "scheme": "http",
+      "port": 7878,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -75,7 +88,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:7878",
+        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
        "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
      },
      "artifact": "runtime"
@@ -100,7 +100,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
        "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
      },
      "restart-on": [
@@ -1,6 +1,19 @@
 {
  "module": "sonarr",
  "version": "1",
+  "provides": [
+    {
+      "name": "sonarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "sonarr-api": {
+      "scheme": "http",
+      "port": 8989,
+      "url-base": ""
+    }
+  },
  "capabilities": [
    "container-runtime"
  ],
@@ -80,7 +93,7 @@
      ],
      "env": {
        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:8989",
+        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
        "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
      },
      "artifact": "runtime"
Author	SHA1	Message	Date
jschoubben	f14c763463	ombi: reach sonarr, radarr and lidarr through the mesh ombi keeps its Servarr connections in its own database, so the mesh has no file to write them into. A run-once step reads the three bindings and pair credentials and writes host, port, TLS, base path and key into ombi through ombi's own API - only when they differ, and nothing else ombi keeps. Until the operator accepts an app's key for this pair the mesh delivers a value it minted, which no Servarr app accepts. The step tries the key against the app first and, refused, writes nothing and fails naming the secret accept that fixes it, so the old working key in ombi is never replaced by a dead one. Declared last so its failing gates nothing else of ombi (ADR 0136), and restart-on its six inputs so it runs again when a provider moves (ADR 0099).	2026-09-30 00:39:19 +02:00
jschoubben	ab44ff02e1	sonarr, radarr, lidarr: provide their API to the mesh A consumer on another machine (ombi first; jackett, bazarr and home-assistant later) reached these by container name on HAL's shared network, which the mesh does not have. Each app now provides <app>-api at mesh scope and serves the software port, so the mesh tells a consumer where it is and redirects the port to where the machine published it. Named per app, not one servarr-api: a requirement is matched by name and answered by exactly one provider per node, so a consumer cannot require one name from three providers - and ombi's code is written against each app's own API version (ADR 0027). No grants and no provisioner: a Servarr instance has one API key, which the mesh cannot mint. The operator accepts it as the pair credential for each consumer (ADR 0092).	2026-09-30 00:39:19 +02:00
jschoubben	c4c44efb1b	Merge remote-tracking branch 'origin/fix/sidecars-dial-the-port-they-were-given' into feat/servarr-api-provision	2026-09-30 00:25:55 +02:00
jschoubben	5cc6258326	Sidecars dial the port they were given, not the software's A host-network sidecar reaches its service over the machine's loopback, and the mesh publishes that service on a machine port it assigns (ADR 0038) — so dialling the software's port reaches whatever else holds it. On ace, searxng's sidecar dialled 127.0.0.1:8080 and got unifi's inform port. The same shape in bazarr, bookshelf, lidarr, nzbget, qbittorrent, radarr and sonarr; each now asks with ${port:N} (hq 088). Found in review of ace's module preparation.	2026-09-29 23:50:19 +02:00
jschoubben	21f5301268	ombi: its config is placed, its image is the one ace runs ombi's definition named /services/ombi/config (a HAL machine path) in three places and pinned an image older than the one ace runs. Ombi migrates its own SQLite schema, so a take onto the older pin (v4.53.10-ls267) would start it on a database the newer build (ls269) already touched. - config is a pathless placed directory, mounted as ${dir:config} - a state directory placed at the assignment root carries route.json - image pinned to the digest ace runs today (v4.53.10-ls269) - the sidecar reaches ombi on the machine port the mesh assigns (${port:3579}) rather than assuming 3579 is free - the sidecar no longer mounts ombi's data directory: MESH_OMBI_CONFIG_DIR is read by no code, and the mount exposed the databases for nothing Verified: catalogue tests (MESH_CATALOGUE set, 6 pass, none skipped); the pinned image starts as PUID 1000 in a 0700 dir and answers /api/v1/Status 200; data owned 1001:2000 (ace's media ids) under a 1000:1000 dir is re-owned by the image's init and serves 200; a minted ApiKey is refused (401) - the api-key secret must be accepted from ombi's own settings.	2026-09-29 23:38:56 +02:00