bunqueue-dashboard 0.0.34 → 0.0.36

package/agent/db/core.ts

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import {
+  DB_EXPORT_MAX_BYTES,
+  DB_EXPORT_MAX_ROWS,
+  MAX_CELL,
+  MissingDbError,
+  type DbFilter,
+  type DbRowId,
+} from './types';
+
+export function openDb(path: string): Database {
+  try {
+    if (!Bun.file(path).size && !existsSync(path)) {
+      throw new MissingDbError(
+        `Database not found at "${path}" — start the server once to create it.`
+      );
+    }
+  } catch (error) {
+    if (error instanceof MissingDbError) throw error;
+  }
+  try {
+    return new Database(path, { readonly: true });
+  } catch (error) {
+    if (!existsSync(path)) {
+      throw new MissingDbError(
+        `Database not found at "${path}" — start the server once to create it.`
+      );
+    }
+    throw new Error(`Could not open database: ${(error as Error).message}`);
+  }
+}
+
+export const ident = (name: string): string => `"${name.replaceAll('"', '""')}"`;
+
+export function isTruncated(value: unknown): boolean {
+  return (
+    (value instanceof Uint8Array && value.byteLength > 0) ||
+    (typeof value === 'string' && value.length > MAX_CELL)
+  );
+}
+
+export function bigintCell(value: bigint): number | string {
+  return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)
+    ? Number(value)
+    : value.toString();
+}
+
+export function jsonCell(value: unknown): unknown {
+  if (value instanceof Uint8Array) return `<blob ${value.byteLength} B>`;
+  if (typeof value === 'string' && value.length > MAX_CELL) {
+    return `${value.slice(0, MAX_CELL)}…`;
+  }
+  if (typeof value === 'bigint') return bigintCell(value);
+  return value;
+}
+
+export const sanitize = (rows: unknown[][]): unknown[][] =>
+  rows.map((row) => row.map(jsonCell));
+
+const MIN_SQLITE_INTEGER = -(1n << 63n);
+const MAX_SQLITE_INTEGER = (1n << 63n) - 1n;
+
+export function boundRowid(rowid: DbRowId): DbRowId {
+  if (typeof rowid === 'number') {
+    if (!Number.isSafeInteger(rowid)) throw new Error('Invalid rowid');
+    return rowid;
+  }
+  if (rowid.length === 0 || rowid.length > 20 || !/^-?\d+$/.test(rowid)) {
+    throw new Error('Invalid rowid');
+  }
+  const integer = BigInt(rowid);
+  if (integer < MIN_SQLITE_INTEGER || integer > MAX_SQLITE_INTEGER) {
+    throw new Error('Invalid rowid');
+  }
+  return rowid;
+}
+
+/** bun:sqlite exposes this at runtime but does not type it. */
+export function safeIntegers(statement: unknown): void {
+  (statement as { safeIntegers?: (on: boolean) => void }).safeIntegers?.(true);
+}
+
+export function knownTable(db: Database, table: string): string {
+  const known = db
+    .query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get(table) as { name: string } | null;
+  if (!known) throw new Error(`No such table: ${table}`);
+  return known.name;
+}
+
+export function buildFilter(
+  columns: string[],
+  filter: DbFilter | undefined
+): { clause: string; params: unknown[]; applied: DbFilter | null } {
+  if (!filter || !filter.value) return { clause: '', params: [], applied: null };
+  const column = columns.find((candidate) => candidate === filter.column);
+  if (!column) throw new Error(`No such column: ${filter.column}`);
+  const quoted = ident(column);
+  if (filter.op === 'eq') {
+    return { clause: ` WHERE ${quoted} = ?`, params: [filter.value], applied: filter };
+  }
+  if (filter.op === 'ne') {
+    return { clause: ` WHERE ${quoted} <> ?`, params: [filter.value], applied: filter };
+  }
+  const needle = filter.value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('%', '\\%')
+    .replaceAll('_', '\\_');
+  return {
+    clause: ` WHERE ${quoted} LIKE ? ESCAPE '\\'`,
+    params: [`%${needle}%`],
+    applied: { ...filter, op: 'contains' },
+  };
+}
+
+export function boundedExportLimit(
+  value: number | undefined,
+  hardCap: number,
+  label: string
+): number {
+  if (value === undefined) return hardCap;
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${label} must be a positive safe integer`);
+  }
+  return Math.min(value, hardCap);
+}
+
+export function validateWorkerBounds(rows: number, bytes: number): boolean {
+  return rows >= 0 && rows <= DB_EXPORT_MAX_ROWS && bytes >= 1 && bytes <= DB_EXPORT_MAX_BYTES;
+}
+
+export function translateDbError(error: unknown): Error {
+  const message = String((error as Error)?.message ?? error);
+  if (/readonly|read-only|SQLITE_READONLY/i.test(message)) {
+    return new Error(
+      'Connection is read-only — INSERT / UPDATE / DELETE / DDL are not permitted here.'
+    );
+  }
+  return error instanceof Error ? error : new Error(message);
+}

package/agent/db/csvExport.ts

@@ -0,0 +1,172 @@
+import {
+  boundedExportLimit,
+  buildFilter,
+  ident,
+  knownTable,
+  openDb,
+  safeIntegers,
+  translateDbError,
+} from './core';
+import {
+  DB_EXPORT_MAX_BYTES,
+  DB_EXPORT_MAX_COLUMNS,
+  DB_EXPORT_MAX_FILTER_CHARS,
+  DB_EXPORT_MAX_IDENTIFIER_CHARS,
+  DB_EXPORT_MAX_ROWS,
+  MAX_CELL,
+  type DbCsvExport,
+  type DbExportCap,
+  type DbExportLimits,
+  type DbFilter,
+} from './types';
+
+function csvCell(value: unknown): string {
+  let text: string;
+  let textual = false;
+  if (value == null) text = '';
+  else if (typeof value === 'string') {
+    text = value;
+    textual = true;
+  } else if (
+    typeof value === 'bigint' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    text = String(value);
+  } else if (value instanceof Uint8Array) {
+    text = `<blob ${value.byteLength} B>`;
+    textual = true;
+  } else {
+    throw new Error('Database export produced an unsupported SQLite value');
+  }
+  const safe = textual && /^[=+\-@\t\r]/.test(text) ? `'${text}` : text;
+  return /[",\r\n]/.test(safe) ? `"${safe.replaceAll('"', '""')}"` : safe;
+}
+
+function validateRequest(table: string, dir: string, filter?: DbFilter): void {
+  if (typeof table !== 'string' || table.length === 0) throw new Error('Table is required');
+  if (table.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+    throw new Error(`Table name exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+  }
+  if (dir !== 'asc' && dir !== 'desc') throw new Error('Invalid export sort direction');
+  if (!filter) return;
+  if (
+    typeof filter.column !== 'string' ||
+    !filter.column ||
+    !['contains', 'eq', 'ne'].includes(filter.op) ||
+    typeof filter.value !== 'string'
+  ) {
+    throw new Error('Invalid database export filter');
+  }
+  if (filter.column.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+    throw new Error(`Filter column exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+  }
+  if (filter.value.length > DB_EXPORT_MAX_FILTER_CHARS) {
+    throw new Error(`Database export filter exceeds ${DB_EXPORT_MAX_FILTER_CHARS} characters`);
+  }
+}
+
+/** Export one filtered/sorted table view from a single SQLite snapshot. */
+export function dbExportCsv(
+  path: string,
+  table: string,
+  orderBy?: string,
+  dir: 'asc' | 'desc' = 'asc',
+  filter?: DbFilter,
+  limits: Readonly<DbExportLimits> = {}
+): DbCsvExport {
+  validateRequest(table, dir, filter);
+  const maxRows = boundedExportLimit(limits.maxRows, DB_EXPORT_MAX_ROWS, 'Export row limit');
+  const maxBytes = boundedExportLimit(limits.maxBytes, DB_EXPORT_MAX_BYTES, 'Export byte limit');
+  const db = openDb(path);
+  try {
+    const snapshot = db.transaction((): DbCsvExport => {
+      const name = knownTable(db, table);
+      const columns = (
+        db.query(`PRAGMA table_info(${ident(name)})`).all() as { name: string }[]
+      ).map((column) => column.name);
+      if (columns.length === 0) throw new Error(`Table has no exportable columns: ${name}`);
+      if (columns.length > DB_EXPORT_MAX_COLUMNS) {
+        throw new Error(
+          `Table has ${columns.length} columns; database export supports at most ${DB_EXPORT_MAX_COLUMNS}`
+        );
+      }
+      if (columns.some((column) => column.length > DB_EXPORT_MAX_IDENTIFIER_CHARS)) {
+        throw new Error(
+          `Database export column names must not exceed ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`
+        );
+      }
+      limits.onSnapshot?.();
+
+      let order = '';
+      if (orderBy !== undefined) {
+        if (typeof orderBy !== 'string' || !orderBy) {
+          throw new Error('Invalid database export sort column');
+        }
+        if (orderBy.length > DB_EXPORT_MAX_IDENTIFIER_CHARS) {
+          throw new Error(`Sort column exceeds ${DB_EXPORT_MAX_IDENTIFIER_CHARS} characters`);
+        }
+        const sortColumn = columns.find((column) => column === orderBy);
+        if (!sortColumn) throw new Error(`No such column: ${orderBy}`);
+        order = ` ORDER BY ${ident(sortColumn)} ${dir === 'desc' ? 'DESC' : 'ASC'}`;
+      }
+      const { clause, params } = buildFilter(columns, filter);
+      const aliases = columns.map((_, index) => `__bq_export_${index}`);
+      const selected = columns.map((column, index) => {
+        const quoted = ident(column);
+        return (
+          `CASE WHEN typeof(${quoted}) = 'blob' THEN '<blob ' || length(${quoted}) || ' B>' ` +
+          `WHEN typeof(${quoted}) = 'text' AND length(CAST(${quoted} AS BLOB)) > ${MAX_CELL} ` +
+          `THEN substr(${quoted}, 1, ${MAX_CELL}) || '…' ` +
+          `ELSE ${quoted} END AS ${ident(aliases[index])}`
+        );
+      });
+      const statement = db.query<Record<string, unknown>, Array<string | number>>(
+        `SELECT ${selected.join(', ')} FROM ${ident(name)}${clause}${order} LIMIT ?`
+      );
+      safeIntegers(statement);
+
+      const encoder = new TextEncoder();
+      const buffer = new Uint8Array(maxBytes);
+      let used = 0;
+      const append = (text: string): boolean => {
+        const result = encoder.encodeInto(text, buffer.subarray(used));
+        if (result.read !== text.length) return false;
+        used += result.written;
+        return true;
+      };
+      if (!append(columns.map(csvCell).join(','))) {
+        throw new Error(`Database export header exceeds the ${maxBytes}-byte export limit`);
+      }
+
+      let rowCount = 0;
+      let cap: DbExportCap = null;
+      const iterator = statement.iterate(...([...params, maxRows + 1] as Array<string | number>));
+      try {
+        for (;;) {
+          const next = iterator.next();
+          if (next.done) break;
+          if (rowCount >= maxRows) {
+            cap = 'rows';
+            break;
+          }
+          const line = `\r\n${aliases.map((alias) => csvCell(next.value[alias])).join(',')}`;
+          if (!append(line)) {
+            cap = 'bytes';
+            break;
+          }
+          rowCount++;
+        }
+      } finally {
+        iterator.return?.();
+      }
+      const content = buffer.slice(0, used);
+      return { table: name, content, rowCount, bytes: content.byteLength, cap };
+    });
+    return snapshot.deferred();
+  } catch (error) {
+    throw translateDbError(error);
+  } finally {
+    db.close();
+  }
+}

package/agent/db/exportTimeout.ts

@@ -0,0 +1,190 @@
+import { validateWorkerBounds } from './core';
+import { createExportWorker } from './workerFactory';
+import {
+  DB_EXPORT_MAX_ROWS,
+  DB_EXPORT_TIMEOUT_MS,
+  DbExportBusyError,
+  DbExportUnavailableError,
+  MAX_CONCURRENT_EXPORTS,
+  MissingDbError,
+  type DbCsvExport,
+  type DbExportCap,
+  type DbFilter,
+} from './types';
+
+let liveExportWorkers = 0;
+
+/** Export workers alive now, including abandoned SQLite calls still unwinding. */
+export const exportWorkerLoad = (): number => liveExportWorkers;
+
+function validatedWorkerExport(value: unknown, expectedTable: string): DbCsvExport {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new DbExportUnavailableError('Database export worker returned a malformed result');
+  }
+  const result = value as Record<string, unknown>;
+  if (
+    typeof result.table !== 'string' ||
+    result.table !== expectedTable ||
+    !(result.content instanceof Uint8Array) ||
+    !Number.isSafeInteger(result.rowCount) ||
+    !Number.isSafeInteger(result.bytes) ||
+    !validateWorkerBounds(result.rowCount as number, result.bytes as number) ||
+    result.content.byteLength !== result.bytes ||
+    (result.cap !== null && result.cap !== 'rows' && result.cap !== 'bytes') ||
+    (result.cap === 'rows' && result.rowCount !== DB_EXPORT_MAX_ROWS)
+  ) {
+    throw new DbExportUnavailableError('Database export worker returned a malformed result');
+  }
+  const content =
+    result.content.buffer instanceof ArrayBuffer
+      ? (result.content as Uint8Array<ArrayBuffer>)
+      : Uint8Array.from(result.content);
+  return {
+    table: result.table,
+    content,
+    rowCount: result.rowCount as number,
+    bytes: result.bytes as number,
+    cap: result.cap as DbExportCap,
+  };
+}
+
+interface WorkerResponse {
+  ok?: unknown;
+  export?: unknown;
+  error?: unknown;
+  missing?: unknown;
+}
+
+/** Run an atomic CSV export off the control-agent event loop. */
+export async function exportWithTimeout(
+  path: string,
+  table: string,
+  orderBy?: string,
+  dir: 'asc' | 'desc' = 'asc',
+  filter?: DbFilter,
+  signal?: AbortSignal
+): Promise<DbCsvExport> {
+  signal?.throwIfAborted();
+  if (liveExportWorkers >= MAX_CONCURRENT_EXPORTS) {
+    throw new DbExportBusyError(
+      'A database export is already running. Wait for it to finish, or restart the agent if it was abandoned.'
+    );
+  }
+
+  let worker: Worker;
+  try {
+    worker = createExportWorker();
+  } catch (error) {
+    throw new DbExportUnavailableError(
+      `Database export worker unavailable: ${(error as Error).message ?? String(error)}`
+    );
+  }
+  liveExportWorkers++;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    liveExportWorkers--;
+  };
+
+  try {
+    return await new Promise<DbCsvExport>((resolve, reject) => {
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const cleanup = () => {
+        if (timer !== undefined) clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+      };
+      const abandon = (error: Error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        worker.terminate();
+        reject(error);
+      };
+      const onAbort = () =>
+        abandon(
+          signal?.reason instanceof Error
+            ? signal.reason
+            : new Error('Database export request was aborted')
+        );
+
+      worker.addEventListener('close', () => {
+        release();
+        if (!settled) {
+          settled = true;
+          cleanup();
+          reject(new DbExportUnavailableError('Database export worker exited unexpectedly'));
+        }
+      });
+      worker.addEventListener('message', (event: MessageEvent) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        release();
+        const response = event.data as WorkerResponse | null;
+        if (!response || typeof response !== 'object' || Array.isArray(response)) {
+          reject(
+            new DbExportUnavailableError('Database export worker returned a malformed response')
+          );
+        } else if (response.ok === true) {
+          try {
+            resolve(validatedWorkerExport(response.export, table));
+          } catch (error) {
+            reject(error);
+          }
+        } else if (response.missing === true) {
+          reject(
+            new MissingDbError(
+              typeof response.error === 'string' ? response.error : 'Database not found'
+            )
+          );
+        } else {
+          reject(
+            new Error(
+              typeof response.error === 'string' ? response.error : 'Database export failed'
+            )
+          );
+        }
+      });
+      worker.addEventListener('error', (event: ErrorEvent) => {
+        if (settled) return;
+        event.preventDefault?.();
+        abandon(
+          new DbExportUnavailableError(
+            `Database export worker failed: ${event.message || 'unknown worker error'}`
+          )
+        );
+      });
+
+      timer = setTimeout(
+        () =>
+          abandon(
+            new DbExportUnavailableError(
+              `Database export exceeded the ${DB_EXPORT_TIMEOUT_MS / 1000}s time limit and was abandoned (SQLite may keep scanning until the worker exits).`
+            )
+          ),
+        DB_EXPORT_TIMEOUT_MS
+      );
+      signal?.addEventListener('abort', onAbort, { once: true });
+      if (signal?.aborted) {
+        onAbort();
+        return;
+      }
+      try {
+        worker.postMessage({ kind: 'export', path, table, orderBy, dir, filter });
+      } catch (error) {
+        settled = true;
+        cleanup();
+        release();
+        reject(
+          new DbExportUnavailableError(
+            `Could not start database export: ${(error as Error).message ?? String(error)}`
+          )
+        );
+      }
+    });
+  } finally {
+    worker.terminate();
+  }
+}

