@donkeylabs/server 0.5.0 → 0.6.3

package/src/core/job-adapter-sqlite.ts

@@ -0,0 +1,287 @@
+/**
+ * Built-in SQLite Job Adapter
+ *
+ * Provides automatic persistence for jobs, enabling server restart resilience
+ * for external jobs without requiring user configuration.
+ */
+
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { Job, JobAdapter, JobStatus } from "./jobs";
+import type { ExternalJobProcessState } from "./external-jobs";
+
+export interface SqliteJobAdapterConfig {
+  /** Path to SQLite database file (default: .donkeylabs/jobs.db) */
+  path?: string;
+  /** Auto-cleanup completed jobs older than N days (default: 7, 0 to disable) */
+  cleanupDays?: number;
+  /** Cleanup interval in ms (default: 3600000 = 1 hour) */
+  cleanupInterval?: number;
+}
+
+export class SqliteJobAdapter implements JobAdapter {
+  private db: Database;
+  private initialized = false;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+  private cleanupDays: number;
+
+  constructor(config: SqliteJobAdapterConfig = {}) {
+    const dbPath = config.path ?? ".donkeylabs/jobs.db";
+    this.cleanupDays = config.cleanupDays ?? 7;
+
+    // Ensure directory exists
+    this.ensureDir(dbPath);
+
+    this.db = new Database(dbPath);
+    this.init();
+
+    // Start cleanup timer
+    if (this.cleanupDays > 0) {
+      const interval = config.cleanupInterval ?? 3600000; // 1 hour
+      this.cleanupTimer = setInterval(() => this.cleanup(), interval);
+      // Run cleanup on startup
+      this.cleanup();
+    }
+  }
+
+  private ensureDir(dbPath: string): void {
+    const dir = dirname(dbPath);
+    if (dir && dir !== ".") {
+      // Sync mkdir for constructor
+      try {
+        Bun.spawnSync(["mkdir", "-p", dir]);
+      } catch {
+        // Directory may already exist
+      }
+    }
+  }
+
+  private init(): void {
+    if (this.initialized) return;
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS jobs (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        data TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        created_at TEXT NOT NULL,
+        run_at TEXT,
+        started_at TEXT,
+        completed_at TEXT,
+        result TEXT,
+        error TEXT,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        max_attempts INTEGER NOT NULL DEFAULT 3,
+        -- External job fields
+        external INTEGER DEFAULT 0,
+        pid INTEGER,
+        socket_path TEXT,
+        tcp_port INTEGER,
+        last_heartbeat TEXT,
+        process_state TEXT
+      )
+    `);
+
+    // Indexes for efficient queries
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_jobs_status ON jobs(status)`);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_jobs_name ON jobs(name)`);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_jobs_external ON jobs(external, status)`);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_jobs_scheduled ON jobs(status, run_at)`);
+
+    this.initialized = true;
+  }
+
+  async create(job: Omit<Job, "id">): Promise<Job> {
+    const id = `job_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    this.db.run(
+      `INSERT INTO jobs (
+        id, name, data, status, created_at, run_at, attempts, max_attempts,
+        external, process_state
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        job.name,
+        JSON.stringify(job.data),
+        job.status,
+        job.createdAt.toISOString(),
+        job.runAt?.toISOString() ?? null,
+        job.attempts,
+        job.maxAttempts,
+        job.external ? 1 : 0,
+        job.processState ?? null,
+      ]
+    );
+
+    return { ...job, id };
+  }
+
+  async get(jobId: string): Promise<Job | null> {
+    const row = this.db.query(`SELECT * FROM jobs WHERE id = ?`).get(jobId) as any;
+    if (!row) return null;
+    return this.rowToJob(row);
+  }
+
+  async update(jobId: string, updates: Partial<Job>): Promise<void> {
+    const sets: string[] = [];
+    const values: any[] = [];
+
+    if (updates.status !== undefined) {
+      sets.push("status = ?");
+      values.push(updates.status);
+    }
+    if (updates.startedAt !== undefined) {
+      sets.push("started_at = ?");
+      values.push(updates.startedAt?.toISOString() ?? null);
+    }
+    if (updates.completedAt !== undefined) {
+      sets.push("completed_at = ?");
+      values.push(updates.completedAt?.toISOString() ?? null);
+    }
+    if (updates.result !== undefined) {
+      sets.push("result = ?");
+      values.push(JSON.stringify(updates.result));
+    }
+    if (updates.error !== undefined) {
+      sets.push("error = ?");
+      values.push(updates.error);
+    }
+    if (updates.attempts !== undefined) {
+      sets.push("attempts = ?");
+      values.push(updates.attempts);
+    }
+    // External job fields
+    if (updates.pid !== undefined) {
+      sets.push("pid = ?");
+      values.push(updates.pid);
+    }
+    if (updates.socketPath !== undefined) {
+      sets.push("socket_path = ?");
+      values.push(updates.socketPath);
+    }
+    if (updates.tcpPort !== undefined) {
+      sets.push("tcp_port = ?");
+      values.push(updates.tcpPort);
+    }
+    if (updates.lastHeartbeat !== undefined) {
+      sets.push("last_heartbeat = ?");
+      values.push(updates.lastHeartbeat?.toISOString() ?? null);
+    }
+    if (updates.processState !== undefined) {
+      sets.push("process_state = ?");
+      values.push(updates.processState);
+    }
+
+    if (sets.length === 0) return;
+
+    values.push(jobId);
+    this.db.run(`UPDATE jobs SET ${sets.join(", ")} WHERE id = ?`, values);
+  }
+
+  async delete(jobId: string): Promise<boolean> {
+    const result = this.db.run(`DELETE FROM jobs WHERE id = ?`, [jobId]);
+    return result.changes > 0;
+  }
+
+  async getPending(limit: number = 100): Promise<Job[]> {
+    const rows = this.db
+      .query(`SELECT * FROM jobs WHERE status = 'pending' ORDER BY created_at LIMIT ?`)
+      .all(limit) as any[];
+    return rows.map((r) => this.rowToJob(r));
+  }
+
+  async getScheduledReady(now: Date): Promise<Job[]> {
+    const rows = this.db
+      .query(`SELECT * FROM jobs WHERE status = 'scheduled' AND run_at <= ? ORDER BY run_at`)
+      .all(now.toISOString()) as any[];
+    return rows.map((r) => this.rowToJob(r));
+  }
+
+  async getByName(name: string, status?: JobStatus): Promise<Job[]> {
+    let query = `SELECT * FROM jobs WHERE name = ?`;
+    const params: any[] = [name];
+
+    if (status) {
+      query += ` AND status = ?`;
+      params.push(status);
+    }
+
+    query += ` ORDER BY created_at DESC`;
+
+    const rows = this.db.query(query).all(...params) as any[];
+    return rows.map((r) => this.rowToJob(r));
+  }
+
+  async getRunningExternal(): Promise<Job[]> {
+    const rows = this.db
+      .query(`SELECT * FROM jobs WHERE external = 1 AND status = 'running'`)
+      .all() as any[];
+    return rows.map((r) => this.rowToJob(r));
+  }
+
+  async getOrphanedExternal(): Promise<Job[]> {
+    // Get external jobs that were running when server died
+    const rows = this.db
+      .query(
+        `SELECT * FROM jobs WHERE external = 1 AND status = 'running'
+         AND (process_state = 'running' OR process_state = 'orphaned' OR process_state = 'spawning')`
+      )
+      .all() as any[];
+    return rows.map((r) => this.rowToJob(r));
+  }
+
+  private rowToJob(row: any): Job {
+    return {
+      id: row.id,
+      name: row.name,
+      data: JSON.parse(row.data),
+      status: row.status as JobStatus,
+      createdAt: new Date(row.created_at),
+      runAt: row.run_at ? new Date(row.run_at) : undefined,
+      startedAt: row.started_at ? new Date(row.started_at) : undefined,
+      completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
+      result: row.result ? JSON.parse(row.result) : undefined,
+      error: row.error ?? undefined,
+      attempts: row.attempts,
+      maxAttempts: row.max_attempts,
+      // External job fields
+      external: row.external === 1 ? true : undefined,
+      pid: row.pid ?? undefined,
+      socketPath: row.socket_path ?? undefined,
+      tcpPort: row.tcp_port ?? undefined,
+      lastHeartbeat: row.last_heartbeat ? new Date(row.last_heartbeat) : undefined,
+      processState: row.process_state as ExternalJobProcessState | undefined,
+    };
+  }
+
+  /** Clean up old completed/failed jobs */
+  private cleanup(): void {
+    if (this.cleanupDays <= 0) return;
+
+    try {
+      const cutoff = new Date();
+      cutoff.setDate(cutoff.getDate() - this.cleanupDays);
+
+      const result = this.db.run(
+        `DELETE FROM jobs WHERE (status = 'completed' OR status = 'failed') AND completed_at < ?`,
+        [cutoff.toISOString()]
+      );
+
+      if (result.changes > 0) {
+        console.log(`[Jobs] Cleaned up ${result.changes} old jobs`);
+      }
+    } catch (err) {
+      console.error("[Jobs] Cleanup error:", err);
+    }
+  }
+
+  /** Stop the adapter and cleanup timer */
+  stop(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+}

package/src/core/jobs.ts

@@ -25,6 +25,7 @@ import {
   createExternalJobSocketServer,
   type ExternalJobSocketServer,
 } from "./external-job-socket";
+import { SqliteJobAdapter } from "./job-adapter-sqlite";
 
 export type JobStatus = "pending" | "running" | "completed" | "failed" | "scheduled";
 
@@ -82,6 +83,13 @@ export interface JobsConfig {
   maxAttempts?: number; // Default retry attempts, default 3
   /** External jobs configuration */
   external?: ExternalJobsConfig;
+  /**
+   * Use SQLite for persistence (default: true when external jobs are used)
+   * Set to false to use MemoryJobAdapter (not recommended for production)
+   */
+  persist?: boolean;
+  /** SQLite database path (default: .donkeylabs/jobs.db) */
+  dbPath?: string;
 }
 
 export interface Jobs {
@@ -188,6 +196,7 @@ export class MemoryJobAdapter implements JobAdapter {
 
 class JobsImpl implements Jobs {
   private adapter: JobAdapter;
+  private sqliteAdapter?: SqliteJobAdapter;
   private events?: Events;
   private handlers = new Map<string, JobHandler>();
   private running = false;
@@ -197,6 +206,8 @@ class JobsImpl implements Jobs {
   private concurrency: number;
   private pollInterval: number;
   private defaultMaxAttempts: number;
+  private usePersistence: boolean;
+  private dbPath?: string;
 
   // External jobs support
   private externalConfigs = new Map<string, ExternalJobConfig>();
@@ -205,12 +216,23 @@ class JobsImpl implements Jobs {
   private externalProcesses = new Map<string, { pid: number; timeout?: ReturnType<typeof setTimeout> }>();
 
   constructor(config: JobsConfig = {}) {
-    this.adapter = config.adapter ?? new MemoryJobAdapter();
     this.events = config.events;
     this.concurrency = config.concurrency ?? 5;
     this.pollInterval = config.pollInterval ?? 1000;
     this.defaultMaxAttempts = config.maxAttempts ?? 3;
     this.externalConfig = config.external ?? {};
+    this.usePersistence = config.persist ?? true; // Default to SQLite persistence
+    this.dbPath = config.dbPath;
+
+    // Use provided adapter, or create SQLite adapter if persistence enabled
+    if (config.adapter) {
+      this.adapter = config.adapter;
+    } else if (this.usePersistence) {
+      this.sqliteAdapter = new SqliteJobAdapter({ path: this.dbPath });
+      this.adapter = this.sqliteAdapter;
+    } else {
+      this.adapter = new MemoryJobAdapter();
+    }
   }
 
   register<T = any, R = any>(name: string, handler: JobHandler<T, R>): void {
@@ -362,6 +384,11 @@ class JobsImpl implements Jobs {
       this.socketServer = null;
     }
 
+    // Stop SQLite adapter cleanup timer
+    if (this.sqliteAdapter) {
+      this.sqliteAdapter.stop();
+    }
+
     // Wait for active in-process jobs to complete (with timeout)
     const maxWait = 30000; // 30 seconds
     const startTime = Date.now();
@@ -476,6 +503,9 @@ class JobsImpl implements Jobs {
           console.log(`[Jobs] Found orphaned job ${job.id} with PID ${job.pid}, attempting reconnect`);
           activeJobIds.add(job.id);
 
+          // Reserve the socket path/port to prevent new jobs from using it
+          this.socketServer?.reserve(job.id, job.socketPath, job.tcpPort);
+
           // Try to reconnect to the socket
           const reconnected = await this.socketServer?.reconnect(
             job.id,
@@ -496,7 +526,7 @@ class JobsImpl implements Jobs {
               });
             }
           } else {
-            // Mark as orphaned, but keep tracking
+            // Mark as orphaned, but keep tracking (reservation remains)
             await this.adapter.update(job.id, { processState: "orphaned" });
 
             if (this.events) {
@@ -507,7 +537,7 @@ class JobsImpl implements Jobs {
             }
           }
         } else {
-          // Process is dead, mark job as failed
+          // Process is dead, mark job as failed and release any reservations
           console.log(`[Jobs] Orphaned job ${job.id} process (PID ${job.pid}) is dead`);
           await this.adapter.update(job.id, {
             status: "failed",
@@ -515,6 +545,9 @@ class JobsImpl implements Jobs {
             completedAt: new Date(),
           });
 
+          // Release reservation since the job is done
+          this.socketServer?.release(job.id);
+
           if (this.events) {
             await this.events.emit("job.failed", {
               jobId: job.id,

package/src/core/process-adapter-sqlite.ts

@@ -0,0 +1,282 @@
+/**
+ * Built-in SQLite Process Adapter
+ *
+ * Provides automatic persistence for managed processes, enabling server restart resilience
+ * and orphan recovery without requiring user configuration.
+ */
+
+import { Database } from "bun:sqlite";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { ProcessStatus, ManagedProcess, ProcessConfig } from "./processes";
+
+export interface SqliteProcessAdapterConfig {
+  /** Path to SQLite database file (default: .donkeylabs/processes.db) */
+  path?: string;
+  /** Auto-cleanup stopped processes older than N days (default: 7, 0 to disable) */
+  cleanupDays?: number;
+  /** Cleanup interval in ms (default: 3600000 = 1 hour) */
+  cleanupInterval?: number;
+}
+
+export interface ProcessAdapter {
+  /** Create a new process record */
+  create(process: Omit<ManagedProcess, "id">): Promise<ManagedProcess>;
+  /** Get a process by ID */
+  get(processId: string): Promise<ManagedProcess | null>;
+  /** Update a process record */
+  update(processId: string, updates: Partial<ManagedProcess>): Promise<void>;
+  /** Delete a process record */
+  delete(processId: string): Promise<boolean>;
+  /** Get all processes by name */
+  getByName(name: string): Promise<ManagedProcess[]>;
+  /** Get all running processes */
+  getRunning(): Promise<ManagedProcess[]>;
+  /** Get orphaned processes (status="running" from before crash) */
+  getOrphaned(): Promise<ManagedProcess[]>;
+  /** Stop the adapter and cleanup timer */
+  stop(): void;
+}
+
+export class SqliteProcessAdapter implements ProcessAdapter {
+  private db: Database;
+  private initialized = false;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+  private cleanupDays: number;
+
+  constructor(config: SqliteProcessAdapterConfig = {}) {
+    const dbPath = config.path ?? ".donkeylabs/processes.db";
+    this.cleanupDays = config.cleanupDays ?? 7;
+
+    // Ensure directory exists
+    this.ensureDir(dbPath);
+
+    this.db = new Database(dbPath);
+    this.init();
+
+    // Start cleanup timer
+    if (this.cleanupDays > 0) {
+      const interval = config.cleanupInterval ?? 3600000; // 1 hour
+      this.cleanupTimer = setInterval(() => this.cleanup(), interval);
+      // Run cleanup on startup
+      this.cleanup();
+    }
+  }
+
+  private ensureDir(dbPath: string): void {
+    const dir = dirname(dbPath);
+    if (dir && dir !== ".") {
+      // Sync mkdir for constructor
+      try {
+        Bun.spawnSync(["mkdir", "-p", dir]);
+      } catch {
+        // Directory may already exist
+      }
+    }
+  }
+
+  private init(): void {
+    if (this.initialized) return;
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS processes (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        pid INTEGER,
+        socket_path TEXT,
+        tcp_port INTEGER,
+        status TEXT NOT NULL DEFAULT 'stopped',
+        config TEXT NOT NULL,
+        metadata TEXT,
+        created_at TEXT NOT NULL,
+        started_at TEXT,
+        stopped_at TEXT,
+        last_heartbeat TEXT,
+        restart_count INTEGER DEFAULT 0,
+        consecutive_failures INTEGER DEFAULT 0,
+        error TEXT
+      )
+    `);
+
+    // Indexes for efficient queries
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_processes_status ON processes(status)`);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_processes_name ON processes(name)`);
+    this.db.run(`CREATE INDEX IF NOT EXISTS idx_processes_name_status ON processes(name, status)`);
+
+    this.initialized = true;
+  }
+
+  async create(process: Omit<ManagedProcess, "id">): Promise<ManagedProcess> {
+    const id = `proc_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    this.db.run(
+      `INSERT INTO processes (
+        id, name, pid, socket_path, tcp_port, status, config, metadata,
+        created_at, started_at, stopped_at, last_heartbeat,
+        restart_count, consecutive_failures, error
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        id,
+        process.name,
+        process.pid ?? null,
+        process.socketPath ?? null,
+        process.tcpPort ?? null,
+        process.status,
+        JSON.stringify(process.config),
+        process.metadata ? JSON.stringify(process.metadata) : null,
+        process.createdAt.toISOString(),
+        process.startedAt?.toISOString() ?? null,
+        process.stoppedAt?.toISOString() ?? null,
+        process.lastHeartbeat?.toISOString() ?? null,
+        process.restartCount ?? 0,
+        process.consecutiveFailures ?? 0,
+        process.error ?? null,
+      ]
+    );
+
+    return { ...process, id };
+  }
+
+  async get(processId: string): Promise<ManagedProcess | null> {
+    const row = this.db.query(`SELECT * FROM processes WHERE id = ?`).get(processId) as any;
+    if (!row) return null;
+    return this.rowToProcess(row);
+  }
+
+  async update(processId: string, updates: Partial<ManagedProcess>): Promise<void> {
+    const sets: string[] = [];
+    const values: any[] = [];
+
+    if (updates.pid !== undefined) {
+      sets.push("pid = ?");
+      values.push(updates.pid);
+    }
+    if (updates.socketPath !== undefined) {
+      sets.push("socket_path = ?");
+      values.push(updates.socketPath);
+    }
+    if (updates.tcpPort !== undefined) {
+      sets.push("tcp_port = ?");
+      values.push(updates.tcpPort);
+    }
+    if (updates.status !== undefined) {
+      sets.push("status = ?");
+      values.push(updates.status);
+    }
+    if (updates.config !== undefined) {
+      sets.push("config = ?");
+      values.push(JSON.stringify(updates.config));
+    }
+    if (updates.metadata !== undefined) {
+      sets.push("metadata = ?");
+      values.push(updates.metadata ? JSON.stringify(updates.metadata) : null);
+    }
+    if (updates.startedAt !== undefined) {
+      sets.push("started_at = ?");
+      values.push(updates.startedAt?.toISOString() ?? null);
+    }
+    if (updates.stoppedAt !== undefined) {
+      sets.push("stopped_at = ?");
+      values.push(updates.stoppedAt?.toISOString() ?? null);
+    }
+    if (updates.lastHeartbeat !== undefined) {
+      sets.push("last_heartbeat = ?");
+      values.push(updates.lastHeartbeat?.toISOString() ?? null);
+    }
+    if (updates.restartCount !== undefined) {
+      sets.push("restart_count = ?");
+      values.push(updates.restartCount);
+    }
+    if (updates.consecutiveFailures !== undefined) {
+      sets.push("consecutive_failures = ?");
+      values.push(updates.consecutiveFailures);
+    }
+    if (updates.error !== undefined) {
+      sets.push("error = ?");
+      values.push(updates.error);
+    }
+
+    if (sets.length === 0) return;
+
+    values.push(processId);
+    this.db.run(`UPDATE processes SET ${sets.join(", ")} WHERE id = ?`, values);
+  }
+
+  async delete(processId: string): Promise<boolean> {
+    const result = this.db.run(`DELETE FROM processes WHERE id = ?`, [processId]);
+    return result.changes > 0;
+  }
+
+  async getByName(name: string): Promise<ManagedProcess[]> {
+    const rows = this.db
+      .query(`SELECT * FROM processes WHERE name = ? ORDER BY created_at DESC`)
+      .all(name) as any[];
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  async getRunning(): Promise<ManagedProcess[]> {
+    const rows = this.db
+      .query(`SELECT * FROM processes WHERE status = 'running' OR status = 'spawning'`)
+      .all() as any[];
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  async getOrphaned(): Promise<ManagedProcess[]> {
+    // Get processes that were running or spawning when server died
+    const rows = this.db
+      .query(
+        `SELECT * FROM processes WHERE status IN ('running', 'spawning', 'orphaned')`
+      )
+      .all() as any[];
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  private rowToProcess(row: any): ManagedProcess {
+    return {
+      id: row.id,
+      name: row.name,
+      pid: row.pid ?? undefined,
+      socketPath: row.socket_path ?? undefined,
+      tcpPort: row.tcp_port ?? undefined,
+      status: row.status as ProcessStatus,
+      config: JSON.parse(row.config),
+      metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+      createdAt: new Date(row.created_at),
+      startedAt: row.started_at ? new Date(row.started_at) : undefined,
+      stoppedAt: row.stopped_at ? new Date(row.stopped_at) : undefined,
+      lastHeartbeat: row.last_heartbeat ? new Date(row.last_heartbeat) : undefined,
+      restartCount: row.restart_count ?? 0,
+      consecutiveFailures: row.consecutive_failures ?? 0,
+      error: row.error ?? undefined,
+    };
+  }
+
+  /** Clean up old stopped/crashed processes */
+  private cleanup(): void {
+    if (this.cleanupDays <= 0) return;
+
+    try {
+      const cutoff = new Date();
+      cutoff.setDate(cutoff.getDate() - this.cleanupDays);
+
+      const result = this.db.run(
+        `DELETE FROM processes WHERE status IN ('stopped', 'crashed', 'dead') AND stopped_at < ?`,
+        [cutoff.toISOString()]
+      );
+
+      if (result.changes > 0) {
+        console.log(`[Processes] Cleaned up ${result.changes} old process records`);
+      }
+    } catch (err) {
+      console.error("[Processes] Cleanup error:", err);
+    }
+  }
+
+  /** Stop the adapter and cleanup timer */
+  stop(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+}