@donkeylabs/server 0.4.7 → 0.4.8

package/src/core/external-job-socket.ts

@@ -0,0 +1,356 @@
+// External Job Socket Server
+// Handles bidirectional communication with external job processes via Unix sockets (or TCP on Windows)
+
+import { mkdir, rm, readdir, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Server as NetServer, Socket } from "node:net";
+import { createServer as createNetServer } from "node:net";
+import type {
+  AnyExternalJobMessage,
+  ExternalJobsConfig,
+} from "./external-jobs";
+import { parseJobMessage } from "./external-jobs";
+
+// ============================================
+// Types
+// ============================================
+
+export interface SocketServerOptions {
+  /** Directory for Unix sockets */
+  socketDir: string;
+  /** TCP port range for Windows fallback */
+  tcpPortRange: [number, number];
+  /** Callback when a message is received */
+  onMessage: (message: AnyExternalJobMessage) => void;
+  /** Callback when a connection is established */
+  onConnect?: (jobId: string) => void;
+  /** Callback when a connection is closed */
+  onDisconnect?: (jobId: string) => void;
+  /** Callback for errors */
+  onError?: (error: Error, jobId?: string) => void;
+}
+
+export interface ExternalJobSocketServer {
+  /** Create a new socket for a job (returns socket path or TCP port) */
+  createSocket(jobId: string): Promise<{ socketPath?: string; tcpPort?: number }>;
+  /** Close a specific job's socket */
+  closeSocket(jobId: string): Promise<void>;
+  /** Get all active job connections */
+  getActiveConnections(): string[];
+  /** Attempt to reconnect to an existing socket */
+  reconnect(jobId: string, socketPath?: string, tcpPort?: number): Promise<boolean>;
+  /** Shutdown all sockets and cleanup */
+  shutdown(): Promise<void>;
+  /** Clean orphaned socket files from a previous run */
+  cleanOrphanedSockets(activeJobIds: Set<string>): Promise<void>;
+}
+
+// ============================================
+// Implementation
+// ============================================
+
+export class ExternalJobSocketServerImpl implements ExternalJobSocketServer {
+  private socketDir: string;
+  private tcpPortRange: [number, number];
+  private onMessage: (message: AnyExternalJobMessage) => void;
+  private onConnect?: (jobId: string) => void;
+  private onDisconnect?: (jobId: string) => void;
+  private onError?: (error: Error, jobId?: string) => void;
+
+  // Map of jobId -> server instance
+  private servers = new Map<string, NetServer>();
+  // Map of jobId -> active client socket
+  private clientSockets = new Map<string, Socket>();
+  // Map of jobId -> socket path
+  private socketPaths = new Map<string, string>();
+  // Map of jobId -> TCP port
+  private tcpPorts = new Map<string, number>();
+  // Track used TCP ports
+  private usedPorts = new Set<number>();
+
+  private isWindows = process.platform === "win32";
+
+  constructor(options: SocketServerOptions) {
+    this.socketDir = options.socketDir;
+    this.tcpPortRange = options.tcpPortRange;
+    this.onMessage = options.onMessage;
+    this.onConnect = options.onConnect;
+    this.onDisconnect = options.onDisconnect;
+    this.onError = options.onError;
+  }
+
+  async createSocket(jobId: string): Promise<{ socketPath?: string; tcpPort?: number }> {
+    // Ensure socket directory exists (only for Unix)
+    if (!this.isWindows) {
+      await mkdir(this.socketDir, { recursive: true });
+    }
+
+    if (this.isWindows) {
+      return this.createTcpServer(jobId);
+    } else {
+      return this.createUnixServer(jobId);
+    }
+  }
+
+  private async createUnixServer(jobId: string): Promise<{ socketPath: string }> {
+    const socketPath = join(this.socketDir, `job_${jobId}.sock`);
+
+    // Remove existing socket file if it exists
+    if (existsSync(socketPath)) {
+      await unlink(socketPath);
+    }
+
+    return new Promise((resolve, reject) => {
+      const server = createNetServer((socket) => {
+        this.handleConnection(jobId, socket);
+      });
+
+      server.on("error", (err) => {
+        this.onError?.(err, jobId);
+        reject(err);
+      });
+
+      server.listen(socketPath, () => {
+        this.servers.set(jobId, server);
+        this.socketPaths.set(jobId, socketPath);
+        resolve({ socketPath });
+      });
+    });
+  }
+
+  private async createTcpServer(jobId: string): Promise<{ tcpPort: number }> {
+    const port = await this.findAvailablePort();
+
+    return new Promise((resolve, reject) => {
+      const server = createNetServer((socket) => {
+        this.handleConnection(jobId, socket);
+      });
+
+      server.on("error", (err) => {
+        this.usedPorts.delete(port);
+        this.onError?.(err, jobId);
+        reject(err);
+      });
+
+      server.listen(port, "127.0.0.1", () => {
+        this.servers.set(jobId, server);
+        this.tcpPorts.set(jobId, port);
+        this.usedPorts.add(port);
+        resolve({ tcpPort: port });
+      });
+    });
+  }
+
+  private async findAvailablePort(): Promise<number> {
+    const [minPort, maxPort] = this.tcpPortRange;
+
+    // Try random ports within range
+    for (let i = 0; i < 100; i++) {
+      const port = minPort + Math.floor(Math.random() * (maxPort - minPort));
+      if (!this.usedPorts.has(port)) {
+        // Check if port is actually available
+        const isAvailable = await this.checkPortAvailable(port);
+        if (isAvailable) {
+          return port;
+        }
+      }
+    }
+
+    throw new Error(
+      `Could not find available port in range ${minPort}-${maxPort}`
+    );
+  }
+
+  private checkPortAvailable(port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+      const server = createNetServer();
+      server.once("error", () => resolve(false));
+      server.once("listening", () => {
+        server.close(() => resolve(true));
+      });
+      server.listen(port, "127.0.0.1");
+    });
+  }
+
+  private handleConnection(jobId: string, socket: Socket): void {
+    // Store the client socket
+    this.clientSockets.set(jobId, socket);
+    this.onConnect?.(jobId);
+
+    let buffer = "";
+
+    socket.on("data", (data) => {
+      buffer += data.toString();
+
+      // Process complete messages (newline-delimited JSON)
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || ""; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        const message = parseJobMessage(line);
+        if (message) {
+          this.onMessage(message);
+        } else {
+          this.onError?.(new Error(`Invalid message: ${line}`), jobId);
+        }
+      }
+    });
+
+    socket.on("error", (err) => {
+      this.onError?.(err, jobId);
+    });
+
+    socket.on("close", () => {
+      this.clientSockets.delete(jobId);
+      this.onDisconnect?.(jobId);
+    });
+  }
+
+  async closeSocket(jobId: string): Promise<void> {
+    // Close client socket
+    const clientSocket = this.clientSockets.get(jobId);
+    if (clientSocket) {
+      clientSocket.destroy();
+      this.clientSockets.delete(jobId);
+    }
+
+    // Close server
+    const server = this.servers.get(jobId);
+    if (server) {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+      this.servers.delete(jobId);
+    }
+
+    // Clean up socket file (Unix only)
+    const socketPath = this.socketPaths.get(jobId);
+    if (socketPath && existsSync(socketPath)) {
+      await unlink(socketPath).catch(() => {
+        // Ignore errors during cleanup
+      });
+    }
+    this.socketPaths.delete(jobId);
+
+    // Clean up port tracking (TCP)
+    const port = this.tcpPorts.get(jobId);
+    if (port) {
+      this.usedPorts.delete(port);
+      this.tcpPorts.delete(jobId);
+    }
+  }
+
+  getActiveConnections(): string[] {
+    return Array.from(this.clientSockets.keys());
+  }
+
+  async reconnect(
+    jobId: string,
+    socketPath?: string,
+    tcpPort?: number
+  ): Promise<boolean> {
+    // Check if we already have a connection
+    if (this.clientSockets.has(jobId)) {
+      return true;
+    }
+
+    // For Unix sockets, check if the socket file exists
+    if (socketPath && existsSync(socketPath)) {
+      // The external process should still be connected to this socket
+      // We need to create a server to listen for the existing connection
+      // However, this is tricky because the original server is gone
+      // The reconnection strategy depends on the external process behavior
+
+      // For now, we'll just check if the socket exists
+      // The external process should attempt to reconnect if configured
+      return false;
+    }
+
+    // For TCP, we can't easily reconnect without the process knowing
+    return false;
+  }
+
+  async shutdown(): Promise<void> {
+    // Close all client sockets
+    for (const socket of this.clientSockets.values()) {
+      socket.destroy();
+    }
+    this.clientSockets.clear();
+
+    // Close all servers
+    const closePromises = Array.from(this.servers.values()).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        })
+    );
+    await Promise.all(closePromises);
+    this.servers.clear();
+
+    // Clean up socket files
+    for (const socketPath of this.socketPaths.values()) {
+      if (existsSync(socketPath)) {
+        await unlink(socketPath).catch(() => {});
+      }
+    }
+    this.socketPaths.clear();
+    this.tcpPorts.clear();
+    this.usedPorts.clear();
+  }
+
+  async cleanOrphanedSockets(activeJobIds: Set<string>): Promise<void> {
+    if (this.isWindows) {
+      // No socket files to clean on Windows
+      return;
+    }
+
+    if (!existsSync(this.socketDir)) {
+      return;
+    }
+
+    try {
+      const files = await readdir(this.socketDir);
+
+      for (const file of files) {
+        // Match socket files: job_<jobId>.sock
+        const match = file.match(/^job_(.+)\.sock$/);
+        if (match) {
+          const jobId = match[1]!;
+          if (!activeJobIds.has(jobId)) {
+            // This socket file doesn't correspond to any active job
+            const socketPath = join(this.socketDir, file);
+            await unlink(socketPath).catch(() => {});
+          }
+        }
+      }
+    } catch {
+      // Ignore errors during cleanup
+    }
+  }
+}
+
+// ============================================
+// Factory Function
+// ============================================
+
+export function createExternalJobSocketServer(
+  config: ExternalJobsConfig,
+  callbacks: {
+    onMessage: (message: AnyExternalJobMessage) => void;
+    onConnect?: (jobId: string) => void;
+    onDisconnect?: (jobId: string) => void;
+    onError?: (error: Error, jobId?: string) => void;
+  }
+): ExternalJobSocketServer {
+  return new ExternalJobSocketServerImpl({
+    socketDir: config.socketDir ?? "/tmp/donkeylabs-jobs",
+    tcpPortRange: config.tcpPortRange ?? [49152, 65535],
+    onMessage: callbacks.onMessage,
+    onConnect: callbacks.onConnect,
+    onDisconnect: callbacks.onDisconnect,
+    onError: callbacks.onError,
+  });
+}

