@donkeylabs/server 0.5.0 → 0.5.1

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.ts

@@ -1,4 +1,4 @@
-import type { Kysely } from "kysely";
+import { sql, type Kysely } from "kysely";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import type { z } from "zod";
@@ -355,8 +355,53 @@ export class PluginManager {
     this.plugins.set(plugin.name, plugin);
   }
 
+  /**
+   * Ensures the migrations tracking table exists.
+   * This table tracks which migrations have been applied for each plugin.
+   */
+  private async ensureMigrationsTable(): Promise<void> {
+    await this.core.db.schema
+      .createTable("__donkeylabs_migrations__")
+      .ifNotExists()
+      .addColumn("id", "integer", (col) => col.primaryKey().autoIncrement())
+      .addColumn("plugin_name", "text", (col) => col.notNull())
+      .addColumn("migration_name", "text", (col) => col.notNull())
+      .addColumn("executed_at", "text", (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`))
+      .execute();
+
+    // Create unique index for plugin_name + migration_name (if not exists)
+    // Using raw SQL since Kysely doesn't have ifNotExists for indexes
+    await sql`CREATE UNIQUE INDEX IF NOT EXISTS idx_migrations_unique
+              ON __donkeylabs_migrations__(plugin_name, migration_name)`.execute(this.core.db);
+  }
+
+  /**
+   * Checks if a migration has already been applied for a specific plugin.
+   */
+  private async isMigrationApplied(pluginName: string, migrationName: string): Promise<boolean> {
+    const result = await sql<{ count: number }>`
+      SELECT COUNT(*) as count FROM __donkeylabs_migrations__
+      WHERE plugin_name = ${pluginName} AND migration_name = ${migrationName}
+    `.execute(this.core.db);
+    return (result.rows[0]?.count ?? 0) > 0;
+  }
+
+  /**
+   * Records that a migration has been applied for a specific plugin.
+   */
+  private async recordMigration(pluginName: string, migrationName: string): Promise<void> {
+    await sql`
+      INSERT INTO __donkeylabs_migrations__ (plugin_name, migration_name)
+      VALUES (${pluginName}, ${migrationName})
+    `.execute(this.core.db);
+  }
+
   async migrate(): Promise<void> {
     console.log("Running migrations (File-System Based)...");
+
+    // Ensure the migrations tracking table exists
+    await this.ensureMigrationsTable();
+
     const sortedPlugins = this.resolveOrder();
 
     for (const plugin of sortedPlugins) {
@@ -392,22 +437,46 @@ export class PluginManager {
                  console.log(`[Migration] checking plugin: ${pluginName} at ${migrationDir}`);
 
                  for (const file of migrationFiles.sort()) {
+                     // Check if this migration has already been applied
+                     const isApplied = await this.isMigrationApplied(pluginName, file);
+                     if (isApplied) {
+                         console.log(`  - Skipping (already applied): ${file}`);
+                         continue;
+                     }
+
                      console.log(`  - Executing migration: ${file}`);
                      const migrationPath = join(migrationDir, file);
-                     const migration = await import(migrationPath);
+
+                     let migration;
+                     try {
+                         migration = await import(migrationPath);
+                     } catch (importError) {
+                         const err = importError instanceof Error ? importError : new Error(String(importError));
+                         throw new Error(`Failed to import migration ${file}: ${err.message}`);
+                     }
 
                      if (migration.up) {
                          try {
                               await migration.up(this.core.db);
+                              // Record successful migration
+                              await this.recordMigration(pluginName, file);
                               console.log(`    Success`);
                          } catch (e) {
                              console.error(`    Failed to run ${file}:`, e);
+                             throw e; // Stop on migration failure - don't continue with inconsistent state
                          }
                      }
                  }
              }
-        } catch {
-            // Migration directory doesn't exist, skip
+        } catch (e) {
+            // Re-throw migration execution errors (they've already been logged)
+            // Only silently catch directory read errors (ENOENT)
+            const isDirectoryError = e instanceof Error &&
+              ((e as NodeJS.ErrnoException).code === 'ENOENT' ||
+               (e as NodeJS.ErrnoException).code === 'ENOTDIR');
+            if (!isDirectoryError) {
+                throw e;
+            }
         }
     }
   }

package/src/index.ts

@@ -45,6 +45,7 @@ export {
   type InferHandlers,
   type InferMiddleware,
   type InferDependencies,
+  type EventSchemas,
 } from "./core";
 
 // Middleware
@@ -72,3 +73,14 @@ export function defineConfig(config: DonkeylabsConfig): DonkeylabsConfig {
 
 // Re-export HttpError for custom error creation
 export { HttpError } from "./core/errors";
+
+// Workflows (step functions)
+export {
+  workflow,
+  WorkflowBuilder,
+  type WorkflowDefinition,
+  type WorkflowInstance,
+  type WorkflowStatus,
+  type WorkflowContext,
+  type Workflows,
+} from "./core/workflows";