@donkeylabs/server 1.1.17 → 1.1.19

package/src/core/processes.ts

@@ -84,6 +84,21 @@ export interface ManagedProcess {
 export interface ProcessDefinition {
   name: string;
   config: Omit<ProcessConfig, "args"> & { args?: string[] };
+  /**
+   * Event schemas this process can emit.
+   * Events are automatically emitted to ctx.core.events as "process.<name>.<event>"
+   * and broadcast to SSE channel "process:<processId>".
+   *
+   * @example
+   * ```ts
+   * events: {
+   *   progress: z.object({ percent: z.number(), fps: z.number() }),
+   *   complete: z.object({ outputPath: z.string() }),
+   *   error: z.object({ message: z.string() }),
+   * }
+   * ```
+   */
+  events?: Record<string, import("zod").ZodType<any>>;
   /** Called when a message is received from the process */
   onMessage?: (process: ManagedProcess, message: any) => void | Promise<void>;
   /** Called when the process crashes unexpectedly */
@@ -261,7 +276,7 @@ export class ProcessesImpl implements Processes {
       // Create Unix socket
       const { socketPath, tcpPort } = await this.socketServer.createSocket(process.id);
 
-      // Build environment with socket info
+      // Build environment with socket info and metadata
       const env: Record<string, string> = {
         ...config.env,
         DONKEYLABS_PROCESS_ID: process.id,
@@ -272,6 +287,9 @@ export class ProcessesImpl implements Processes {
       if (tcpPort) {
         env.DONKEYLABS_TCP_PORT = tcpPort.toString();
       }
+      if (options?.metadata) {
+        env.DONKEYLABS_METADATA = JSON.stringify(options.metadata);
+      }
 
       // Spawn the process
       const proc = Bun.spawn([config.command, ...(config.args || [])], {
@@ -508,7 +526,32 @@ export class ProcessesImpl implements Processes {
       return;
     }
 
-    // Emit generic message event
+    // Handle typed event messages from ProcessClient.emit()
+    if (type === "event" && message.event) {
+      const eventName = message.event as string;
+      const eventData = message.data ?? {};
+
+      // Emit to events service as "process.<name>.<event>"
+      await this.emitEvent(`process.${proc.name}.${eventName}`, {
+        processId,
+        name: proc.name,
+        event: eventName,
+        data: eventData,
+      });
+
+      // Broadcast to SSE channel "process:<processId>"
+      if (this.events) {
+        // SSE broadcast happens through events - listeners can forward to SSE
+        await this.emitEvent("process.event", {
+          processId,
+          name: proc.name,
+          event: eventName,
+          data: eventData,
+        });
+      }
+    }
+
+    // Emit generic message event (for raw messages)
     await this.emitEvent("process.message", {
       processId,
       name: proc.name,

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

@@ -46,12 +46,10 @@ export class KyselyWorkflowAdapter implements WorkflowAdapter {
     this.db = db as Kysely<Database>;
     this.cleanupDays = config.cleanupDays ?? 30;
 
-    // Start cleanup timer
+    // Start cleanup timer (don't run immediately - tables may not exist yet before migrations)
     if (this.cleanupDays > 0) {
       const interval = config.cleanupInterval ?? 3600000; // 1 hour
       this.cleanupTimer = setInterval(() => this.cleanup(), interval);
-      // Run cleanup on startup
-      this.cleanup();
     }
   }
 
@@ -240,7 +238,9 @@ export class KyselyWorkflowAdapter implements WorkflowAdapter {
       if (numDeleted > 0) {
         console.log(`[Workflows] Cleaned up ${numDeleted} old workflow instances`);
       }
-    } catch (err) {
+    } catch (err: any) {
+      // Silently ignore "no such table" errors - table may not exist yet before migrations run
+      if (err?.message?.includes("no such table")) return;
       console.error("[Workflows] Cleanup error:", err);
     }
   }

package/src/core.ts

@@ -67,6 +67,26 @@ export interface CoreServices {
  * Global context interface used in route handlers.
  * The `plugins` property is typed via PluginRegistry augmentation.
  */
+/**
+ * Registry for custom user services.
+ * Augment this interface to add typed services:
+ *
+ * @example
+ * ```ts
+ * // In your app's types file
+ * declare module "@donkeylabs/server" {
+ *   interface ServiceRegistry {
+ *     nvr: NVR;
+ *     analytics: AnalyticsService;
+ *   }
+ * }
+ *
+ * // Now ctx.services.nvr is typed
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ServiceRegistry {}
+
 export interface GlobalContext {
   /** Database instance */
   db: Kysely<any>;
@@ -80,6 +100,8 @@ export interface GlobalContext {
   errors: Errors;
   /** Application config */
   config: Record<string, any>;
+  /** Custom user-registered services - typed via ServiceRegistry augmentation */
+  services: ServiceRegistry & Record<string, any>;
   /** Client IP address */
   ip: string;
   /** Unique request ID */

package/src/index.ts

@@ -1,7 +1,19 @@
 // @donkeylabs/server - Main exports
 
 // Server
-export { AppServer, type ServerConfig } from "./server";
+export {
+  AppServer,
+  type ServerConfig,
+  // Lifecycle hooks
+  type HookContext,
+  type OnReadyHandler,
+  type OnShutdownHandler,
+  type OnErrorHandler,
+  // Custom services
+  defineService,
+  type ServiceDefinition,
+  type ServiceFactory,
+} from "./server";
 
 // Router
 export {
@@ -46,6 +58,8 @@ export {
   type InferMiddleware,
   type InferDependencies,
   type EventSchemas,
+  // Custom services registry
+  type ServiceRegistry,
 } from "./core";
 
 // Middleware
@@ -84,3 +98,6 @@ export {
   type WorkflowContext,
   type Workflows,
 } from "./core/workflows";
+
+// Test Harness - for plugin testing
+export { createTestHarness } from "./harness";

package/src/process-client.ts

@@ -0,0 +1,19 @@
+/**
+ * Process Client Entry Point
+ *
+ * Import this in your wrapper scripts:
+ * ```ts
+ * import { ProcessClient } from "@donkeylabs/server/process-client";
+ *
+ * const client = await ProcessClient.connect();
+ * client.emit("progress", { percent: 50 });
+ * ```
+ */
+
+export {
+  ProcessClient,
+  type ProcessClient as ProcessClientType,
+  type ProcessClientConfig,
+  connect,
+  createProcessClient,
+} from "./core/process-client";

package/src/server.ts

@@ -84,6 +84,103 @@ export interface ServerConfig {
   useLegacyCoreDatabases?: boolean;
 }
 
+// =============================================================================
+// LIFECYCLE HOOK TYPES
+// =============================================================================
+
+/**
+ * Context passed to lifecycle hooks.
+ * Provides access to core services, plugin services, the database, and custom services.
+ */
+export interface HookContext {
+  /** Database instance (Kysely) */
+  db: CoreServices["db"];
+  /** Core services (logger, cache, events, jobs, etc.) */
+  core: CoreServices;
+  /** Plugin services (auth, email, permissions, etc.) */
+  plugins: Record<string, any>;
+  /** Server configuration */
+  config: Record<string, any>;
+  /** Custom user-registered services */
+  services: Record<string, any>;
+  /**
+   * Register a custom service at runtime (useful in onReady hooks).
+   * Services registered this way are immediately available in ctx.services.
+   *
+   * @example
+   * ```ts
+   * server.onReady(async (ctx) => {
+   *   const nvr = new NVR(ctx.plugins.auth);
+   *   await nvr.initialize();
+   *   ctx.setService("nvr", nvr);
+   * });
+   * ```
+   */
+  setService: <T>(name: string, service: T) => void;
+}
+
+/**
+ * Handler for onReady hook - called after server is fully initialized
+ */
+export type OnReadyHandler = (ctx: HookContext) => void | Promise<void>;
+
+/**
+ * Handler for onShutdown hook - called when server is shutting down
+ */
+export type OnShutdownHandler = () => void | Promise<void>;
+
+/**
+ * Handler for onError hook - called when an unhandled error occurs
+ */
+export type OnErrorHandler = (error: Error, ctx?: HookContext) => void | Promise<void>;
+
+/**
+ * Factory function for creating a service.
+ * Receives the hook context to access plugins, db, etc.
+ */
+export type ServiceFactory<T> = (ctx: HookContext) => T | Promise<T>;
+
+/**
+ * Service definition created by defineService().
+ * Contains the name and factory for type-safe service registration.
+ */
+export interface ServiceDefinition<N extends string = string, T = any> {
+  readonly name: N;
+  readonly factory: ServiceFactory<T>;
+  /** Type brand for inference - not used at runtime */
+  readonly __type?: T;
+}
+
+/**
+ * Define a custom service for registration with the server.
+ * The service will be available as `ctx.services.name` in route handlers.
+ * Types are automatically inferred and included in generated types.
+ *
+ * @example
+ * ```ts
+ * // services/nvr.ts
+ * export const nvrService = defineService("nvr", async (ctx) => {
+ *   const nvr = new NVR(ctx.plugins.auth);
+ *   await nvr.initialize();
+ *   return nvr;
+ * });
+ *
+ * // server/index.ts
+ * server.registerService(nvrService);
+ *
+ * // In routes - ctx.services.nvr is fully typed
+ * handle: async (input, ctx) => {
+ *   return ctx.services.nvr.getRecordings();
+ * }
+ * ```
+ */
+export function defineService<N extends string, T>(
+  name: N,
+  factory: ServiceFactory<T>
+): ServiceDefinition<N, T> {
+  return { name, factory };
+}
+
 export class AppServer {
   private port: number;
   private maxPortAttempts: number;
@@ -93,6 +190,16 @@ export class AppServer {
   private coreServices: CoreServices;
   private typeGenConfig?: TypeGenerationConfig;
 
+  // Lifecycle hooks
+  private readyHandlers: OnReadyHandler[] = [];
+  private shutdownHandlers: OnShutdownHandler[] = [];
+  private errorHandlers: OnErrorHandler[] = [];
+  private isShuttingDown = false;
+
+  // Custom services registry
+  private serviceFactories = new Map<string, ServiceFactory<any>>();
+  private serviceRegistry: Record<string, any> = {};
+
   constructor(options: ServerConfig) {
     // Port priority: explicit config > PORT env var > default 3000
     const envPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
@@ -183,6 +290,196 @@ export class AppServer {
     return this;
   }
 
+  // ===========================================================================
+  // LIFECYCLE HOOKS & SERVICES
+  // ===========================================================================
+
+  /**
+   * Register a custom service/dependency that will be available in ctx.services.
+   * Services are initialized after plugins but before onReady handlers.
+   *
+   * Prefer using `defineService()` for automatic type generation:
+   * @example
+   * ```ts
+   * // services/nvr.ts
+   * export const nvrService = defineService("nvr", async (ctx) => {
+   *   const nvr = new NVR(ctx.plugins.auth);
+   *   await nvr.initialize();
+   *   return nvr;
+   * });
+   *
+   * // server/index.ts
+   * server.registerService(nvrService);
+   *
+   * // In routes - ctx.services.nvr is fully typed!
+   * handle: async (input, ctx) => {
+   *   return ctx.services.nvr.getRecordings();
+   * }
+   * ```
+   */
+  registerService<N extends string, T>(definition: ServiceDefinition<N, T>): this;
+  registerService<T>(name: string, factory: ServiceFactory<T>): this;
+  registerService<N extends string, T>(
+    nameOrDefinition: string | ServiceDefinition<N, T>,
+    factory?: ServiceFactory<T>
+  ): this {
+    if (typeof nameOrDefinition === "string") {
+      this.serviceFactories.set(nameOrDefinition, factory!);
+    } else {
+      this.serviceFactories.set(nameOrDefinition.name, nameOrDefinition.factory);
+    }
+    return this;
+  }
+
+  /**
+   * Get the custom services registry.
+   */
+  getCustomServices(): Record<string, any> {
+    return this.serviceRegistry;
+  }
+
+  /**
+   * Register a handler to be called when the server is fully initialized.
+   * Called after all plugins are initialized and background services are started.
+   *
+   * @example
+   * ```ts
+   * server.onReady(async (ctx) => {
+   *   // Initialize app-specific services
+   *   await MyService.initialize(ctx.plugins.auth);
+   *
+   *   // Set up event listeners
+   *   ctx.core.events.on("user.created", handleUserCreated);
+   *
+   *   ctx.core.logger.info("Application ready!");
+   * });
+   * ```
+   */
+  onReady(handler: OnReadyHandler): this {
+    this.readyHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * Register a handler to be called when the server is shutting down.
+   * Use this to clean up resources, close connections, etc.
+   *
+   * @example
+   * ```ts
+   * server.onShutdown(async () => {
+   *   await redis.quit();
+   *   await externalApi.disconnect();
+   *   console.log("Cleanup complete");
+   * });
+   * ```
+   */
+  onShutdown(handler: OnShutdownHandler): this {
+    this.shutdownHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * Register a global error handler for unhandled errors.
+   * Use this for error reporting, logging, or recovery.
+   *
+   * @example
+   * ```ts
+   * server.onError(async (error, ctx) => {
+   *   // Report to error tracking service
+   *   await Sentry.captureException(error);
+   *
+   *   ctx?.core.logger.error("Unhandled error", { error: error.message });
+   * });
+   * ```
+   */
+  onError(handler: OnErrorHandler): this {
+    this.errorHandlers.push(handler);
+    return this;
+  }
+
+  /**
+   * Build the hook context for lifecycle handlers.
+   */
+  private getHookContext(): HookContext {
+    return {
+      db: this.coreServices.db,
+      core: this.coreServices,
+      plugins: this.manager.getServices(),
+      config: this.coreServices.config,
+      services: this.serviceRegistry,
+      setService: <T>(name: string, service: T) => {
+        this.serviceRegistry[name] = service;
+      },
+    };
+  }
+
+  /**
+   * Initialize all registered services.
+   * Called after plugins but before onReady handlers.
+   */
+  private async initializeServices(): Promise<void> {
+    const ctx = this.getHookContext();
+    for (const [name, factory] of this.serviceFactories) {
+      try {
+        this.serviceRegistry[name] = await factory(ctx);
+        this.coreServices.logger.debug(`Service initialized: ${name}`);
+      } catch (error) {
+        this.coreServices.logger.error(`Failed to initialize service: ${name}`, { error });
+        await this.handleError(error as Error);
+        throw error; // Services are critical, fail startup if they can't init
+      }
+    }
+    if (this.serviceFactories.size > 0) {
+      this.coreServices.logger.info(`Initialized ${this.serviceFactories.size} custom service(s)`);
+    }
+  }
+
+  /**
+   * Run all registered ready handlers.
+   */
+  private async runReadyHandlers(): Promise<void> {
+    const ctx = this.getHookContext();
+    for (const handler of this.readyHandlers) {
+      try {
+        await handler(ctx);
+      } catch (error) {
+        this.coreServices.logger.error("Error in onReady handler", { error });
+        await this.handleError(error as Error);
+      }
+    }
+  }
+
+  /**
+   * Run all registered shutdown handlers (internal helper).
+   */
+  private async runShutdownHandlers(): Promise<void> {
+    // Run shutdown handlers in reverse order (LIFO)
+    for (const handler of [...this.shutdownHandlers].reverse()) {
+      try {
+        await handler();
+      } catch (error) {
+        this.coreServices.logger.error("Error in onShutdown handler", { error });
+      }
+    }
+  }
+
+  /**
+   * Handle an error using registered error handlers.
+   */
+  private async handleError(error: Error): Promise<void> {
+    const ctx = this.getHookContext();
+    for (const handler of this.errorHandlers) {
+      try {
+        await handler(error, ctx);
+      } catch (handlerError) {
+        this.coreServices.logger.error("Error in onError handler", {
+          originalError: error.message,
+          handlerError: (handlerError as Error).message,
+        });
+      }
+    }
+  }
+
   /**
    * Add a router to handle RPC routes.
    */
@@ -594,8 +891,8 @@ export interface Handler<T extends { Input: any; Output: any }> {
   handle(input: T["Input"]): T["Output"] | Promise<T["Output"]>;
 }
 
-// Re-export server context for model classes
-export { type ServerContext as AppContext } from "@donkeylabs/server";
+// Re-export server context for model classes (type-only to avoid bundling server code)
+export type { ServerContext as AppContext } from "@donkeylabs/server";
 
 // ============================================
 // Route Types
@@ -650,6 +947,10 @@ ${factoryFunction}
     }
     logger.info(`Loaded ${this.routeMap.size} RPC routes`);
     logger.info("Server initialized (adapter mode)");
+
+    // Initialize custom services, then run onReady handlers
+    await this.initializeServices();
+    await this.runReadyHandlers();
   }
 
   /**
@@ -700,6 +1001,7 @@ ${factoryFunction}
       core: this.coreServices,
       errors: this.coreServices.errors,
       config: this.coreServices.config,
+      services: this.serviceRegistry,
       ip,
       requestId: crypto.randomUUID(),
     };
@@ -774,6 +1076,7 @@ ${factoryFunction}
       core: this.coreServices,
       errors: this.coreServices.errors,
       config: this.coreServices.config,
+      services: this.serviceRegistry,
       ip,
       requestId: crypto.randomUUID(),
     };
@@ -894,7 +1197,7 @@ ${factoryFunction}
         const getEnabledHandlers = ["stream", "sse", "html", "raw"];
 
         // Check method based on handler type
-        if (req.method === "GET" && !getEnabledHandlers.includes(handlerType)) {
+        if (req.method === "GET" && !getEnabledHandlers.includes(handlerType as string)) {
           return new Response("Method Not Allowed", { status: 405 });
         }
         if (req.method !== "GET" && req.method !== "POST") {
@@ -923,6 +1226,7 @@ ${factoryFunction}
             core: this.coreServices,
             errors: this.coreServices.errors, // Convenience access
             config: this.coreServices.config,
+            services: this.serviceRegistry,
             ip,
             requestId: crypto.randomUUID(),
           };
@@ -978,6 +1282,10 @@ ${factoryFunction}
         // Update the actual port we're running on
         this.port = currentPort;
         logger.info(`Server running at http://localhost:${this.port}`);
+
+        // Initialize custom services, then run onReady handlers
+        await this.initializeServices();
+        await this.runReadyHandlers();
         return;
       } catch (error) {
         const isPortInUse =
@@ -1030,12 +1338,19 @@ ${factoryFunction}
 
   /**
    * Gracefully shutdown the server.
-   * Stops background services and closes SSE connections.
+   * Runs shutdown handlers, stops background services, and closes connections.
+   * Safe to call multiple times (idempotent).
    */
-  async shutdown() {
+  async shutdown(): Promise<void> {
+    if (this.isShuttingDown) return;
+    this.isShuttingDown = true;
+
     const { logger } = this.coreServices;
     logger.info("Shutting down server...");
 
+    // Run user shutdown handlers first (in reverse order - LIFO)
+    await this.runShutdownHandlers();
+
     // Stop SSE (closes all client connections)
     this.coreServices.sse.shutdown();
 
@@ -1053,4 +1368,27 @@ ${factoryFunction}
 
     logger.info("Server shutdown complete");
   }
+
+  /**
+   * Set up graceful shutdown handlers for process signals.
+   * Call this after start() to enable SIGTERM/SIGINT handling.
+   *
+   * @example
+   * ```ts
+   * await server.start();
+   * server.enableGracefulShutdown();
+   * ```
+   */
+  enableGracefulShutdown(): this {
+    const handleSignal = async (signal: string) => {
+      this.coreServices.logger.info(`Received ${signal}, initiating graceful shutdown...`);
+      await this.shutdown();
+      process.exit(0);
+    };
+
+    process.on("SIGTERM", () => handleSignal("SIGTERM"));
+    process.on("SIGINT", () => handleSignal("SIGINT"));
+
+    return this;
+  }
 }