@donkeylabs/server 2.1.0 → 2.3.0

package/docs/cache.md

@@ -322,51 +322,44 @@ interface CacheAdapter {
 }
 ```
 
-### Redis Adapter Example
+### Built-in Redis Adapter
+
+A production-ready Redis adapter is included. Requires `ioredis` as a peer dependency (`bun add ioredis`).
 
 ```ts
-import { createCache, type CacheAdapter } from "./core/cache";
 import Redis from "ioredis";
+import { RedisCacheAdapter } from "@donkeylabs/server/core";
 
-class RedisCacheAdapter implements CacheAdapter {
-  constructor(private redis: Redis) {}
+const redis = new Redis("redis://localhost:6379");
 
-  async get<T>(key: string): Promise<T | null> {
-    const value = await this.redis.get(key);
-    return value ? JSON.parse(value) : null;
-  }
+const server = new AppServer({
+  cache: {
+    adapter: new RedisCacheAdapter(redis, { prefix: "myapp:" }),
+  },
+});
 
-  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
-    const serialized = JSON.stringify(value);
-    if (ttlMs) {
-      await this.redis.set(key, serialized, "PX", ttlMs);
-    } else {
-      await this.redis.set(key, serialized);
-    }
-  }
+// Remember to disconnect on shutdown
+server.onShutdown(() => redis.disconnect());
+```
 
-  async delete(key: string): Promise<boolean> {
-    const result = await this.redis.del(key);
-    return result > 0;
-  }
+**Features:**
+- JSON serialization for values
+- `SET key val PX ttlMs` for TTL support
+- `SCAN` (not `KEYS`) for production-safe key listing on large datasets
+- Optional `prefix` for key namespace isolation in shared Redis instances
+- With prefix: `clear()` uses SCAN + DEL only for prefixed keys
+- Without prefix: `clear()` uses `FLUSHDB`
 
-  async has(key: string): Promise<boolean> {
-    return (await this.redis.exists(key)) === 1;
-  }
+### Custom Redis Adapter Example
 
-  async clear(): Promise<void> {
-    await this.redis.flushdb();
-  }
+For custom requirements, implement `CacheAdapter` directly:
 
-  async keys(pattern?: string): Promise<string[]> {
-    return this.redis.keys(pattern ?? "*");
-  }
-}
+```ts
+import { type CacheAdapter } from "@donkeylabs/server/core";
 
-// Use Redis adapter
-const cache = createCache({
-  adapter: new RedisCacheAdapter(new Redis()),
-});
+class MyCustomCacheAdapter implements CacheAdapter {
+  // Implement get, set, delete, has, clear, keys
+}
 ```
 
 ---

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/docs/rate-limiter.md

@@ -420,46 +420,41 @@ interface RateLimitAdapter {
 }
 ```
 
-### Redis Adapter Example
+### Built-in Redis Adapter
+
+A production-ready Redis adapter is included. Requires `ioredis` as a peer dependency (`bun add ioredis`).
 
 ```ts
-import { createRateLimiter, type RateLimitAdapter } from "./core/rate-limiter";
 import Redis from "ioredis";
+import { RedisRateLimitAdapter } from "@donkeylabs/server/core";
 
-class RedisRateLimitAdapter implements RateLimitAdapter {
-  constructor(private redis: Redis) {}
+const redis = new Redis("redis://localhost:6379");
 
-  async increment(key: string, windowMs: number): Promise<{ count: number; resetAt: Date }> {
-    const now = Date.now();
-    const windowKey = `${key}:${Math.floor(now / windowMs)}`;
+const server = new AppServer({
+  rateLimiter: {
+    adapter: new RedisRateLimitAdapter(redis, { prefix: "myapp:" }),
+  },
+});
 
-    const count = await this.redis.incr(windowKey);
+// Remember to disconnect on shutdown
+server.onShutdown(() => redis.disconnect());
+```
 
-    if (count === 1) {
-      // Set expiry on first request in window
-      await this.redis.pexpire(windowKey, windowMs);
-    }
+**Features:**
+- Atomic Lua script for `INCR` + conditional `PEXPIRE` (prevents race conditions)
+- Pipeline `GET` + `PTTL` in a single round-trip for `get()`
+- Optional `prefix` for key namespace isolation in shared Redis instances
 
-    const resetAt = new Date(Math.ceil(now / windowMs) * windowMs);
+### Custom Redis Adapter Example
 
-    return { count, resetAt };
-  }
+For custom requirements, implement `RateLimitAdapter` directly:
 
