@donkeylabs/server 2.0.37 → 2.2.0

package/src/client/base.ts

@@ -154,6 +154,8 @@ export interface ApiClientOptions {
   onAuthChange?: (authenticated: boolean) => void;
   /** Custom fetch implementation (for testing or Node.js polyfills) */
   fetch?: typeof fetch;
+  /** API version to send via X-API-Version header */
+  apiVersion?: string;
 }
 
 // ============================================
@@ -225,6 +227,18 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
   /**
    * Make a typed POST request to a route
    */
+  /** Build common headers including optional API version */
+  private buildHeaders(extra?: Record<string, string>): Record<string, string> {
+    const headers: Record<string, string> = {
+      ...this.options.headers,
+      ...extra,
+    };
+    if (this.options.apiVersion) {
+      headers["X-API-Version"] = this.options.apiVersion;
+    }
+    return headers;
+  }
+
   protected async request<TInput, TOutput>(
     route: string,
     input: TInput,
@@ -236,8 +250,7 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        ...this.options.headers,
-        ...options.headers,
+        ...this.buildHeaders(options.headers),
       },
       credentials: this.options.credentials,
       body: JSON.stringify(input),
@@ -278,7 +291,7 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
       method: "POST",
       ...requestInit,
       headers: {
-        ...this.options.headers,
+        ...this.buildHeaders(),
         ...requestInit.headers,
       },
       credentials: this.options.credentials,
@@ -298,7 +311,7 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        ...this.options.headers,
+        ...this.buildHeaders(),
       },
       credentials: this.options.credentials,
       body: JSON.stringify(input),