package/agent/db/query.ts

@@ -0,0 +1,82 @@
+import type { Database } from 'bun:sqlite';
+import { ident, openDb, safeIntegers, sanitize, translateDbError } from './core';
+import { MAX_ROWS, type DbQueryResult } from './types';
+
+const READ_ONLY_LEAD = /^(?:SELECT|WITH|EXPLAIN|VALUES|PRAGMA)\b/;
+const DUP_VIEW = '__bq_query_columns';
+
+function leadingKeyword(sql: string): string {
+  const head = sql.replace(/^(?:\s|--[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*/, '');
+  return head.slice(0, 12).toUpperCase();
+}
+
+/** Let SQLite disambiguate colliding output names through a private TEMP view. */
+function disambiguateColumns(
+  db: Database,
+  sql: string
+): { stmt: ReturnType<Database['query']>; cols: string[] } | null {
+  try {
+    // query().run() compiles one statement; db.run() would execute a trailing
+    // statement that the leading-keyword allowlist cannot see.
+    db.query(`CREATE TEMP VIEW ${ident(DUP_VIEW)} AS ${sql.replace(/;\s*$/, '')}`).run();
+    const columns = (
+      db.query(`PRAGMA table_info(${ident(DUP_VIEW)})`).all() as { name: string }[]
+    ).map((column) => column.name);
+    return { stmt: db.query(`SELECT * FROM ${ident(DUP_VIEW)}`), cols: columns };
+  } catch {
+    return null;
+  }
+}
+
+/** Synchronous read-only query implementation used inside a disposable Worker. */
+export function dbQuery(path: string, sql: string): DbQueryResult {
+  const trimmed = sql.trim();
+  if (!trimmed) throw new Error('Empty query');
+  if (!READ_ONLY_LEAD.test(leadingKeyword(trimmed))) {
+    throw new Error(
+      'Only read-only SELECT / WITH / EXPLAIN / VALUES / PRAGMA queries are allowed here.'
+    );
+  }
+  const db = openDb(path);
+  try {
+    const started = performance.now();
+    let statement: ReturnType<Database['query']>;
+    try {
+      statement = db.query(trimmed);
+    } catch (error) {
+      throw translateDbError(error);
+    }
+    let columns = statement.columnNames;
+    if (statement.columnTypes.length > columns.length) {
+      const disambiguated = disambiguateColumns(db, trimmed);
+      if (disambiguated) {
+        statement = disambiguated.stmt;
+        columns = disambiguated.cols;
+      }
+    }
+    safeIntegers(statement);
+    const rows: unknown[][] = [];
+    let truncated = false;
+    try {
+      for (const row of statement.iterate() as IterableIterator<Record<string, unknown>>) {
+        if (rows.length >= MAX_ROWS) {
+          truncated = true;
+          break;
+        }
+        rows.push(columns.map((column) => row[column]));
+      }
+    } catch (error) {
+      throw translateDbError(error);
+    }
+    const milliseconds = performance.now() - started;
+    return {
+      columns,
+      rows: sanitize(rows),
+      rowCount: rows.length,
+      truncated,
+      ms: Math.round(milliseconds * 10) / 10,
+    };
+  } finally {
+    db.close();
+  }
+}

package/agent/db/queryTimeout.ts

@@ -0,0 +1,76 @@
+import { createQueryWorker } from './workerFactory';
+import {
+  MAX_CONCURRENT_QUERIES,
+  MissingDbError,
+  QUERY_TIMEOUT_MS,
+  type DbQueryResult,
+} from './types';
+
+let liveQueryWorkers = 0;
+
+/** Query worker threads currently alive, including timed-out queries. */
+export const queryWorkerLoad = (): number => liveQueryWorkers;
+
+export async function queryWithTimeout(path: string, sql: string): Promise<DbQueryResult> {
+  if (liveQueryWorkers >= MAX_CONCURRENT_QUERIES) {
+    throw new Error(
+      `Too many queries running (${liveQueryWorkers}/${MAX_CONCURRENT_QUERIES}). A previous query timed out and is still running inside SQLite — wait for it to finish, or restart the agent.`
+    );
+  }
+  let worker: Worker;
+  try {
+    worker = createQueryWorker();
+  } catch (error) {
+    throw new Error(`Query worker unavailable: ${(error as Error).message ?? String(error)}`);
+  }
+  liveQueryWorkers++;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    liveQueryWorkers--;
+  };
+  worker.addEventListener('close', release);
+  try {
+    return await new Promise<DbQueryResult>((resolve, reject) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        worker.terminate();
+        reject(
+          new Error(
+            `Query exceeded the ${QUERY_TIMEOUT_MS / 1000}s time limit and was abandoned (it may keep running inside SQLite until it completes).`
+          )
+        );
+      }, QUERY_TIMEOUT_MS);
+      worker.addEventListener('message', (event: MessageEvent) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        release();
+        const response = event.data as {
+          ok: boolean;
+          result?: DbQueryResult;
+          error?: string;
+          missing?: boolean;
+        };
+        if (response.ok && response.result) resolve(response.result);
+        else if (response.missing) {
+          reject(new MissingDbError(response.error ?? 'Database not found'));
+        } else reject(new Error(response.error ?? 'Query failed'));
+      });
+      worker.addEventListener('error', (event: ErrorEvent) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        release();
+        event.preventDefault?.();
+        reject(new Error(`Query worker failed: ${event.message || 'unknown worker error'}`));
+      });
+      worker.postMessage({ path, sql });
+    });
+  } finally {
+    worker.terminate();
+  }
+}