@donkeylabs/server 2.1.0 → 2.2.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/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.2.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/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));
+  }
+}