@donkeylabs/server 2.3.0 → 2.4.0

package/docs/processes.md

@@ -323,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;
 
@@ -363,9 +366,12 @@ interface Processes {
   /** Get processes by name */
   getByName(name: string): ManagedProcess[];
 
-  /** Send a message to a running process */
+  /** 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>;
 
@@ -575,6 +581,51 @@ ctx.core.events.on("process.stats", ({ processId, name, stats }) => {
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.3.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/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 }));
   }
 
   /**