bunqueue-dashboard 0.0.14

package/agent/manager.ts

@@ -0,0 +1,262 @@
+/**
+ * ProcessManager — supervises a bunqueue server child process so the dashboard
+ * can start / stop / restart it. Runs under Bun (uses Bun.spawn).
+ *
+ * It does NOT import or touch bunqueue source — it just launches a configurable
+ * command (default `bunqueue start`) with the ports/data-path passed as env.
+ */
+
+export type Status = 'running' | 'stopped' | 'starting' | 'stopping';
+
+export interface ServerConfig {
+  /** Command to launch the server, e.g. "bunqueue start" or "bun run src/main.ts". */
+  command: string;
+  httpPort: number;
+  tcpPort: number;
+  dataPath: string;
+  extraEnv: Record<string, string>;
+}
+
+export interface LogLine {
+  seq: number;
+  ts: number;
+  stream: 'stdout' | 'stderr' | 'sys';
+  line: string;
+}
+
+/** On-disk footprint of the configured SQLite database (main + WAL + SHM). */
+export interface DbStats {
+  path: string;
+  exists: boolean;
+  size: number;
+  walSize: number;
+  shmSize: number;
+  totalSize: number;
+  mtimeMs: number | null;
+}
+
+export interface StatusSnapshot {
+  status: Status;
+  pid: number | null;
+  startedAt: number | null;
+  exitCode: number | null;
+  /** Editable/desired config — takes effect on the next start/restart. */
+  config: ServerConfig;
+  /** Config the live process was actually launched with (null when stopped). */
+  runningConfig: ServerConfig | null;
+}
+
+const MAX_LOGS = 800;
+const STOP_TIMEOUT_MS = 8000;
+
+function defaultConfig(): ServerConfig {
+  return {
+    command: process.env.BUNQUEUE_START_CMD || 'bunqueue start',
+    httpPort: Number(process.env.HTTP_PORT) || 6790,
+    tcpPort: Number(process.env.TCP_PORT) || 6789,
+    dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',
+    extraEnv: {},
+  };
+}
+
+export class ProcessManager {
+  private proc: ReturnType<typeof Bun.spawn> | null = null;
+  private status: Status = 'stopped';
+  private startedAt: number | null = null;
+  private exitCode: number | null = null;
+  private config: ServerConfig = defaultConfig();
+  private runningConfig: ServerConfig | null = null;
+  private logs: LogLine[] = [];
+  private seq = 0;
+  /**
+   * Monotonic id for the current process generation. Every start() bumps it;
+   * onExit and stop() only mutate shared state when their captured token is
+   * still current, so a stop() awaiting an old process can't clobber a process
+   * a concurrent start() brought up (and vice-versa).
+   */
+  private procToken = 0;
+
+  getConfig(): ServerConfig {
+    return this.config;
+  }
+
+  /**
+   * Update the desired config. Editing while the server runs is allowed; the
+   * change applies on the next start/restart (the live process keeps using
+   * `runningConfig` until then). Ports/data-path of a live process cannot be
+   * changed in place.
+   */
+  setConfig(patch: Partial<ServerConfig>): ServerConfig {
+    this.config = { ...this.config, ...patch, extraEnv: patch.extraEnv ?? this.config.extraEnv };
+    return this.config;
+  }
+
+  getStatus(): StatusSnapshot {
+    return {
+      status: this.status,
+      pid: this.proc?.pid ?? null,
+      startedAt: this.startedAt,
+      exitCode: this.exitCode,
+      config: this.config,
+      runningConfig: this.runningConfig,
+    };
+  }
+
+  /** Stat the configured SQLite db file plus its WAL/SHM sidecars. */
+  async dbStats(): Promise<DbStats> {
+    const path = this.config.dataPath;
+    const one = async (p: string): Promise<{ size: number; mtimeMs: number | null }> => {
+      try {
+        const f = Bun.file(p);
+        if (!(await f.exists())) return { size: 0, mtimeMs: null };
+        return { size: f.size, mtimeMs: f.lastModified };
+      } catch {
+        return { size: 0, mtimeMs: null };
+      }
+    };
+    const [main, wal, shm] = await Promise.all([
+      one(path),
+      one(`${path}-wal`),
+      one(`${path}-shm`),
+    ]);
+    return {
+      path,
+      exists: main.mtimeMs !== null,
+      size: main.size,
+      walSize: wal.size,
+      shmSize: shm.size,
+      totalSize: main.size + wal.size + shm.size,
+      mtimeMs: main.mtimeMs,
+    };
+  }
+
+  getLogs(): LogLine[] {
+    return this.logs;
+  }
+
+  private push(stream: LogLine['stream'], line: string): void {
+    this.logs.push({ seq: this.seq++, ts: Date.now(), stream, line });
+    // Amortized trim: only splice once the buffer overshoots by a slack margin, so
+    // steady-state logging isn't an O(n) array shift on every single line.
+    if (this.logs.length > MAX_LOGS + 256) this.logs.splice(0, this.logs.length - MAX_LOGS);
+  }
+
+  async start(): Promise<StatusSnapshot> {
+    if (this.status === 'running' || this.status === 'starting') return this.getStatus();
+    this.status = 'starting';
+    this.exitCode = null;
+    const token = ++this.procToken;
+
+    const parts = this.config.command.trim().split(/\s+/);
+    const [cmd, ...args] = parts;
+    if (!cmd) {
+      this.status = 'stopped';
+      throw new Error('Empty command');
+    }
+
+    const env: Record<string, string> = {
+      ...(process.env as Record<string, string>),
+      HTTP_PORT: String(this.config.httpPort),
+      TCP_PORT: String(this.config.tcpPort),
+      BUNQUEUE_DATA_PATH: this.config.dataPath,
+      ...this.config.extraEnv,
+    };
+
+    try {
+      this.proc = Bun.spawn([cmd, ...args], {
+        env,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        onExit: (_p, code) => {
+          // Ignore the exit of a process a newer start() has already replaced.
+          if (this.procToken !== token) return;
+          this.exitCode = code ?? null;
+          this.status = 'stopped';
+          this.proc = null;
+          this.runningConfig = null;
+          this.push('sys', `process exited (code ${code ?? '?'})`);
+        },
+      });
+    } catch (e) {
+      this.status = 'stopped';
+      // Leave a consistent stopped snapshot: without this, a spawn failure
+      // racing an in-flight stop() (whose token is already stale, so its
+      // finalizer returns early) leaves getStatus() reporting the previous
+      // generation's dead pid and a non-null runningConfig.
+      this.proc = null;
+      this.runningConfig = null;
+      throw new Error(`Failed to spawn "${cmd}": ${(e as Error).message}`);
+    }
+
+    this.startedAt = Date.now();
+    this.status = 'running';
+    this.runningConfig = { ...this.config, extraEnv: { ...this.config.extraEnv } };
+    this.push('sys', `started: ${this.config.command} (pid ${this.proc.pid})`);
+    void this.pipe(this.proc.stdout as ReadableStream<Uint8Array>, 'stdout');
+    void this.pipe(this.proc.stderr as ReadableStream<Uint8Array>, 'stderr');
+    return this.getStatus();
+  }
+
+  private async pipe(stream: ReadableStream<Uint8Array>, name: 'stdout' | 'stderr'): Promise<void> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let i: number;
+        while ((i = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, i);
+          buffer = buffer.slice(i + 1);
+          if (line.trim()) this.push(name, line);
+        }
+      }
+    } catch {
+      /* stream closed */
+    }
+    // Flush the final chunk when the stream ends without a trailing newline
+    // (e.g. a crash cause written via a bare write()) — otherwise the last,
+    // often most important, line never reaches the log buffer.
+    const tail = buffer + decoder.decode();
+    if (tail.trim()) this.push(name, tail);
+  }
+
+  async stop(): Promise<StatusSnapshot> {
+    if (!this.proc) {
+      this.status = 'stopped';
+      this.runningConfig = null;
+      return this.getStatus();
+    }
+    this.status = 'stopping';
+    this.push('sys', 'stopping (SIGTERM)…');
+    const proc = this.proc;
+    const token = this.procToken;
+    proc.kill();
+    const timedOut = await Promise.race([
+      proc.exited.then(() => false),
+      new Promise<boolean>((r) => setTimeout(() => r(true), STOP_TIMEOUT_MS)),
+    ]);
+    // Always escalate to SIGKILL on the CAPTURED proc (never `this.proc`) so a
+    // child that ignores SIGTERM is still reaped even if a concurrent start()
+    // has since swapped in a new process — `proc` targets this generation only.
+    if (timedOut) {
+      this.push('sys', 'SIGTERM timed out, sending SIGKILL');
+      proc.kill(9);
+      await proc.exited;
+    }
+    // Only finalize shared state if no newer start() replaced this generation
+    // while we awaited — otherwise we'd null out the wrong (live) process.
+    if (this.procToken !== token) return this.getStatus();
+    this.status = 'stopped';
+    this.proc = null;
+    this.runningConfig = null;
+    return this.getStatus();
+  }
+
+  async restart(): Promise<StatusSnapshot> {
+    await this.stop();
+    return this.start();
+  }
+}

