bunqueue-dashboard 0.0.34 → 0.0.36

package/agent/manager/process.ts

@@ -0,0 +1,233 @@
+import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
+import { ProcessLogs } from './logs';
+import { databaseStats } from './storage';
+import type {
+  DbStats,
+  LogLine,
+  ServerConfig,
+  Status,
+  StatusSnapshot,
+} from './types';
+
+const STOP_TIMEOUT_MS = 8000;
+type ManagedProcess = ReturnType<typeof Bun.spawn>;
+
+async function exitsWithin(process: ManagedProcess, timeout: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    process.exited.then(() => true),
+    new Promise<boolean>((resolve) => {
+      timer = setTimeout(() => resolve(false), timeout);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/** Supervises one bunqueue server child process. */
+export class ProcessManager {
+  private proc: ManagedProcess | 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 procToken = 0;
+  private stopping: Promise<StatusSnapshot> | null = null;
+  private shuttingDown = false;
+  private maintenance: string | null = null;
+  private output = new ProcessLogs();
+
+  constructor(private readonly stopTimeoutMs = STOP_TIMEOUT_MS) {}
+
+  getConfig(): ServerConfig {
+    return copyConfig(this.config);
+  }
+
+  setConfig(patch: Partial<ServerConfig>): ServerConfig {
+    const valid = validateConfigPatch(patch);
+    this.config = {
+      ...this.config,
+      ...valid,
+      extraEnv: valid.extraEnv ?? this.config.extraEnv,
+    };
+    return copyConfig(this.config);
+  }
+
+  getStatus(): StatusSnapshot {
+    return {
+      status: this.status,
+      generation: this.procToken,
+      pid: this.proc?.pid ?? null,
+      startedAt: this.startedAt,
+      exitCode: this.exitCode,
+      config: copyConfig(this.config),
+      runningConfig: this.runningConfig ? copyConfig(this.runningConfig) : null,
+    };
+  }
+
+  dbStats(): Promise<DbStats> {
+    return databaseStats(this.config.dataPath);
+  }
+
+  getLogs(): LogLine[] {
+    return this.output.get();
+  }
+
+  async start(): Promise<StatusSnapshot> {
+    this.assertNoMaintenance('start');
+    if (this.shuttingDown) return this.getStatus();
+    if (this.status === 'running' || this.status === 'starting') return this.getStatus();
+    if (this.stopping) await this.stopping;
+    this.assertNoMaintenance('start');
+    if (this.shuttingDown) return this.getStatus();
+    const statusAfterWait = this.status as Status;
+    if (statusAfterWait === 'running' || statusAfterWait === 'starting') {
+      return this.getStatus();
+    }
+    if (this.proc) {
+      throw new Error(
+        `Cannot start while the previous managed process (pid ${this.proc.pid}) is still alive`
+      );
+    }
+
+    const launchConfig = validateServerConfig(this.config);
+    const [command, ...args] = launchConfig.command.trim().split(/\s+/);
+    this.status = 'starting';
+    this.exitCode = null;
+    const token = ++this.procToken;
+    const env: Record<string, string> = {
+      ...(process.env as Record<string, string>),
+      ...launchConfig.extraEnv,
+      HTTP_PORT: String(launchConfig.httpPort),
+      TCP_PORT: String(launchConfig.tcpPort),
+      BUNQUEUE_DATA_PATH: launchConfig.dataPath,
+    };
+
+    try {
+      this.proc = Bun.spawn([command, ...args], {
+        env,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        onExit: (_process, code) => {
+          this.output.cancel(token);
+          if (this.procToken !== token) return;
+          this.exitCode = code ?? null;
+          this.status = 'stopped';
+          this.proc = null;
+          this.runningConfig = null;
+          this.output.push('sys', `process exited (code ${code ?? '?'})`);
+        },
+      });
+    } catch (error) {
+      this.status = 'stopped';
+      this.proc = null;
+      this.runningConfig = null;
+      throw new Error(`Failed to spawn "${command}": ${(error as Error).message}`);
+    }
+
+    this.startedAt = Date.now();
+    this.status = 'running';
+    this.runningConfig = copyConfig(launchConfig);
+    this.output.push('sys', `started: ${launchConfig.command} (pid ${this.proc.pid})`);
+    const isCurrent = () => this.procToken === token;
+    void this.output.capture(
+      this.proc.stdout as unknown as ReadableStream<Uint8Array>,
+      'stdout',
+      token,
+      isCurrent
+    );
+    void this.output.capture(
+      this.proc.stderr as unknown as ReadableStream<Uint8Array>,
+      'stderr',
+      token,
+      isCurrent
+    );
+    return this.getStatus();
+  }
+
+  stop(): Promise<StatusSnapshot> {
+    if (this.stopping) return this.stopping;
+    const pending = this.stopOnce();
+    this.stopping = pending;
+    const clearStopping = () => {
+      if (this.stopping === pending) this.stopping = null;
+    };
+    void pending.then(clearStopping, clearStopping);
+    return pending;
+  }
+
+  /** Permanently prevent this manager from spawning another child process. */
+  beginShutdown(): void {
+    this.shuttingDown = true;
+  }
+
+  /** Last-resort terminal path used after graceful shutdown times out. */
+  forceShutdown(): void {
+    this.beginShutdown();
+    if (!this.proc) return;
+    this.output.push('sys', `force stopping pid ${this.proc.pid} (SIGKILL)`);
+    this.proc.kill(9);
+  }
+
+  async shutdown(): Promise<StatusSnapshot> {
+    this.beginShutdown();
+    return this.stop();
+  }
+
+  private async stopOnce(): Promise<StatusSnapshot> {
+    if (!this.proc) {
+      this.status = 'stopped';
+      this.runningConfig = null;
+      return this.getStatus();
+    }
+    this.status = 'stopping';
+    this.output.push('sys', 'stopping (SIGTERM)…');
+    const process = this.proc;
+    const token = this.procToken;
+    process.kill();
+    if (!(await exitsWithin(process, this.stopTimeoutMs))) {
+      this.output.push('sys', 'SIGTERM timed out, sending SIGKILL');
+      process.kill(9);
+      if (!(await exitsWithin(process, this.stopTimeoutMs))) {
+        const message = `pid ${process.pid} did not exit after SIGKILL`;
+        this.output.push('sys', `${message} — retaining failed-process tracking`);
+        throw new Error(message);
+      }
+    }
+    this.output.cancel(token);
+    if (this.procToken !== token) return this.getStatus();
+    this.status = 'stopped';
+    this.proc = null;
+    this.runningConfig = null;
+    return this.getStatus();
+  }
+
+  async restart(): Promise<StatusSnapshot> {
+    this.assertNoMaintenance('restart');
+    await this.stop();
+    return this.start();
+  }
+
+  /** Hold an atomic stopped-server lease across a destructive maintenance task. */
+  async withStoppedMaintenance<T>(label: string, operation: () => Promise<T>): Promise<T> {
+    if (this.maintenance) {
+      throw new Error(`Another maintenance operation is already running: ${this.maintenance}`);
+    }
+    if (this.proc || this.status !== 'stopped' || this.stopping) {
+      throw new Error(`Stop the managed Bunqueue server before ${label}`);
+    }
+    this.maintenance = label;
+    try {
+      return await operation();
+    } finally {
+      if (this.maintenance === label) this.maintenance = null;
+    }
+  }
+
+  private assertNoMaintenance(action: 'start' | 'restart'): void {
+    if (this.maintenance) {
+      throw new Error(
+        `Cannot ${action} the managed Bunqueue server while ${this.maintenance} is running`
+      );
+    }
+  }
+}

package/agent/manager/storage.ts

@@ -0,0 +1,28 @@
+import type { DbStats } from './types';
+
+/** Stat a SQLite database plus its WAL/SHM sidecars. */
+export async function databaseStats(path: string): Promise<DbStats> {
+  const one = async (file: string): Promise<{ size: number; mtimeMs: number | null }> => {
+    try {
+      const handle = Bun.file(file);
+      if (!(await handle.exists())) return { size: 0, mtimeMs: null };
+      return { size: handle.size, mtimeMs: handle.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,
+  };
+}

package/agent/manager/types.ts

@@ -0,0 +1,38 @@
+export type Status = 'running' | 'stopped' | 'starting' | 'stopping';
+
+export interface ServerConfig {
+  /** Command to launch the server. */
+  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;
+}
+
+export interface DbStats {
+  path: string;
+  exists: boolean;
+  size: number;
+  walSize: number;
+  shmSize: number;
+  totalSize: number;
+  mtimeMs: number | null;
+}
+
+export interface StatusSnapshot {
+  status: Status;
+  /** Monotonic identity of the managed process generation. */
+  generation: number;
+  pid: number | null;
+  startedAt: number | null;
+  exitCode: number | null;
+  config: ServerConfig;
+  runningConfig: ServerConfig | null;
+}