@donkeylabs/server 2.2.0 → 2.4.0

package/docs/processes.md

@@ -269,6 +269,11 @@ client.connected; // true | false
 // Emit a typed event to the server
 await client.emit("progress", { percent: 50, fps: 30 });
 
+// Register a handler for server-sent messages (alternative to onMessage in connect options)
+client.onMessage((message) => {
+  console.log("Received from server:", message);
+});
+
 // Disconnect when done
 client.disconnect();
 ```
@@ -318,9 +323,12 @@ interface ProcessDefinition {
   /** Environment variables */
   env?: Record<string, string>;
 
-  /** Typed events the process can emit */
+  /** Typed events the process can emit (validated at runtime) */
   events?: Record<string, ZodSchema>;
 
+  /** Typed command schemas for messages sent TO the process via send() (validated at runtime) */
+  commands?: Record<string, ZodSchema>;
+
   /** Heartbeat timeout in ms (default: 30000) */
   heartbeatTimeout?: number;
 
@@ -358,6 +366,12 @@ interface Processes {
   /** Get processes by name */
   getByName(name: string): ManagedProcess[];
 
+  /** Send a message to a running process (validated against command schemas if defined) */
+  send(processId: string, message: any): Promise<boolean>;
+
+  /** Get all registered process definitions */
+  getDefinitions(): Map<string, ProcessDefinition>;
+
   /** Stop a process */
   stop(processId: string, signal?: NodeJS.Signals): Promise<void>;
 
@@ -563,6 +577,134 @@ ctx.core.events.on("process.stats", ({ processId, name, stats }) => {
 });
 ```
 
+## Server-to-Process Communication
+
+The server can send messages to running processes via `ctx.core.processes.send()`. The ProcessClient receives these messages through the `onMessage` callback.
+
+### Typed Commands
+
+Define command schemas to get runtime validation on `send()`. If a command fails validation, `send()` returns `false` and the message is not sent.
+
+```typescript
+import { z } from "zod";
+
+ctx.core.processes.register({
+  name: "ws-daemon",
+  config: {
+    command: "bun",
+    args: ["./workers/ws-daemon.ts"],
+  },
+  events: {
+    ready: z.object({ port: z.number() }),
+    clientCount: z.object({ count: z.number() }),
+  },
+  // Commands are validated before sending to the process
+  commands: {
+    subscribe: z.object({
+      type: z.literal("subscribe"),
+      channel: z.string(),
+    }),
+    configUpdate: z.object({
+      type: z.literal("configUpdate"),
+      settings: z.record(z.any()),
+    }),
+  },
+});
+
+// Valid command - sends successfully
+await ctx.core.processes.send(processId, {
+  type: "subscribe",
+  channel: "live-scores",
+}); // true
+
+// Invalid command - returns false, message not sent
+await ctx.core.processes.send(processId, {
+  type: "subscribe",
+  channel: 12345, // schema requires string
+}); // false
+```
+
+Commands without schemas are not validated (passthrough). The `type` field of the message is used to match against the command schema name.
+
+### Sending Messages from Server
+
+```typescript
+// In a route handler or service
+await ctx.core.processes.send(processId, {
+  type: "subscribe",
+  channel: "live-scores",
+});
+
+await ctx.core.processes.send(processId, {
+  type: "config_update",
+  settings: { maxConnections: 100 },
+});
+```
+
+### Receiving Messages in Worker
+
+```typescript
+// Option 1: In connect options
+const client = await ProcessClient.connect({
+  onMessage: (message) => {
+    switch (message.type) {
+      case "subscribe":
+        subscribeToChannel(message.channel);
+        break;
+      case "config_update":
+        applyConfig(message.settings);
+        break;
+    }
+  },
+});
+
+// Option 2: Register handler after connecting
+const client = await ProcessClient.connect();
+client.onMessage((message) => {
+  console.log("Received:", message);
+});
+```
+
+### Example: WebSocket Daemon with Server Commands
+
+```typescript
+// Server: define and spawn the WebSocket daemon
+server.getCore().processes.define("ws-daemon", {
+  command: "bun",
+  args: ["./workers/ws-daemon.ts"],
+  events: {
+    ready: z.object({ port: z.number() }),
+    clientCount: z.object({ count: z.number() }),
+  },
+});
+
+const processId = await ctx.core.processes.spawn("ws-daemon", {
+  metadata: { port: 8080 },
+});
+
+// Server: send commands to the daemon
+await ctx.core.processes.send(processId, {
+  type: "broadcast",
+  message: "Server maintenance in 5 minutes",
+});
+
+// Worker: ws-daemon.ts
+import { ProcessClient } from "@donkeylabs/server/process-client";
+
+const client = await ProcessClient.connect({
+  onMessage: (message) => {
+    if (message.type === "broadcast") {
+      // Broadcast to all connected WebSocket clients
+      for (const ws of connections) {
+        ws.send(JSON.stringify({ type: "announcement", text: message.message }));
+      }
+    }
+  },
+});
+
+client.emit("ready", { port: client.metadata.port });
+```
+
 ## Heartbeat Monitoring
 
 The ProcessClient automatically sends heartbeats. If heartbeats stop:
