slskd: scaffold reverse-proxy sidecar

Add officer-slskd, a singleton sidecar that reverse-proxies to a self-hosted slskd (Soulseek) instance and reports its loopback port to the API on connect. All slskd knowledge (URL + API key) lives in the sidecar; the platform is a thin auth+forward proxy for /api/slskd/* and holds no slskd credentials. Mirrors the officer-vault pattern. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-29 15:49:09 +00:00
parent 0325f14770
commit c023082975
7 changed files with 271 additions and 0 deletions
@@ -60,6 +60,8 @@ export type SidecarEvent =
  | { type: 'music:server'; port: number }
  // Vault — the sidecar reports where its Vaultwarden reverse-proxy HTTP/WS server is listening on connect
  | { type: 'vault:server'; port: number }
+  // slskd — the sidecar reports where its slskd reverse-proxy HTTP server is listening (random port) on connect
+  | { type: 'slskd:server'; port: number }
  // Generic
  | { type: 'error'; id?: string; error: string };

@@ -0,0 +1,141 @@
+import type { SidecarCommand, SidecarEvent } from '../protocol';
+import { createSidecarConnector } from '../connect';
+import { getSlskdBase, getSlskdApiKey, stripHopByHop } from './upstream';
+
+// The officer-slskd sidecar. Same philosophy as officer-vault / officer-music: a singleton process that
+// registers with the API server and OWNS a contract — here, a reverse-proxy to a self-hosted slskd
+// (Soulseek daemon). ALL knowledge of slskd (its URL, its API key) lives here; the platform API is a
+// thin, auth-gated forwarder that never sees the slskd credential. This lets the Soulseek client grow
+// end-to-end without the main server accreting any slskd-specific logic.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// HTTP CONTRACT — the platform strips its /api/slskd mount prefix before forwarding, so requests arrive
+// here as slskd-root paths (e.g. /api/v0/searches, /api/v0/transfers, /api/v0/session). We inject
+// `X-API-Key` and pass method, path, query, headers, status and BOTH body streams through verbatim.
+// `GET /_health` is ours (probes slskd's /health), not part of the slskd contract. The server listens on
+// a random loopback port, reported to the API on connect so it can route here.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+//
+// TODO (next iteration): slskd streams live search results + transfer progress over SignalR hubs at
+// /hub/*. Add a WebSocket upgrade path here mirroring the officer-vault notifications proxy
+// (src/servers/sidecar/vault/index.ts) once the client needs real-time updates. SignalR carries its
+// credential as an `?access_token=` query param on the socket, so the key injection differs from HTTP.
+
+const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
+
+/** Grab an ephemeral free port by briefly binding one and releasing it. */
+function getFreePort(): number {
+  const probe = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') });
+  const p = probe.port;
+  probe.stop(true);
+  if (p == null) throw new Error('failed to acquire a free port');
+  return p;
+}
+
+const port = getFreePort();
+
+const server = Bun.serve({
+  port,
+  hostname: '127.0.0.1',
+  idleTimeout: 255, // browse/search can idle; Bun caps this at 255s
+  maxRequestBodySize: 1024 * 1024 * 1024, // room for uploads / large browse responses
+  async fetch(req) {
+    const url = new URL(req.url);
+    const base = getSlskdBase();
+
+    // Reachability probe — ours, not part of the slskd contract.
+    if (url.pathname === '/_health') {
+      if (!base) return Response.json({ ok: false, error: 'SLSKD_URL not configured' }, { status: 503 });
+      const started = Date.now();
+      try {
+        const r = await fetch(`${base}/health`, { method: 'GET', signal: AbortSignal.timeout(5000) });
+        return Response.json({ ok: r.ok, upstreamStatus: r.status, ms: Date.now() - started });
+      } catch {
+        return Response.json({ ok: false, error: 'upstream unreachable', ms: Date.now() - started }, { status: 502 });
+      }
+    }
+
+    if (!base) return new Response('slskd upstream not configured', { status: 503 });
+
+    const target = `${base}${url.pathname}${url.search}`;
+    const method = req.method;
+    const hasBody = method !== 'GET' && method !== 'HEAD';
+    const started = Date.now();
+
+    const headers = stripHopByHop(req.headers);
+    const apiKey = getSlskdApiKey();
+    if (apiKey) headers.set('X-API-Key', apiKey);
+
+    // Bun/undici require half-duplex to stream a request body straight through.
+    const init: RequestInit & { duplex?: 'half' } = {
+      method,
+      headers,
+      body: hasBody ? req.body : undefined,
+      redirect: 'manual', // a transparent proxy passes 3xx through rather than following them
+    };
+    if (hasBody) init.duplex = 'half';
+
+    let upstream: Response;
+    try {
+      upstream = await fetch(target, init);
+    } catch {
+      console.error(`[slskd] ${method} ${url.pathname} -> upstream unreachable`);
+      return new Response('slskd upstream unreachable', { status: 502 });
+    }
+
+    console.log(`[slskd] ${method} ${url.pathname} -> ${upstream.status} ${Date.now() - started}ms`);
+    return new Response(upstream.body, { status: upstream.status, headers: stripHopByHop(upstream.headers) });
+  },
+});
+
+console.log(`[slskd] reverse-proxy listening on 127.0.0.1:${port} -> ${getSlskdBase() ?? '(SLSKD_URL unset)'}`);
+
+// ── Command handlers ──
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+// ── Connect to API server ──
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'slskd',
+  capabilities: ['slskd'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+  onConnected() {
+    // Tell the API where our proxy is listening, so it can forward /api/slskd/* here.
+    connection.send({ type: 'slskd:server', port });
+    console.log(`[slskd] reported proxy port ${port} to API`);
+  },
+});
+
+// ── Graceful shutdown ──
+
+function shutdown(signal: string) {
+  console.log(`[slskd] ${signal} received, shutting down...`);
+  try {
+    server.stop(true);
+  } catch {
+    /* already stopped */
+  }
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
@@ -0,0 +1,53 @@
+// slskd upstream config + header hygiene for the officer-slskd sidecar.
+//
+// All knowledge of the slskd instance (its URL and API key) lives in the sidecar, mirroring the
+// officer-vault philosophy: the platform API is a thin auth+forward proxy and holds NO slskd
+// credentials. The sidecar injects the API key on every forwarded request; the platform never sees it.
+
+const { SLSKD_URL, SLSKD_API_KEY } = process.env;
+
+let warnedUnset = false;
+
+/** The slskd base URL (no trailing slash), or null when unconfigured (the sidecar then 503s). */
+export function getSlskdBase(): string | null {
+  const raw = SLSKD_URL?.trim();
+  if (!raw) {
+    if (!warnedUnset) {
+      console.warn('[slskd] SLSKD_URL is unset — the sidecar will respond 503 until it is set');
+      warnedUnset = true;
+    }
+    return null;
+  }
+  return raw.replace(/\/+$/, '');
+}
+
+/** The slskd API key, injected as `X-API-Key` on every forwarded request. Null when unconfigured. */
+export function getSlskdApiKey(): string | null {
+  const raw = SLSKD_API_KEY?.trim();
+  return raw ? raw : null;
+}
+
+// Hop-by-hop headers must not cross a proxy hop (RFC 7230 §6.1). `host` is dropped so the outgoing
+// fetch sets the upstream authority itself; everything else — including our injected X-API-Key — passes.
+const HOP_BY_HOP = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'host',
+]);
+
+/** Copy headers, dropping only hop-by-hop / proxy-* ones. Used for both request and response directions. */
+export function stripHopByHop(src: Headers): Headers {
+  const out = new Headers();
+  src.forEach((value, key) => {
+    const k = key.toLowerCase();
+    if (HOP_BY_HOP.has(k) || k.startsWith('proxy-')) return;
+    out.set(key, value);
+  });
+  return out;
+}