searxng, icecast, photos: full nox modules (ADR 0044/0046)

searxng: a search tool — tools-only, a stateless search has nothing to observe. icecast: status tool, emits stream.started/.stopped by diffing live mountpoints. photos: status/albums/recent tools, emits item.added (immich-shaped API, coded defensively since the stub ships a placeholder image — flagged in the code). Typecheck; manifests parse.
2026-09-04 02:46:24 +02:00
parent 81dc74734b
commit 8f8e0153b1
16 changed files with 548 additions and 1 deletions
@@ -0,0 +1,87 @@
+// Icecast's API client — icecast's own code, living in the module (novox/hq ADR 0044). Icecast is an
+// audio streaming server: sources push mountpoints in, listeners pull them out. Its `/status-json.xsl`
+// endpoint reports the live mountpoints and their listener counts — the one thing worth watching, and
+// the basis for both the status tool and the stream started/stopped events.
+
+export interface IcecastMount {
+  /** The mountpoint path, e.g. "/stream.mp3", derived from the source's listen URL. */
+  mount: string;
+  listeners: number;
+  name?: string;
+  description?: string;
+  streamStart?: string;
+  bitrate?: number;
+  serverType?: string;
+}
+
+export interface IcecastStatus {
+  mounts: IcecastMount[];
+  totalListeners: number;
+  mountCount: number;
+}
+
+// The raw shape of one <source> in status-json.xsl. `source` is absent with no mounts, a lone object
+// with one, and an array with several — normalised below.
+interface RawSource {
+  listenurl?: string;
+  listeners?: number;
+  server_name?: string;
+  server_description?: string;
+  stream_start_iso8601?: string;
+  stream_start?: string;
+  bitrate?: number;
+  server_type?: string;
+}
+
+export class IcecastClient {
+  readonly baseUrl: string;
+  private readonly authHeader?: string;
+
+  constructor(url: string, adminUser?: string, adminPassword?: string) {
+    this.baseUrl = url.replace(/\/$/, "");
+    // status-json.xsl is public on most instances; basic auth is used only where admin locked it down.
+    if (adminUser && adminPassword) {
+      this.authHeader = "Basic " + Buffer.from(`${adminUser}:${adminPassword}`).toString("base64");
+    }
+  }
+
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): IcecastClient {
+    const url = env.MESH_ICECAST_URL ?? `http://127.0.0.1:${env.ICECAST_PORT ?? "8000"}`;
+    return new IcecastClient(url, env.MESH_ICECAST_ADMIN_USER, env.MESH_ICECAST_ADMIN_PASSWORD);
+  }
+
+  async getStatus(): Promise<IcecastStatus> {
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (this.authHeader) headers.Authorization = this.authHeader;
+    const res = await fetch(`${this.baseUrl}/status-json.xsl`, { headers });
+    if (!res.ok) throw new Error(`Icecast status: ${res.status} ${await res.text()}`);
+    const data = (await res.json()) as { icestats?: { source?: RawSource | RawSource[] } };
+
+    const raw = data.icestats?.source;
+    const sources: RawSource[] = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
+    const mounts = sources.map((s) => ({
+      mount: this.mountFromUrl(s.listenurl),
+      listeners: s.listeners ?? 0,
+      name: s.server_name,
+      description: s.server_description,
+      streamStart: s.stream_start_iso8601 ?? s.stream_start,
+      bitrate: s.bitrate,
+      serverType: s.server_type,
+    }));
+    return {
+      mounts,
+      totalListeners: mounts.reduce((n, m) => n + m.listeners, 0),
+      mountCount: mounts.length,
+    };
+  }
+
+  /** Icecast names the mount only inside the listen URL's path; pull it back out (fall back to raw). */
+  private mountFromUrl(listenurl?: string): string {
+    if (!listenurl) return "unknown";
+    try {
+      return new URL(listenurl).pathname;
+    } catch {
+      return listenurl;
+    }
+  }
+}