package/agent/server.ts

@@ -0,0 +1,213 @@
+/**
+ * Request handling + origin/auth policy for the control agent, factored out of
+ * index.ts so it can be unit-tested without binding a port.
+ *
+ * Threat model: the agent can spawn arbitrary processes (`/control/config` sets
+ * the launch command, `/control/start` runs it). It binds 127.0.0.1, but that
+ * does NOT stop a malicious web page the user is visiting from issuing a
+ * cross-origin request to http://127.0.0.1:6800 (CSRF → RCE). Defenses:
+ *
+ *  1. CORS is locked to an explicit allowlist (never `*`); the browser is only
+ *     told a cross-origin response is readable for known dashboard origins.
+ *  2. Any request carrying a disallowed `Origin` header is rejected (403)
+ *     before it can reach the ProcessManager — a cross-origin browser request
+ *     always sends `Origin`, so a drive-by page cannot start/stop/reconfigure
+ *     the server. Non-browser callers (curl, same-process) send no Origin and
+ *     still work for local use.
+ *  3. Optional bearer token (AGENT_TOKEN): when set, state-changing requests
+ *     must present it (`Authorization: Bearer <t>` or `x-agent-token: <t>`).
+ */
+import { type DbFilter, dbCell, dbInfo, dbRows, dbSchema, dbTables, MissingDbError, queryWithTimeout } from './db';
+import type { ProcessManager, ServerConfig } from './manager';
+
+export interface AgentOptions {
+  allowedOrigins: string[];
+  /** When set, POST/PUT requests must present this token. */
+  token?: string;
+}
+
+const DEFAULT_ORIGINS = ['http://localhost:5273', 'http://127.0.0.1:5273'];
+
+/** Parse AGENT_ALLOWED_ORIGINS (comma-separated) merged with sane dev defaults. */
+export function resolveAllowedOrigins(env = process.env): string[] {
+  const extra = (env.AGENT_ALLOWED_ORIGINS ?? '')
+    .split(',')
+    .map((s) => s.trim().replace(/\/$/, ''))
+    .filter(Boolean);
+  return Array.from(new Set([...DEFAULT_ORIGINS, ...extra]));
+}
+
+export function isOriginAllowed(origin: string | null, allowed: string[]): boolean {
+  if (!origin) return true; // non-browser caller (curl / same process) — no Origin header
+  return allowed.includes(origin.replace(/\/$/, ''));
+}
+
+/** CORS headers. ACAO is reflected only for an allowed origin (never `*`). */
+export function corsHeaders(origin: string | null, allowed: string[]): Record<string, string> {
+  const h: Record<string, string> = {
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Agent-Token',
+    Vary: 'Origin',
+  };
+  if (origin && allowed.includes(origin.replace(/\/$/, ''))) {
+    h['Access-Control-Allow-Origin'] = origin;
+  }
+  return h;
+}
+
+function tokenOk(req: Request, token?: string): boolean {
+  if (!token) return true;
+  const auth = req.headers.get('authorization') ?? '';
+  const bearer = auth.startsWith('Bearer ') ? auth.slice(7) : '';
+  return bearer === token || req.headers.get('x-agent-token') === token;
+}
+
+/**
+ * Build the fetch handler for the agent. Pure w.r.t. the network — takes a
+ * ProcessManager and policy, returns an async (req) => Response.
+ */
+export function createFetchHandler(mgr: ProcessManager, opts: AgentOptions) {
+  const { allowedOrigins, token } = opts;
+
+  const json = (data: unknown, status: number, origin: string | null): Response =>
+    new Response(JSON.stringify(data), {
+      status,
+      headers: { 'Content-Type': 'application/json', ...corsHeaders(origin, allowedOrigins) },
+    });
+
+  async function statusWithHealth() {
+    const snap = mgr.getStatus();
+    let healthy = false;
+    let version: string | undefined;
+    if (snap.status === 'running') {
+      const port = snap.runningConfig?.httpPort ?? snap.config.httpPort;
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/health`, {
+          signal: AbortSignal.timeout(1500),
+        });
+        if (res.ok) {
+          const h = (await res.json()) as { ok?: boolean; version?: string };
+          healthy = h.ok !== false;
+          version = h.version;
+        }
+      } catch {
+        /* not up yet */
+      }
+    }
+    const db = await mgr.dbStats().catch(() => null);
+    return { ...snap, healthy, version, db };
+  }
+
+  return async function handle(req: Request): Promise<Response> {
+    const { pathname } = new URL(req.url);
+    const method = req.method;
+    const origin = req.headers.get('origin');
+
+    if (method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: corsHeaders(origin, allowedOrigins) });
+    }
+
+    // Block any request from a disallowed browser origin before it can act.
+    if (!isOriginAllowed(origin, allowedOrigins)) {
+      return json({ ok: false, error: 'Origin not allowed' }, 403, origin);
+    }
+
+    // The optional AGENT_TOKEN gates STATE-CHANGING requests only. Read-only
+    // GETs (including the /db/* inspector, which can expose job payloads) are
+    // protected by the Origin allowlist alone — a drive-by cross-origin page
+    // can't read the response (no ACAO for its origin), which is the real
+    // threat. Gating reads behind the token would break the dashboard itself:
+    // the browser client sends no agent token (see bq.ts `agent()`), so the
+    // whole point of loopback + allowlisted CORS is to make browser reads work
+    // without one. Non-browser local callers on loopback are trusted for reads.
+    const mutating = method === 'POST' || method === 'PUT';
+    if (mutating && !tokenOk(req, token)) {
+      return json({ ok: false, error: 'Unauthorized' }, 401, origin);
+    }
+
+    try {
+      if (pathname === '/control/status') return json(await statusWithHealth(), 200, origin);
+      if (pathname === '/control/logs') return json({ lines: mgr.getLogs() }, 200, origin);
+
+      if (pathname === '/control/start' && method === 'POST') {
+        await mgr.start();
+        return json(await statusWithHealth(), 200, origin);
+      }
+      if (pathname === '/control/stop' && method === 'POST') {
+        await mgr.stop();
+        return json(await statusWithHealth(), 200, origin);
+      }
+      if (pathname === '/control/restart' && method === 'POST') {
+        await mgr.restart();
+        return json(await statusWithHealth(), 200, origin);
+      }
+
+      if (pathname === '/control/config' && method === 'GET') return json(mgr.getConfig(), 200, origin);
+      if (pathname === '/control/config' && method === 'PUT') {
+        const patch = (await req.json()) as Partial<ServerConfig>;
+        return json(mgr.setConfig(patch), 200, origin);
+      }
+
+      // Read-only SQLite inspector (agent/db.ts opens every connection
+      // readonly, so none of these can mutate the store). The POST query
+      // endpoint rides the same token gate as other mutating methods.
+      if (pathname === '/db/info' && method === 'GET') {
+        return json({ ok: true, ...dbInfo(mgr.getConfig().dataPath) }, 200, origin);
+      }
+      if (pathname === '/db/tables' && method === 'GET') {
+        return json({ ok: true, tables: dbTables(mgr.getConfig().dataPath) }, 200, origin);
+      }
+      // Segment-based routing (the client percent-encodes the table name, so it
+      // never contains a literal '/'): a single trailing segment is the rows
+      // route; `<table>/schema` and `<table>/cell` are sub-resources. This is
+      // unambiguous even for a table literally named "schema" or "cell".
+      if (pathname.startsWith('/db/tables/') && method === 'GET') {
+        const segs = pathname.slice('/db/tables/'.length).split('/');
+        const table = decodeURIComponent(segs[0] ?? '');
+        const sub = segs[1];
+        if (segs.length === 2 && sub === 'schema') {
+          return json({ ok: true, ...dbSchema(mgr.getConfig().dataPath, table) }, 200, origin);
+        }
+        if (segs.length === 2 && sub === 'cell') {
+          const sp = new URL(req.url).searchParams;
+          const rowid = Number(sp.get('rowid'));
+          const column = sp.get('column') ?? '';
+          return json(
+            { ok: true, ...dbCell(mgr.getConfig().dataPath, table, rowid, column) },
+            200,
+            origin
+          );
+        }
+        if (segs.length !== 1) return json({ ok: false, error: 'Not found' }, 404, origin);
+        const sp = new URL(req.url).searchParams;
+        const limit = Number(sp.get('limit')) || 50;
+        const offset = Number(sp.get('offset')) || 0;
+        const orderBy = sp.get('orderBy') || undefined;
+        const dir = sp.get('dir') === 'desc' ? 'desc' : 'asc';
+        const fCol = sp.get('fcol');
+        const fOp = sp.get('fop');
+        const fVal = sp.get('fval');
+        const filter: DbFilter | undefined =
+          fCol && fVal
+            ? { column: fCol, op: fOp === 'eq' ? 'eq' : fOp === 'ne' ? 'ne' : 'contains', value: fVal }
+            : undefined;
+        return json(
+          { ok: true, ...dbRows(mgr.getConfig().dataPath, table, limit, offset, orderBy, dir, filter) },
+          200,
+          origin
+        );
+      }
+      if (pathname === '/db/query' && method === 'POST') {
+        const { sql } = (await req.json()) as { sql?: string };
+        return json({ ok: true, ...(await queryWithTimeout(mgr.getConfig().dataPath, sql ?? '')) }, 200, origin);
+      }
+
+      return json({ ok: false, error: 'Not found' }, 404, origin);
+    } catch (e) {
+      // A missing database file is an expected pre-first-start condition — 404
+      // so the UI can show "no database yet" distinctly from a real read error.
+      const status = e instanceof MissingDbError ? 404 : 400;
+      return json({ ok: false, error: (e as Error).message ?? String(e) }, status, origin);
+    }
+  };
+}