@donkeylabs/server 2.2.0 → 2.3.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();
 ```
@@ -358,6 +363,9 @@ interface Processes {
   /** Get processes by name */
   getByName(name: string): ManagedProcess[];
 
+  /** Send a message to a running process */
+  send(processId: string, message: any): Promise<boolean>;
+
   /** Stop a process */
   stop(processId: string, signal?: NodeJS.Signals): Promise<void>;
 
@@ -563,6 +571,89 @@ 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.
+
+### 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 +742,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.3.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;