@@ -651,3 +793,4 @@ process.on("SIGTERM", () => client.disconnect());
 3. **Use typed events** - Define event schemas for type safety
 4. **Monitor heartbeats** - Set appropriate timeout for your use case
 5. **Keep wrappers thin** - Business logic should be in the actual process
+6. **Use onMessage for commands** - Register `onMessage` to receive server commands for stateful workers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",

package/src/core/process-client.ts

@@ -8,7 +8,11 @@
  * ```ts
  * import { ProcessClient } from "@donkeylabs/server/process-client";
  *
- * const client = await ProcessClient.connect();
+ * const client = await ProcessClient.connect({
+ *   onMessage: (message) => {
+ *     if (message.type === "subscribe") { ... }
+ *   },
+ * });
  *
  * // Access metadata passed during spawn
  * const { inputPath, outputPath } = client.metadata;
@@ -83,6 +87,8 @@ export interface ProcessClientConfig {
   maxReconnectAttempts?: number;
   /** Stats emission configuration */
   stats?: StatsConfig;
+  /** Callback for messages sent from the server via ctx.core.processes.send() */
+  onMessage?: (message: any) => void | Promise<void>;
 }
 
 export interface ProcessClient {
@@ -94,6 +100,8 @@ export interface ProcessClient {
   readonly connected: boolean;
   /** Emit a typed event to the server */
   emit(event: string, data?: Record<string, any>): Promise<boolean>;
+  /** Register a handler for messages sent from the server via ctx.core.processes.send() */
+  onMessage(handler: (message: any) => void | Promise<void>): void;
   /** Disconnect from the server */
   disconnect(): void;
 }
@@ -120,6 +128,7 @@ class ProcessClientImpl implements ProcessClient {
   private reconnectAttempts = 0;
   private isDisconnecting = false;
   private _connected = false;
+  private messageHandler?: (message: any) => void | Promise<void>;
 
   // For CPU percentage calculation
   private lastCpuUsage?: NodeJS.CpuUsage;
@@ -134,6 +143,7 @@ class ProcessClientImpl implements ProcessClient {
     this.reconnectInterval = config.reconnectInterval ?? 2000;
     this.maxReconnectAttempts = config.maxReconnectAttempts ?? 30;
     this.statsConfig = config.stats ?? { enabled: false };
+    if (config.onMessage) this.messageHandler = config.onMessage;
   }
 
   get connected(): boolean {
@@ -221,9 +231,22 @@ class ProcessClientImpl implements ProcessClient {
   }
 
   private handleServerMessage(message: any): void {
-    // Server can send messages to the process (e.g., "stop", "config update")
-    // For now, just log them
-    console.log(`[ProcessClient] Received from server:`, message);
+    if (this.messageHandler) {
+      try {
+        const result = this.messageHandler(message);
+        if (result instanceof Promise) {
+          result.catch((err) => {
+            console.error(`[ProcessClient] Error in onMessage handler:`, err);
+          });
+        }
+      } catch (err) {
+        console.error(`[ProcessClient] Error in onMessage handler:`, err);
+      }
+    }
+  }
+
+  onMessage(handler: (message: any) => void | Promise<void>): void {
+    this.messageHandler = handler;
   }
 
   private scheduleReconnect(): void {
@@ -412,6 +435,14 @@ export function createProcessClient(config: ProcessClientConfig): ProcessClient
  * const client = await ProcessClient.connect({
  *   stats: { enabled: true, interval: 2000 }
  * });
+ *
+ * // With server message handling
+ * const client = await ProcessClient.connect({
+ *   onMessage: (message) => {
+ *     if (message.type === "subscribe") { ... }
+ *     if (message.type === "config_update") { ... }
+ *   },
+ * });
  * ```
  */
 export async function connect(options?: {
@@ -420,6 +451,8 @@ export async function connect(options?: {
   maxReconnectAttempts?: number;
   /** Enable real-time CPU/memory stats emission */
   stats?: StatsConfig;
+  /** Callback for messages sent from the server via ctx.core.processes.send() */
+  onMessage?: (message: any) => void | Promise<void>;
 }): Promise<ProcessClient> {
   const processId = process.env.DONKEYLABS_PROCESS_ID;
   const socketPath = process.env.DONKEYLABS_SOCKET_PATH;

package/src/core/processes.ts

@@ -136,6 +136,19 @@ export interface ProcessDefinition {
    * ```
    */
   events?: Record<string, import("zod").ZodType<any>>;
+  /**
+   * Command schemas for messages sent TO the process via send().
+   * Commands are validated at runtime using safeParse() before sending.
+   *
+   * @example
+   * ```ts
+   * commands: {
+   *   subscribe: z.object({ channel: z.string() }),
+   *   configUpdate: z.object({ settings: z.record(z.any()) }),
+   * }
+   * ```
+   */
+  commands?: 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 */
@@ -209,6 +222,8 @@ export interface Processes {
   getRunning(): Promise<ManagedProcess[]>;
   /** Send a message to a process via socket */
   send(processId: string, message: any): Promise<boolean>;
+  /** Get all registered process definitions */
+  getDefinitions(): Map<string, ProcessDefinition>;
   /** Start the service (recovery, monitoring) */
   start(): void;
   /** Shutdown the service and all managed processes */
@@ -552,9 +567,32 @@ export class ProcessesImpl implements Processes {
   }
 
   async send(processId: string, message: any): Promise<boolean> {
+    // Validate message against command schemas if defined
+    if (message && typeof message === "object" && message.type) {
+      const proc = await this.adapter.get(processId);
+      if (proc) {
+        const definition = this.definitions.get(proc.name);
+        if (definition?.commands) {
+          const commandSchema = definition.commands[message.type];
+          if (commandSchema) {
+            const result = commandSchema.safeParse(message);
+            if (!result.success) {
+              console.warn(
+                `[Processes] Command validation failed for '${message.type}' on ${proc.name}: ${result.error.message}`
+              );
+              return false;
+            }
+          }
+        }
+      }
+    }
     return this.socketServer.send(processId, message);
   }
 
+  getDefinitions(): Map<string, ProcessDefinition> {
+    return this.definitions;
+  }
+
   start(): void {
     // Recover orphaned processes
     if (this.autoRecoverOrphans) {
@@ -684,7 +722,23 @@ export class ProcessesImpl implements Processes {
     // Handle typed event messages from ProcessClient.emit()
     if (type === "event" && message.event) {
       const eventName = message.event as string;
-      const eventData = message.data ?? {};
+      let eventData = message.data ?? {};
+
+      // Validate event data against schema if defined
+      const definition = this.definitions.get(proc.name);
+      if (definition?.events) {
+        const eventSchema = definition.events[eventName];
+        if (eventSchema) {
+          const result = eventSchema.safeParse(eventData);
+          if (!result.success) {
+            console.warn(
+              `[Processes] Event validation failed for '${eventName}' on ${proc.name}: ${result.error.message}`
+            );
+            return; // Drop invalid events
+          }
+          eventData = result.data;
+        }
+      }
 
       // Emit to events service as "process.<name>.<event>"
       await this.emitEvent(`process.${proc.name}.${eventName}`, {

package/src/core.ts

@@ -73,6 +73,25 @@ export type EventSchemas = Record<string, z.ZodType<any>>;
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface EventRegistry {}
 
+/**
+ * Registry for process type definitions.
+ * Augment this interface to add typed process commands/events:
+ *
+ * @example
+ * ```ts
+ * declare module "@donkeylabs/server" {
+ *   interface ProcessRegistry {
+ *     "video-encoder": {
+ *       events: { progress: { percent: number }; complete: { outputPath: string } };
+ *       commands: { subscribe: { channel: string }; configUpdate: { settings: Record<string, any> } };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ProcessRegistry {}
+
 /**
  * Define server-level events with Zod schemas.
  * Events defined here will be typed and available across the app.
@@ -240,7 +259,7 @@ type ExtractServices<T extends readonly (keyof PluginRegistry)[] | undefined> =
   T extends readonly []
     ? {}
     : T extends readonly (infer K)[]
-      ? K extends keyof PluginRegistry
+      ? [K] extends [keyof PluginRegistry]
         ? { [P in K]: PluginRegistry[P] extends { service: infer S } ? S : unknown }
         : {}
       : {};

package/src/index.ts

@@ -51,7 +51,9 @@ export {
   defineEvents,
   type EventRegistry,
   type EventSchemas,
+  // Registries
   type PluginRegistry,
+  type ProcessRegistry,
   type PluginHandlerRegistry,
   type PluginMiddlewareRegistry,
   type CoreServices,

package/src/server.ts

@@ -855,7 +855,30 @@ export class AppServer {
       }
     }
 
-    console.log(JSON.stringify({ routes }));
+    // Collect process definitions with their schemas
+    const processes = [];
+    const definitions = this.coreServices.processes.getDefinitions();
+    for (const [name, def] of definitions) {
+      const events: Record<string, string> = {};
+      if (def.events) {
+        for (const [eventName, schema] of Object.entries(def.events)) {
+          events[eventName] = zodSchemaToTs(schema);
+        }
+      }
+      const commands: Record<string, string> = {};
+      if (def.commands) {
+        for (const [cmdName, schema] of Object.entries(def.commands)) {
+          commands[cmdName] = zodSchemaToTs(schema);
+        }
+      }
+      processes.push({
+        name,
+        events: Object.keys(events).length > 0 ? events : undefined,
+        commands: Object.keys(commands).length > 0 ? commands : undefined,
+      });
+    }
+
+    console.log(JSON.stringify({ routes, processes }));
   }
 
   /**