@@ -331,7 +344,7 @@ export class ApiClientBase<TEvents extends Record<string, any> = Record<string,
     const response = await fetchFn(`${this.baseUrl}/${route}`, {
       method: "POST",
       headers: {
-        ...this.options.headers,
+        ...this.buildHeaders(),
         // Don't set Content-Type - browser will set it with boundary
       },
       credentials: this.options.credentials,

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/events.ts

@@ -11,20 +11,33 @@ export interface Subscription {
   unsubscribe(): void;
 }
 
+export interface EventMetadata {
+  traceId?: string;
+  source?: string;
+  [key: string]: any;
+}
+
 export interface EventRecord {
   event: string;
   data: any;
   timestamp: Date;
+  metadata?: EventMetadata;
 }
 
 export interface EventAdapter {
-  publish(event: string, data: any): Promise<void>;
+  publish(event: string, data: any, metadata?: EventMetadata): Promise<void>;
   getHistory(event: string, limit?: number): Promise<EventRecord[]>;
+  /** Subscribe to events from other instances (for distributed adapters) */
+  subscribe?(callback: (event: string, data: any, metadata?: EventMetadata) => void): Promise<void>;
+  /** Stop the adapter and clean up resources */
+  stop?(): Promise<void>;
 }
 
 export interface EventsConfig {
   adapter?: EventAdapter;
   maxHistorySize?: number;
+  /** SSE service for auto-propagating distributed events to SSE clients */
+  sse?: import("./sse").SSE;
 }
 
 /**
@@ -41,11 +54,11 @@ export interface Events {
   /**
    * Emit a typed event (when EventRegistry is augmented)
    */
-  emit<K extends keyof EventRegistry>(event: K, data: EventRegistry[K]): Promise<void>;
+  emit<K extends keyof EventRegistry>(event: K, data: EventRegistry[K], metadata?: EventMetadata): Promise<void>;
   /**
    * Emit an untyped event (fallback for dynamic event names)
    */
-  emit<T = any>(event: string, data: T): Promise<void>;
+  emit<T = any>(event: string, data: T, metadata?: EventMetadata): Promise<void>;
 
   /**
    * Subscribe to a typed event (when EventRegistry is augmented)
@@ -67,6 +80,8 @@ export interface Events {
 
   off(event: string, handler?: EventHandler): void;
   getHistory(event: string, limit?: number): Promise<EventRecord[]>;
+  /** Stop the event bus and clean up resources */
+  stop(): Promise<void>;
 }
 
 // In-memory event adapter with history
@@ -78,11 +93,12 @@ export class MemoryEventAdapter implements EventAdapter {
     this.maxHistorySize = maxHistorySize;
   }
 
-  async publish(event: string, data: any): Promise<void> {
+  async publish(event: string, data: any, metadata?: EventMetadata): Promise<void> {
     const record: EventRecord = {
       event,
       data,
       timestamp: new Date(),
+      metadata,
     };
 
     this.history.push(record);
@@ -103,16 +119,41 @@ export class MemoryEventAdapter implements EventAdapter {
 class EventsImpl implements Events {
   private handlers = new Map<string, Set<EventHandler>>();
   private adapter: EventAdapter;
+  private sse?: import("./sse").SSE;
+  private stopped = false;
 
   constructor(config: EventsConfig = {}) {
     this.adapter = config.adapter ?? new MemoryEventAdapter(config.maxHistorySize);
+    this.sse = config.sse;
+
+    // If adapter supports distributed subscriptions, set up the callback
+    if (this.adapter.subscribe) {
+      this.adapter.subscribe((event, data, metadata) => {
+        // Dispatch to local handlers without re-publishing to adapter
+        this.dispatchToLocalHandlers(event, data, metadata);
+        // Propagate to SSE clients so browser subscribers see distributed events
+        this.sse?.broadcastAll(event, data);
+      });
+    }
   }
 
-  async emit<T = any>(event: string, data: T): Promise<void> {
+  async emit<T = any>(event: string, data: T, metadata?: EventMetadata): Promise<void> {
+    if (this.stopped) return;
+
     // Store in adapter (for history/persistence)
-    await this.adapter.publish(event, data);
+    await this.adapter.publish(event, data, metadata);
+
+    // Dispatch to local handlers
+    await this.dispatchToLocalHandlers(event, data, metadata);
+  }
 
-    // Notify handlers
+  /**
+   * Dispatch an event to locally registered handlers.
+   * Separated from emit() so distributed adapters can deliver remote events
+   * without re-publishing to the adapter.
+   */
+  private async dispatchToLocalHandlers(event: string, data: any, _metadata?: EventMetadata): Promise<void> {
+    // Notify exact-match handlers
     const eventHandlers = this.handlers.get(event);
     if (eventHandlers) {
       const promises: Promise<void>[] = [];
@@ -185,6 +226,12 @@ class EventsImpl implements Events {
     return this.adapter.getHistory(event, limit);
   }
 
+  async stop(): Promise<void> {
+    this.stopped = true;
+    await this.adapter.stop?.();
+    this.handlers.clear();
+  }
+
   private matchPattern(event: string, pattern: string): boolean {
     // Convert glob pattern to regex (e.g., "user.*" -> /^user\..*$/)
     const regex = new RegExp(

package/src/core/health.ts

@@ -0,0 +1,165 @@
+// Core Health Check Service
+// Provides liveness and readiness probes for production deployments
+
+import type { Kysely } from "kysely";
+
+export type HealthStatus = "healthy" | "degraded" | "unhealthy";
+
+export interface HealthCheckResult {
+  status: HealthStatus;
+  message?: string;
+  latencyMs?: number;
+}
+
+export interface HealthCheck {
+  name: string;
+  check: () => Promise<HealthCheckResult> | HealthCheckResult;
+  /** Whether failure of this check marks the service as unhealthy (default: true) */
+  critical?: boolean;
+}
+
+export interface HealthResponse {
+  status: HealthStatus;
+  uptime: number;
+  timestamp: string;
+  checks: Record<string, HealthCheckResult>;
+}
+
+export interface HealthConfig {
+  checks?: HealthCheck[];
+  /** Path for liveness probe (default: "/_health") */
+  livenessPath?: string;
+  /** Path for readiness probe (default: "/_ready") */
+  readinessPath?: string;
+  /** Timeout per check in ms (default: 5000) */
+  checkTimeout?: number;
+  /** Whether to register a built-in database check (default: true) */
+  dbCheck?: boolean;
+}
+
+export interface Health {
+  /** Register a health check */
+  register(check: HealthCheck): void;
+  /** Run all readiness checks */
+  check(): Promise<HealthResponse>;
+  /** Fast liveness probe (no external checks) */
+  liveness(isShuttingDown: boolean): HealthResponse;
+}
+
+class HealthImpl implements Health {
+  private checks: HealthCheck[] = [];
+  private startTime = Date.now();
+  private checkTimeout: number;
+
+  constructor(config: HealthConfig = {}) {
+    this.checkTimeout = config.checkTimeout ?? 5000;
+
+    if (config.checks) {
+      for (const check of config.checks) {
+        this.checks.push(check);
+      }
+    }
+  }
+
+  register(check: HealthCheck): void {
+    this.checks.push(check);
+  }
+
+  async check(): Promise<HealthResponse> {
+    const results: Record<string, HealthCheckResult> = {};
+    let overallStatus: HealthStatus = "healthy";
+
+    await Promise.all(
+      this.checks.map(async (check) => {
+        const start = Date.now();
+        try {
+          const result = await Promise.race([
+            Promise.resolve(check.check()),
+            new Promise<HealthCheckResult>((_, reject) =>
+              setTimeout(() => reject(new Error("Health check timed out")), this.checkTimeout)
+            ),
+          ]);
+          results[check.name] = {
+            ...result,
+            latencyMs: result.latencyMs ?? Date.now() - start,
+          };
+
+          const isCritical = check.critical !== false;
+          if (result.status === "unhealthy" && isCritical) {
+            overallStatus = "unhealthy";
+          } else if (result.status === "degraded" && overallStatus !== "unhealthy") {
+            overallStatus = "degraded";
+          } else if (result.status === "unhealthy" && !isCritical && overallStatus !== "unhealthy") {
+            overallStatus = "degraded";
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          results[check.name] = {
+            status: "unhealthy",
+            message,
+            latencyMs: Date.now() - start,
+          };
+          const isCritical = check.critical !== false;
+          if (isCritical) {
+            overallStatus = "unhealthy";
+          } else if (overallStatus !== "unhealthy") {
+            overallStatus = "degraded";
+          }
+        }
+      })
+    );
+
+    return {
+      status: overallStatus,
+      uptime: Math.floor((Date.now() - this.startTime) / 1000),
+      timestamp: new Date().toISOString(),
+      checks: results,
+    };
+  }
+
+  liveness(isShuttingDown: boolean): HealthResponse {
+    return {
+      status: isShuttingDown ? "unhealthy" : "healthy",
+      uptime: Math.floor((Date.now() - this.startTime) / 1000),
+      timestamp: new Date().toISOString(),
+      checks: {},
+    };
+  }
+}
+
+/**
+ * Create a built-in database health check.
+ */
+export function createDbHealthCheck(db: Kysely<any>): HealthCheck {
+  return {
+    name: "database",
+    critical: true,
+    check: async () => {
+      const start = Date.now();
+      try {
+        await db.selectFrom(db.dynamic.ref("sqlite_master") as any)
+          .select(db.dynamic.ref("1") as any)
+          .execute()
+          .catch(async () => {
+            // Fallback for non-SQLite databases
+            const { sql } = await import("kysely");
+            await sql`SELECT 1`.execute(db);
+          });
+        return {
+          status: "healthy" as const,
+          latencyMs: Date.now() - start,
+        };
+      } catch (err) {
+        return {
+          status: "unhealthy" as const,
+          message: err instanceof Error ? err.message : String(err),
+          latencyMs: Date.now() - start,
+        };
+      }
+    },
+  };
+}
+
+export function createHealth(config?: HealthConfig): Health {
+  return new HealthImpl(config);
+}

package/src/core/index.ts

@@ -21,6 +21,7 @@ export {
 export {
   type Events,
   type EventHandler,
+  type EventMetadata,
   type Subscription,
   type EventRecord,
   type EventAdapter,
@@ -281,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,
@@ -302,3 +313,14 @@ export {
   PersistentTransport,
   type PersistentTransportConfig,
 } from "./logs-transport";
+
+export {
+  type Health,
+  type HealthCheck,
+  type HealthCheckResult,
+  type HealthConfig,
+  type HealthResponse,
+  type HealthStatus,
+  createHealth,
+  createDbHealthCheck,
+} from "./health";

package/src/core/jobs.ts

@@ -56,6 +56,8 @@ export interface Job {
   lastHeartbeat?: Date;
   /** Current process state */
   processState?: ExternalJobProcessState;
+  /** Trace ID for distributed tracing */
+  traceId?: string;
 }
 
 export interface JobHandler<T = any, R = any> {
@@ -66,6 +68,8 @@ export interface JobHandlerContext {
   logger?: Logger;
   emit?: (event: string, data?: Record<string, any>) => Promise<void>;
   log?: (level: LogLevel, message: string, data?: Record<string, any>) => void;
+  /** Trace ID for distributed tracing */
+  traceId?: string;
 }
 
 /** Options for listing all jobs */
@@ -128,9 +132,9 @@ export interface Jobs {
   /** Register an external job (Python, Go, Shell, etc.) */
   registerExternal(name: string, config: ExternalJobConfig): void;
   /** Enqueue a job (works for both in-process and external jobs) */
-  enqueue<T = any>(name: string, data: T, options?: { maxAttempts?: number }): Promise<string>;
+  enqueue<T = any>(name: string, data: T, options?: { maxAttempts?: number; traceId?: string }): Promise<string>;
   /** Schedule a job to run at a specific time */
-  schedule<T = any>(name: string, data: T, runAt: Date, options?: { maxAttempts?: number }): Promise<string>;
+  schedule<T = any>(name: string, data: T, runAt: Date, options?: { maxAttempts?: number; traceId?: string }): Promise<string>;
   /** Get a job by ID */
   get(jobId: string): Promise<Job | null>;
   /** Cancel a pending job */
@@ -339,7 +343,7 @@ class JobsImpl implements Jobs {
     return this.externalConfigs.has(name);
   }
 
-  async enqueue<T = any>(name: string, data: T, options: { maxAttempts?: number } = {}): Promise<string> {
+  async enqueue<T = any>(name: string, data: T, options: { maxAttempts?: number; traceId?: string } = {}): Promise<string> {
     const isExternal = this.isExternalJob(name);
 
     if (!isExternal && !this.handlers.has(name)) {
@@ -355,6 +359,7 @@ class JobsImpl implements Jobs {
       maxAttempts: options.maxAttempts ?? this.defaultMaxAttempts,
       external: isExternal || undefined,
       processState: isExternal ? "spawning" : undefined,
+      traceId: options.traceId,
     });
 
     return job.id;
@@ -364,7 +369,7 @@ class JobsImpl implements Jobs {
     name: string,
     data: T,
     runAt: Date,
-    options: { maxAttempts?: number } = {}
+    options: { maxAttempts?: number; traceId?: string } = {}
   ): Promise<string> {
     const isExternal = this.isExternalJob(name);
 
@@ -382,6 +387,7 @@ class JobsImpl implements Jobs {
       maxAttempts: options.maxAttempts ?? this.defaultMaxAttempts,
       external: isExternal || undefined,
       processState: isExternal ? "spawning" : undefined,
+      traceId: options.traceId,
     });
 
     return job.id;
@@ -1147,6 +1153,7 @@ class JobsImpl implements Jobs {
         logger: scopedLogger,
         emit,
         log,
+        traceId: job.traceId,
       });
 
       await this.adapter.update(job.id, {

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));
+  }
+}