package/src/core/external-jobs.ts

@@ -0,0 +1,237 @@
+// External Jobs Service
+// Extends the Jobs system to support external processes written in any language
+
+import type { Events } from "./events";
+import type { Job, JobAdapter } from "./jobs";
+
+// ============================================
+// Message Protocol Types
+// ============================================
+
+export type ExternalJobMessageType =
+  | "started"
+  | "progress"
+  | "heartbeat"
+  | "log"
+  | "completed"
+  | "failed";
+
+export interface ExternalJobMessage {
+  type: ExternalJobMessageType;
+  jobId: string;
+  timestamp: number;
+}
+
+export interface StartedMessage extends ExternalJobMessage {
+  type: "started";
+}
+
+export interface ProgressMessage extends ExternalJobMessage {
+  type: "progress";
+  percent: number;
+  message?: string;
+  data?: Record<string, any>;
+}
+
+export interface HeartbeatMessage extends ExternalJobMessage {
+  type: "heartbeat";
+}
+
+export interface LogMessage extends ExternalJobMessage {
+  type: "log";
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  data?: Record<string, any>;
+}
+
+export interface CompletedMessage extends ExternalJobMessage {
+  type: "completed";
+  result?: any;
+}
+
+export interface FailedMessage extends ExternalJobMessage {
+  type: "failed";
+  error: string;
+  stack?: string;
+}
+
+export type AnyExternalJobMessage =
+  | StartedMessage
+  | ProgressMessage
+  | HeartbeatMessage
+  | LogMessage
+  | CompletedMessage
+  | FailedMessage;
+
+// ============================================
+// External Job Configuration
+// ============================================
+
+export interface ExternalJobConfig {
+  /** Command to execute (e.g., "python", "node", "./script.sh") */
+  command: string;
+  /** Arguments to pass to the command */
+  args?: string[];
+  /** Working directory for the process */
+  cwd?: string;
+  /** Environment variables to set */
+  env?: Record<string, string>;
+  /** Heartbeat timeout in milliseconds (default: 30000) */
+  heartbeatTimeout?: number;
+  /** Job timeout in milliseconds (optional) */
+  timeout?: number;
+}
+
+// ============================================
+// External Job State
+// ============================================
+
+export type ExternalJobProcessState =
+  | "spawning"
+  | "running"
+  | "orphaned"
+  | "reconnecting";
+
+export interface ExternalJob extends Job {
+  /** Flag indicating this is an external job */
+  external: true;
+  /** Process ID of the external process */
+  pid?: number;
+  /** Unix socket path for communication */
+  socketPath?: string;
+  /** TCP port for Windows fallback */
+  tcpPort?: number;
+  /** Timestamp of last heartbeat */
+  lastHeartbeat?: Date;
+  /** Current process state */
+  processState?: ExternalJobProcessState;
+}
+
+// ============================================
+// External Jobs Configuration
+// ============================================
+
+export interface ExternalJobsConfig {
+  /** Directory for Unix sockets (default: /tmp/donkeylabs-jobs) */
+  socketDir?: string;
+  /** TCP port range for Windows fallback (default: [49152, 65535]) */
+  tcpPortRange?: [number, number];
+  /** Default heartbeat timeout in ms (default: 30000) */
+  defaultHeartbeatTimeout?: number;
+  /** Heartbeat check interval in ms (default: 10000) */
+  heartbeatCheckInterval?: number;
+}
+
+// ============================================
+// External Job Manager Interface
+// ============================================
+
+export interface ExternalJobManager {
+  /** Register an external job configuration */
+  registerExternal(name: string, config: ExternalJobConfig): void;
+  /** Check if a job is registered as external */
+  isExternal(name: string): boolean;
+  /** Get external job configuration */
+  getExternalConfig(name: string): ExternalJobConfig | undefined;
+  /** Spawn an external job process */
+  spawn(jobId: string, name: string, data: any): Promise<ExternalJob>;
+  /** Handle message from external process */
+  handleMessage(message: AnyExternalJobMessage): Promise<void>;
+  /** Get all running external jobs */
+  getRunningExternal(): Promise<ExternalJob[]>;
+  /** Attempt to reconnect to orphaned jobs on server restart */
+  reconnectOrphaned(): Promise<void>;
+  /** Start the heartbeat monitoring loop */
+  startHeartbeatMonitor(): void;
+  /** Stop the heartbeat monitoring and cleanup */
+  stop(): Promise<void>;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+/**
+ * Check if a process with given PID is still alive
+ */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    // Sending signal 0 doesn't actually send a signal,
+    // it just checks if the process exists and we have permission to signal it
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate a unique socket path for a job
+ */
+export function generateSocketPath(socketDir: string, jobId: string): string {
+  return `${socketDir}/job_${jobId}.sock`;
+}
+
+/**
+ * Parse a message from an external job process
+ */
+export function parseJobMessage(data: string): AnyExternalJobMessage | null {
+  try {
+    const parsed = JSON.parse(data);
+    if (!parsed.type || !parsed.jobId || typeof parsed.timestamp !== "number") {
+      return null;
+    }
+    return parsed as AnyExternalJobMessage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create the initial payload to send to the external process via stdin
+ */
+export function createInitialPayload(
+  jobId: string,
+  name: string,
+  data: any,
+  socketPath: string
+): string {
+  return JSON.stringify({
+    jobId,
+    name,
+    data,
+    socketPath,
+  });
+}
+
+// ============================================
+// Type Guards
+// ============================================
+
+export function isExternalJob(job: Job): job is ExternalJob {
+  return (job as ExternalJob).external === true;
+}
+
+export function isProgressMessage(msg: AnyExternalJobMessage): msg is ProgressMessage {
+  return msg.type === "progress";
+}
+
+export function isHeartbeatMessage(msg: AnyExternalJobMessage): msg is HeartbeatMessage {
+  return msg.type === "heartbeat";
+}
+
+export function isLogMessage(msg: AnyExternalJobMessage): msg is LogMessage {
+  return msg.type === "log";
+}
+
+export function isCompletedMessage(msg: AnyExternalJobMessage): msg is CompletedMessage {
+  return msg.type === "completed";
+}
+
+export function isFailedMessage(msg: AnyExternalJobMessage): msg is FailedMessage {
+  return msg.type === "failed";
+}
+
+export function isStartedMessage(msg: AnyExternalJobMessage): msg is StartedMessage {
+  return msg.type === "started";
+}

package/src/core/index.ts

@@ -47,6 +47,31 @@ export {
   createJobs,
 } from "./jobs";
 
+export {
+  type ExternalJobConfig,
+  type ExternalJob,
+  type ExternalJobProcessState,
+  type ExternalJobsConfig,
+  type ExternalJobManager,
+  type ExternalJobMessage,
+  type ExternalJobMessageType,
+  type AnyExternalJobMessage,
+  type StartedMessage,
+  type ProgressMessage,
+  type HeartbeatMessage,
+  type LogMessage,
+  type CompletedMessage,
+  type FailedMessage,
+  isExternalJob,
+  isProgressMessage,
+  isHeartbeatMessage,
+  isLogMessage,
+  isCompletedMessage,
+  isFailedMessage,
+  isStartedMessage,
+  isProcessAlive,
+} from "./external-jobs";
+
 export {
   type SSE,
   type SSEClient,
@@ -92,3 +117,27 @@ export {
   createErrors,
   createValidationError,
 } from "./errors";
+
+export {
+  type Workflows,
+  type WorkflowsConfig,
+  type WorkflowDefinition,
+  type WorkflowInstance,
+  type WorkflowStatus,
+  type WorkflowContext,
+  type WorkflowAdapter,
+  type StepDefinition,
+  type StepType,
+  type StepStatus,
+  type StepResult,
+  type TaskStepDefinition,
+  type ParallelStepDefinition,
+  type ChoiceStepDefinition,
+  type ChoiceCondition,
+  type PassStepDefinition,
+  type RetryConfig,
+  WorkflowBuilder,
+  MemoryWorkflowAdapter,
+  workflow,
+  createWorkflows,
+} from "./workflows";