-  async get(key: string): Promise<{ count: number; resetAt: Date } | null> {
-    // Implementation for getting current state
-  }
+```ts
+import { type RateLimitAdapter } from "@donkeylabs/server/core";
 
-  async reset(key: string): Promise<void> {
-    const keys = await this.redis.keys(`${key}:*`);
-    if (keys.length > 0) {
-      await this.redis.del(...keys);
-    }
-  }
+class MyCustomRateLimitAdapter implements RateLimitAdapter {
+  // Implement increment, get, reset
 }
-
-const rateLimiter = createRateLimiter({
-  adapter: new RedisRateLimitAdapter(new Redis()),
-});
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@donkeylabs/server",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "type": "module",
   "description": "Type-safe plugin system for building RPC-style APIs with Bun",
   "main": "./src/index.ts",
@@ -75,7 +75,8 @@
     "@aws-sdk/s3-request-presigner": "^3.0.0",
     "@playwright/test": "^1.40.0",
     "pg": "^8.0.0",
-    "mysql2": "^3.0.0"
+    "mysql2": "^3.0.0",
+    "ioredis": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -92,6 +93,9 @@
     },
     "mysql2": {
       "optional": true
+    },
+    "ioredis": {
+      "optional": true
     }
   },
   "dependencies": {

package/src/core/cache-adapter-redis.ts

@@ -0,0 +1,113 @@
+// Redis Cache Adapter
+// Production-ready cache backend using Redis (via ioredis)
+
+import type { CacheAdapter } from "./cache";
+
+export interface RedisCacheAdapterConfig {
+  /** Key prefix for namespace isolation in shared Redis instances */
+  prefix?: string;
+}
+
+/**
+ * Redis-backed cache adapter using ioredis.
+ *
+ * Constructor takes a pre-built ioredis client (typed as `any` to avoid
+ * requiring ioredis types at compile time — same pattern as S3StorageAdapter).
+ * User manages connection lifecycle (connect/disconnect in onShutdown).
+ *
+ * @example
+ * ```ts
+ * import Redis from "ioredis";
+ * import { RedisCacheAdapter } from "@donkeylabs/server/core";
+ *
+ * const redis = new Redis("redis://localhost:6379");
+ * const server = new AppServer({
+ *   cache: { adapter: new RedisCacheAdapter(redis, { prefix: "myapp:" }) },
+ * });
+ * ```
+ */
+export class RedisCacheAdapter implements CacheAdapter {
+  private redis: any;
+  private prefix: string;
+
+  constructor(redis: any, config: RedisCacheAdapterConfig = {}) {
+    this.redis = redis;
+    this.prefix = config.prefix ?? "";
+  }
+
+  private prefixKey(key: string): string {
+    return this.prefix + key;
+  }
+
+  private stripPrefix(key: string): string {
+    if (this.prefix && key.startsWith(this.prefix)) {
+      return key.slice(this.prefix.length);
+    }
+    return key;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const raw = await this.redis.get(this.prefixKey(key));
+    if (raw === null || raw === undefined) return null;
+    return JSON.parse(raw) as T;
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    const serialized = JSON.stringify(value);
+    if (ttlMs && ttlMs > 0) {
+      await this.redis.set(this.prefixKey(key), serialized, "PX", ttlMs);
+    } else {
+      await this.redis.set(this.prefixKey(key), serialized);
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const result = await this.redis.del(this.prefixKey(key));
+    return result > 0;
+  }
+
+  async has(key: string): Promise<boolean> {
+    return (await this.redis.exists(this.prefixKey(key))) === 1;
+  }
+
+  async clear(): Promise<void> {
+    if (this.prefix) {
+      // With prefix: SCAN + DEL only prefixed keys (production-safe)
+      const keys = await this.scanKeys(this.prefix + "*");
+      if (keys.length > 0) {
+        await this.redis.del(...keys);
+      }
+    } else {
+      await this.redis.flushdb();
+    }
+  }
+
+  async keys(pattern?: string): Promise<string[]> {
+    const redisPattern = this.prefix + (pattern ?? "*");
+    const keys = await this.scanKeys(redisPattern);
+    return keys.map((k: string) => this.stripPrefix(k));
+  }
+
+  /**
+   * Uses SCAN (not KEYS) for production safety on large datasets.
+   * Iterates cursor until exhausted.
+   */
+  private async scanKeys(pattern: string): Promise<string[]> {
+    const results: string[] = [];
+    let cursor = "0";
+
+    do {
+      const [nextCursor, keys] = await this.redis.scan(
+        cursor,
+        "MATCH",
+        pattern,
+        "COUNT",
+        100,
+      );
+      cursor = nextCursor;
+      results.push(...keys);
+    } while (cursor !== "0");
+
+    return results;
+  }
+}

package/src/core/index.ts

@@ -282,6 +282,16 @@ export {
 export { LocalStorageAdapter } from "./storage-adapter-local";
 export { S3StorageAdapter } from "./storage-adapter-s3";
 
+export {
+  RedisCacheAdapter,
+  type RedisCacheAdapterConfig,
+} from "./cache-adapter-redis";
+
+export {
+  RedisRateLimitAdapter,
+  type RedisRateLimitAdapterConfig,
+} from "./rate-limit-adapter-redis";
+
 export {
   type Logs,
   type LogSource,

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/rate-limit-adapter-redis.ts

@@ -0,0 +1,109 @@
+// Redis Rate Limit Adapter
+// Production-ready rate limiting backend using Redis (via ioredis)
+
+import type { RateLimitAdapter } from "./rate-limiter";
+
+export interface RedisRateLimitAdapterConfig {
+  /** Key prefix for namespace isolation in shared Redis instances */
+  prefix?: string;
+}
+
+/**
+ * Redis-backed rate limit adapter using ioredis.
+ *
+ * Uses a Lua script for atomic INCR + conditional PEXPIRE to prevent
+ * race conditions where a key is incremented but the expire fails.
+ *
+ * Constructor takes a pre-built ioredis client (typed as `any` to avoid
+ * requiring ioredis types at compile time — same pattern as S3StorageAdapter).
+ * User manages connection lifecycle (connect/disconnect in onShutdown).
+ *
+ * @example
+ * ```ts
+ * import Redis from "ioredis";
+ * import { RedisRateLimitAdapter } from "@donkeylabs/server/core";
+ *
+ * const redis = new Redis("redis://localhost:6379");
+ * const server = new AppServer({
+ *   rateLimiter: { adapter: new RedisRateLimitAdapter(redis, { prefix: "myapp:" }) },
+ * });
+ * ```
+ */
+export class RedisRateLimitAdapter implements RateLimitAdapter {
+  private redis: any;
+  private prefix: string;
+
+  /**
+   * Lua script for atomic increment + conditional expire.
+   * KEYS[1] = rate limit key
+   * ARGV[1] = window TTL in milliseconds
+   *
+   * Returns [count, ttl_remaining_ms]:
+   * - count: current count after increment
+   * - ttl_remaining_ms: remaining TTL in milliseconds
+   */
+  private static readonly INCREMENT_SCRIPT = `
+    local count = redis.call('INCR', KEYS[1])
+    if count == 1 then
+      redis.call('PEXPIRE', KEYS[1], ARGV[1])
+    end
+    local ttl = redis.call('PTTL', KEYS[1])
+    return {count, ttl}
+  `;
+
+  constructor(redis: any, config: RedisRateLimitAdapterConfig = {}) {
+    this.redis = redis;
+    this.prefix = config.prefix ?? "";
+  }
+
+  private prefixKey(key: string): string {
+    return this.prefix + key;
+  }
+
+  async increment(
+    key: string,
+    windowMs: number,
+  ): Promise<{ count: number; resetAt: Date }> {
+    const prefixed = this.prefixKey(key);
+    const [count, ttl] = await this.redis.eval(
+      RedisRateLimitAdapter.INCREMENT_SCRIPT,
+      1,
+      prefixed,
+      windowMs,
+    );
+
+    // ttl is remaining time in ms; derive resetAt from it
+    const resetAt = new Date(Date.now() + Math.max(ttl, 0));
+    return { count, resetAt };
+  }
+
+  async get(key: string): Promise<{ count: number; resetAt: Date } | null> {
+    const prefixed = this.prefixKey(key);
+
+    // Pipeline GET + PTTL in a single round-trip
+    const pipeline = this.redis.pipeline();
+    pipeline.get(prefixed);
+    pipeline.pttl(prefixed);
+    const results = await pipeline.exec();
+
+    const [getErr, rawCount] = results[0];
+    const [pttlErr, ttl] = results[1];
+
+    if (getErr || pttlErr) {
+      throw getErr || pttlErr;
+    }
+
+    if (rawCount === null) return null;
+
+    const count = parseInt(rawCount, 10);
+    if (isNaN(count)) return null;
+
+    // PTTL returns -2 if key doesn't exist, -1 if no expiry
+    const resetAt = new Date(Date.now() + Math.max(ttl, 0));
+    return { count, resetAt };
+  }
+
+  async reset(key: string): Promise<void> {
+    await this.redis.del(this.prefixKey(key));
+  }
+}