@donkeylabs/server 0.6.4 → 1.0.0

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

@@ -0,0 +1,260 @@
+/**
+ * Kysely Process Adapter
+ *
+ * Implements the ProcessAdapter interface using Kysely for the shared app database.
+ * This replaces the standalone SqliteProcessAdapter that used a separate .donkeylabs/processes.db file.
+ */
+
+import type { Kysely } from "kysely";
+import type { ProcessAdapter } from "./process-adapter-sqlite";
+import type { ProcessStatus, ManagedProcess, ProcessConfig } from "./processes";
+
+export interface KyselyProcessAdapterConfig {
+  /** 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;
+}
+
+// Table type for Kysely
+interface ProcessesTable {
+  id: string;
+  name: string;
+  pid: number | null;
+  socket_path: string | null;
+  tcp_port: number | null;
+  status: string;
+  config: string;
+  metadata: string | null;
+  created_at: string;
+  started_at: string | null;
+  stopped_at: string | null;
+  last_heartbeat: string | null;
+  restart_count: number;
+  consecutive_failures: number;
+  error: string | null;
+}
+
+interface Database {
+  __donkeylabs_processes__: ProcessesTable;
+}
+
+export class KyselyProcessAdapter implements ProcessAdapter {
+  private db: Kysely<Database>;
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+  private cleanupDays: number;
+
+  constructor(db: Kysely<any>, config: KyselyProcessAdapterConfig = {}) {
+    this.db = db as Kysely<Database>;
+    this.cleanupDays = config.cleanupDays ?? 7;
+
+    // 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();
+    }
+  }
+
+  async create(process: Omit<ManagedProcess, "id">): Promise<ManagedProcess> {
+    const id = `proc_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    await this.db
+      .insertInto("__donkeylabs_processes__")
+      .values({
+        id,
+        name: process.name,
+        pid: process.pid ?? null,
+        socket_path: process.socketPath ?? null,
+        tcp_port: process.tcpPort ?? null,
+        status: process.status,
+        config: JSON.stringify(process.config),
+        metadata: process.metadata ? JSON.stringify(process.metadata) : null,
+        created_at: process.createdAt.toISOString(),
+        started_at: process.startedAt?.toISOString() ?? null,
+        stopped_at: process.stoppedAt?.toISOString() ?? null,
+        last_heartbeat: process.lastHeartbeat?.toISOString() ?? null,
+        restart_count: process.restartCount ?? 0,
+        consecutive_failures: process.consecutiveFailures ?? 0,
+        error: process.error ?? null,
+      })
+      .execute();
+
+    return { ...process, id };
+  }
+
+  async get(processId: string): Promise<ManagedProcess | null> {
+    const row = await this.db
+      .selectFrom("__donkeylabs_processes__")
+      .selectAll()
+      .where("id", "=", processId)
+      .executeTakeFirst();
+
+    if (!row) return null;
+    return this.rowToProcess(row);
+  }
+
+  async update(processId: string, updates: Partial<ManagedProcess>): Promise<void> {
+    const updateData: Partial<ProcessesTable> = {};
+
+    if (updates.pid !== undefined) {
+      updateData.pid = updates.pid;
+    }
+    if (updates.socketPath !== undefined) {
+      updateData.socket_path = updates.socketPath;
+    }
+    if (updates.tcpPort !== undefined) {
+      updateData.tcp_port = updates.tcpPort;
+    }
+    if (updates.status !== undefined) {
+      updateData.status = updates.status;
+    }
+    if (updates.config !== undefined) {
+      updateData.config = JSON.stringify(updates.config);
+    }
+    if (updates.metadata !== undefined) {
+      updateData.metadata = updates.metadata ? JSON.stringify(updates.metadata) : null;
+    }
+    if (updates.startedAt !== undefined) {
+      updateData.started_at = updates.startedAt?.toISOString() ?? null;
+    }
+    if (updates.stoppedAt !== undefined) {
+      updateData.stopped_at = updates.stoppedAt?.toISOString() ?? null;
+    }
+    if (updates.lastHeartbeat !== undefined) {
+      updateData.last_heartbeat = updates.lastHeartbeat?.toISOString() ?? null;
+    }
+    if (updates.restartCount !== undefined) {
+      updateData.restart_count = updates.restartCount;
+    }
+    if (updates.consecutiveFailures !== undefined) {
+      updateData.consecutive_failures = updates.consecutiveFailures;
+    }
+    if (updates.error !== undefined) {
+      updateData.error = updates.error;
+    }
+
+    if (Object.keys(updateData).length === 0) return;
+
+    await this.db
+      .updateTable("__donkeylabs_processes__")
+      .set(updateData)
+      .where("id", "=", processId)
+      .execute();
+  }
+
+  async delete(processId: string): Promise<boolean> {
+    // Check if exists first since BunSqliteDialect doesn't report numDeletedRows properly
+    const exists = await this.db
+      .selectFrom("__donkeylabs_processes__")
+      .select("id")
+      .where("id", "=", processId)
+      .executeTakeFirst();
+
+    if (!exists) return false;
+
+    await this.db
+      .deleteFrom("__donkeylabs_processes__")
+      .where("id", "=", processId)
+      .execute();
+
+    return true;
+  }
+
+  async getByName(name: string): Promise<ManagedProcess[]> {
+    const rows = await this.db
+      .selectFrom("__donkeylabs_processes__")
+      .selectAll()
+      .where("name", "=", name)
+      .orderBy("created_at", "desc")
+      .execute();
+
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  async getRunning(): Promise<ManagedProcess[]> {
+    const rows = await this.db
+      .selectFrom("__donkeylabs_processes__")
+      .selectAll()
+      .where((eb) =>
+        eb.or([eb("status", "=", "running"), eb("status", "=", "spawning")])
+      )
+      .execute();
+
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  async getOrphaned(): Promise<ManagedProcess[]> {
+    const rows = await this.db
+      .selectFrom("__donkeylabs_processes__")
+      .selectAll()
+      .where((eb) =>
+        eb.or([
+          eb("status", "=", "running"),
+          eb("status", "=", "spawning"),
+          eb("status", "=", "orphaned"),
+        ])
+      )
+      .execute();
+
+    return rows.map((r) => this.rowToProcess(r));
+  }
+
+  private rowToProcess(row: ProcessesTable): 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) as ProcessConfig,
+      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 async cleanup(): Promise<void> {
+    if (this.cleanupDays <= 0) return;
+
+    try {
+      const cutoff = new Date();
+      cutoff.setDate(cutoff.getDate() - this.cleanupDays);
+
+      const result = await this.db
+        .deleteFrom("__donkeylabs_processes__")
+        .where((eb) =>
+          eb.or([
+            eb("status", "=", "stopped"),
+            eb("status", "=", "crashed"),
+            eb("status", "=", "dead"),
+          ])
+        )
+        .where("stopped_at", "<", cutoff.toISOString())
+        .execute();
+
+      const numDeleted = Number(result[0]?.numDeletedRows ?? 0);
+      if (numDeleted > 0) {
+        console.log(`[Processes] Cleaned up ${numDeleted} 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;
+    }
+  }
+}

package/src/core/websocket.ts

@@ -0,0 +1,352 @@
+/**
+ * WebSocket Core Service
+ *
+ * Provides bidirectional real-time communication using Bun's native WebSocket support.
+ * This is an in-memory service (no persistence needed) for high-frequency messaging.
+ */
+
+import type { ServerWebSocket } from "bun";
+
+// ============================================
+// Types
+// ============================================
+
+export interface WebSocketClient {
+  id: string;
+  socket: ServerWebSocket<WebSocketData>;
+  channels: Set<string>;
+  metadata?: Record<string, any>;
+  connectedAt: Date;
+  lastMessageAt?: Date;
+}
+
+export interface WebSocketData {
+  clientId: string;
+}
+
+export interface WebSocketMessage {
+  event: string;
+  data: any;
+  channel?: string;
+}
+
+export type WebSocketMessageHandler = (
+  clientId: string,
+  event: string,
+  data: any
+) => void | Promise<void>;
+
+// ============================================
+// Service Interface
+// ============================================
+
+export interface WebSocketService {
+  /** Broadcast a message to all clients in a channel */
+  broadcast(channel: string, event: string, data: any): void;
+  /** Broadcast a message to all connected clients */
+  broadcastAll(event: string, data: any): void;
+  /** Send a message to a specific client */
+  send(clientId: string, event: string, data: any): boolean;
+  /** Subscribe a client to a channel */
+  subscribe(clientId: string, channel: string): boolean;
+  /** Unsubscribe a client from a channel */
+  unsubscribe(clientId: string, channel: string): boolean;
+  /** Register a message handler */
+  onMessage(handler: WebSocketMessageHandler): void;
+  /** Get all clients in a channel */
+  getClients(channel?: string): string[];
+  /** Get client count */
+  getClientCount(channel?: string): number;
+  /** Check if a client is connected */
+  isConnected(clientId: string): boolean;
+  /** Get client metadata */
+  getClientMetadata(clientId: string): Record<string, any> | undefined;
+  /** Set client metadata */
+  setClientMetadata(clientId: string, metadata: Record<string, any>): boolean;
+  /** Handle an incoming WebSocket connection (for server integration) */
+  handleUpgrade(
+    clientId: string,
+    socket: ServerWebSocket<WebSocketData>,
+    metadata?: Record<string, any>
+  ): void;
+  /** Handle a client disconnection */
+  handleClose(clientId: string): void;
+  /** Handle an incoming message */
+  handleMessage(clientId: string, message: string | Buffer): void;
+  /** Close all connections and cleanup */
+  shutdown(): void;
+}
+
+// ============================================
+// Configuration
+// ============================================
+
+export interface WebSocketConfig {
+  /** Maximum clients per channel (default: unlimited) */
+  maxClientsPerChannel?: number;
+  /** Ping interval in ms to keep connections alive (default: 30000) */
+  pingInterval?: number;
+  /** Maximum message size in bytes (default: 1MB) */
+  maxMessageSize?: number;
+}
+
+// ============================================
+// Implementation
+// ============================================
+
+class WebSocketServiceImpl implements WebSocketService {
+  private clients = new Map<string, WebSocketClient>();
+  private channels = new Map<string, Set<string>>(); // channel -> Set<clientId>
+  private messageHandlers: WebSocketMessageHandler[] = [];
+  private pingTimer?: ReturnType<typeof setInterval>;
+  private maxClientsPerChannel: number;
+  private pingInterval: number;
+  private maxMessageSize: number;
+
+  constructor(config: WebSocketConfig = {}) {
+    this.maxClientsPerChannel = config.maxClientsPerChannel ?? Infinity;
+    this.pingInterval = config.pingInterval ?? 30000;
+    this.maxMessageSize = config.maxMessageSize ?? 1024 * 1024; // 1MB
+
+    // Start ping timer
+    this.startPingTimer();
+  }
+
+  broadcast(channel: string, event: string, data: any): void {
+    const channelClients = this.channels.get(channel);
+    if (!channelClients) return;
+
+    const message = JSON.stringify({ event, data, channel });
+
+    for (const clientId of channelClients) {
+      const client = this.clients.get(clientId);
+      if (client) {
+        try {
+          client.socket.send(message);
+        } catch {
+          // Client may have disconnected
+        }
+      }
+    }
+  }
+
+  broadcastAll(event: string, data: any): void {
+    const message = JSON.stringify({ event, data });
+
+    for (const client of this.clients.values()) {
+      try {
+        client.socket.send(message);
+      } catch {
+        // Client may have disconnected
+      }
+    }
+  }
+
+  send(clientId: string, event: string, data: any): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+
+    try {
+      client.socket.send(JSON.stringify({ event, data }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  subscribe(clientId: string, channel: string): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+
+    // Check max clients per channel
+    let channelClients = this.channels.get(channel);
+    if (!channelClients) {
+      channelClients = new Set();
+      this.channels.set(channel, channelClients);
+    }
+
+    if (channelClients.size >= this.maxClientsPerChannel) {
+      return false;
+    }
+
+    channelClients.add(clientId);
+    client.channels.add(channel);
+    return true;
+  }
+
+  unsubscribe(clientId: string, channel: string): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+
+    client.channels.delete(channel);
+
+    const channelClients = this.channels.get(channel);
+    if (channelClients) {
+      channelClients.delete(clientId);
+      if (channelClients.size === 0) {
+        this.channels.delete(channel);
+      }
+    }
+
+    return true;
+  }
+
+  onMessage(handler: WebSocketMessageHandler): void {
+    this.messageHandlers.push(handler);
+  }
+
+  getClients(channel?: string): string[] {
+    if (channel) {
+      const channelClients = this.channels.get(channel);
+      return channelClients ? Array.from(channelClients) : [];
+    }
+    return Array.from(this.clients.keys());
+  }
+
+  getClientCount(channel?: string): number {
+    if (channel) {
+      return this.channels.get(channel)?.size ?? 0;
+    }
+    return this.clients.size;
+  }
+
+  isConnected(clientId: string): boolean {
+    return this.clients.has(clientId);
+  }
+
+  getClientMetadata(clientId: string): Record<string, any> | undefined {
+    return this.clients.get(clientId)?.metadata;
+  }
+
+  setClientMetadata(clientId: string, metadata: Record<string, any>): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) return false;
+    client.metadata = { ...client.metadata, ...metadata };
+    return true;
+  }
+
+  handleUpgrade(
+    clientId: string,
+    socket: ServerWebSocket<WebSocketData>,
+    metadata?: Record<string, any>
+  ): void {
+    const client: WebSocketClient = {
+      id: clientId,
+      socket,
+      channels: new Set(),
+      metadata,
+      connectedAt: new Date(),
+    };
+
+    this.clients.set(clientId, client);
+    console.log(`[WebSocket] Client connected: ${clientId}`);
+  }
+
+  handleClose(clientId: string): void {
+    const client = this.clients.get(clientId);
+    if (!client) return;
+
+    // Remove from all channels
+    for (const channel of client.channels) {
+      const channelClients = this.channels.get(channel);
+      if (channelClients) {
+        channelClients.delete(clientId);
+        if (channelClients.size === 0) {
+          this.channels.delete(channel);
+        }
+      }
+    }
+
+    this.clients.delete(clientId);
+    console.log(`[WebSocket] Client disconnected: ${clientId}`);
+  }
+
+  handleMessage(clientId: string, message: string | Buffer): void {
+    const client = this.clients.get(clientId);
+    if (!client) return;
+
+    client.lastMessageAt = new Date();
+
+    // Check message size
+    const messageStr = typeof message === "string" ? message : message.toString();
+    if (messageStr.length > this.maxMessageSize) {
+      console.warn(`[WebSocket] Message too large from ${clientId}`);
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(messageStr) as WebSocketMessage;
+      const { event, data } = parsed;
+
+      // Handle built-in events
+      if (event === "subscribe" && data?.channel) {
+        this.subscribe(clientId, data.channel);
+        return;
+      }
+      if (event === "unsubscribe" && data?.channel) {
+        this.unsubscribe(clientId, data.channel);
+        return;
+      }
+      if (event === "ping") {
+        this.send(clientId, "pong", { timestamp: Date.now() });
+        return;
+      }
+
+      // Call registered handlers
+      for (const handler of this.messageHandlers) {
+        try {
+          handler(clientId, event, data);
+        } catch (err) {
+          console.error(`[WebSocket] Message handler error:`, err);
+        }
+      }
+    } catch {
+      console.warn(`[WebSocket] Invalid message from ${clientId}`);
+    }
+  }
+
+  shutdown(): void {
+    // Stop ping timer
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = undefined;
+    }
+
+    // Close all connections
+    for (const client of this.clients.values()) {
+      try {
+        client.socket.close(1000, "Server shutting down");
+      } catch {
+        // Already closed
+      }
+    }
+
+    this.clients.clear();
+    this.channels.clear();
+    this.messageHandlers = [];
+
+    console.log("[WebSocket] Service shutdown complete");
+  }
+
+  private startPingTimer(): void {
+    this.pingTimer = setInterval(() => {
+      const now = Date.now();
+
+      for (const client of this.clients.values()) {
+        try {
+          client.socket.send(JSON.stringify({ event: "ping", data: { timestamp: now } }));
+        } catch {
+          // Client may have disconnected
+        }
+      }
+    }, this.pingInterval);
+  }
+}
+
+// ============================================
+// Factory Function
+// ============================================
+
+export function createWebSocket(config?: WebSocketConfig): WebSocketService {
+  return new WebSocketServiceImpl(config);
+}