@donkeylabs/server 0.1.0

package/src/core/jobs.ts

@@ -0,0 +1,334 @@
+// Core Jobs Service
+// Background job queue with scheduling
+
+import type { Events } from "./events";
+
+export type JobStatus = "pending" | "running" | "completed" | "failed" | "scheduled";
+
+export interface Job {
+  id: string;
+  name: string;
+  data: any;
+  status: JobStatus;
+  createdAt: Date;
+  runAt?: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  result?: any;
+  error?: string;
+  attempts: number;
+  maxAttempts: number;
+}
+
+export interface JobHandler<T = any, R = any> {
+  (data: T): Promise<R>;
+}
+
+export interface JobAdapter {
+  create(job: Omit<Job, "id">): Promise<Job>;
+  get(jobId: string): Promise<Job | null>;
+  update(jobId: string, updates: Partial<Job>): Promise<void>;
+  delete(jobId: string): Promise<boolean>;
+  getPending(limit?: number): Promise<Job[]>;
+  getScheduledReady(now: Date): Promise<Job[]>;
+  getByName(name: string, status?: JobStatus): Promise<Job[]>;
+}
+
+export interface JobsConfig {
+  adapter?: JobAdapter;
+  events?: Events;
+  concurrency?: number; // Max concurrent jobs, default 5
+  pollInterval?: number; // ms, default 1000
+  maxAttempts?: number; // Default retry attempts, default 3
+}
+
+export interface Jobs {
+  register<T = any, R = any>(name: string, handler: JobHandler<T, R>): void;
+  enqueue<T = any>(name: string, data: T, options?: { maxAttempts?: number }): Promise<string>;
+  schedule<T = any>(name: string, data: T, runAt: Date, options?: { maxAttempts?: number }): Promise<string>;
+  get(jobId: string): Promise<Job | null>;
+  cancel(jobId: string): Promise<boolean>;
+  getByName(name: string, status?: JobStatus): Promise<Job[]>;
+  start(): void;
+  stop(): Promise<void>;
+}
+
+// In-memory job adapter
+export class MemoryJobAdapter implements JobAdapter {
+  private jobs = new Map<string, Job>();
+  private counter = 0;
+
+  async create(job: Omit<Job, "id">): Promise<Job> {
+    const id = `job_${++this.counter}_${Date.now()}`;
+    const fullJob: Job = { ...job, id };
+    this.jobs.set(id, fullJob);
+    return fullJob;
+  }
+
+  async get(jobId: string): Promise<Job | null> {
+    return this.jobs.get(jobId) ?? null;
+  }
+
+  async update(jobId: string, updates: Partial<Job>): Promise<void> {
+    const job = this.jobs.get(jobId);
+    if (job) {
+      Object.assign(job, updates);
+    }
+  }
+
+  async delete(jobId: string): Promise<boolean> {
+    return this.jobs.delete(jobId);
+  }
+
+  async getPending(limit: number = 100): Promise<Job[]> {
+    const pending: Job[] = [];
+    for (const job of this.jobs.values()) {
+      if (job.status === "pending") {
+        pending.push(job);
+        if (pending.length >= limit) break;
+      }
+    }
+    return pending;
+  }
+
+  async getScheduledReady(now: Date): Promise<Job[]> {
+    const ready: Job[] = [];
+    for (const job of this.jobs.values()) {
+      if (job.status === "scheduled" && job.runAt && job.runAt <= now) {
+        ready.push(job);
+      }
+    }
+    return ready;
+  }
+
+  async getByName(name: string, status?: JobStatus): Promise<Job[]> {
+    const results: Job[] = [];
+    for (const job of this.jobs.values()) {
+      if (job.name === name && (!status || job.status === status)) {
+        results.push(job);
+      }
+    }
+    return results;
+  }
+}
+
+class JobsImpl implements Jobs {
+  private adapter: JobAdapter;
+  private events?: Events;
+  private handlers = new Map<string, JobHandler>();
+  private running = false;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private activeJobs = 0;
+  private concurrency: number;
+  private pollInterval: number;
+  private defaultMaxAttempts: number;
+
+  constructor(config: JobsConfig = {}) {
+    this.adapter = config.adapter ?? new MemoryJobAdapter();
+    this.events = config.events;
+    this.concurrency = config.concurrency ?? 5;
+    this.pollInterval = config.pollInterval ?? 1000;
+    this.defaultMaxAttempts = config.maxAttempts ?? 3;
+  }
+
+  register<T = any, R = any>(name: string, handler: JobHandler<T, R>): void {
+    if (this.handlers.has(name)) {
+      throw new Error(`Job handler "${name}" is already registered`);
+    }
+    this.handlers.set(name, handler);
+  }
+
+  async enqueue<T = any>(name: string, data: T, options: { maxAttempts?: number } = {}): Promise<string> {
+    if (!this.handlers.has(name)) {
+      throw new Error(`No handler registered for job "${name}"`);
+    }
+
+    const job = await this.adapter.create({
+      name,
+      data,
+      status: "pending",
+      createdAt: new Date(),
+      attempts: 0,
+      maxAttempts: options.maxAttempts ?? this.defaultMaxAttempts,
+    });
+
+    return job.id;
+  }
+
+  async schedule<T = any>(
+    name: string,
+    data: T,
+    runAt: Date,
+    options: { maxAttempts?: number } = {}
+  ): Promise<string> {
+    if (!this.handlers.has(name)) {
+      throw new Error(`No handler registered for job "${name}"`);
+    }
+
+    const job = await this.adapter.create({
+      name,
+      data,
+      status: "scheduled",
+      createdAt: new Date(),
+      runAt,
+      attempts: 0,
+      maxAttempts: options.maxAttempts ?? this.defaultMaxAttempts,
+    });
+
+    return job.id;
+  }
+
+  async get(jobId: string): Promise<Job | null> {
+    return this.adapter.get(jobId);
+  }
+
+  async cancel(jobId: string): Promise<boolean> {
+    const job = await this.adapter.get(jobId);
+    if (!job) return false;
+
+    if (job.status === "running") {
+      // Can't cancel running job
+      return false;
+    }
+
+    return this.adapter.delete(jobId);
+  }
+
+  async getByName(name: string, status?: JobStatus): Promise<Job[]> {
+    return this.adapter.getByName(name, status);
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+
+    this.timer = setInterval(() => this.tick(), this.pollInterval);
+    // Run immediately too
+    this.tick();
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+
+    // Wait for active jobs to complete (with timeout)
+    const maxWait = 30000; // 30 seconds
+    const start = Date.now();
+    while (this.activeJobs > 0 && Date.now() - start < maxWait) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  }
+
+  private async tick(): Promise<void> {
+    if (!this.running) return;
+
+    try {
+      // Process scheduled jobs that are ready
+      const now = new Date();
+      const scheduledReady = await this.adapter.getScheduledReady(now);
+      for (const job of scheduledReady) {
+        await this.adapter.update(job.id, { status: "pending" });
+      }
+
+      // Process pending jobs
+      const availableSlots = this.concurrency - this.activeJobs;
+      if (availableSlots <= 0) return;
+
+      const pending = await this.adapter.getPending(availableSlots);
+      for (const job of pending) {
+        if (this.activeJobs >= this.concurrency) break;
+        this.processJob(job);
+      }
+    } catch (err) {
+      console.error("[Jobs] Tick error:", err);
+    }
+  }
+
+  private async processJob(job: Job): Promise<void> {
+    const handler = this.handlers.get(job.name);
+    if (!handler) {
+      await this.adapter.update(job.id, {
+        status: "failed",
+        error: `No handler registered for job "${job.name}"`,
+        completedAt: new Date(),
+      });
+      return;
+    }
+
+    this.activeJobs++;
+    const startedAt = new Date();
+
+    try {
+      await this.adapter.update(job.id, {
+        status: "running",
+        startedAt,
+        attempts: job.attempts + 1,
+      });
+
+      const result = await handler(job.data);
+
+      await this.adapter.update(job.id, {
+        status: "completed",
+        completedAt: new Date(),
+        result,
+      });
+
+      // Emit completion event
+      if (this.events) {
+        await this.events.emit(`job.completed`, {
+          jobId: job.id,
+          name: job.name,
+          result,
+        });
+        await this.events.emit(`job.${job.name}.completed`, {
+          jobId: job.id,
+          result,
+        });
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      const attempts = job.attempts + 1;
+
+      if (attempts < job.maxAttempts) {
+        // Retry later
+        await this.adapter.update(job.id, {
+          status: "pending",
+          attempts,
+          error,
+        });
+      } else {
+        // Max attempts reached, mark as failed
+        await this.adapter.update(job.id, {
+          status: "failed",
+          completedAt: new Date(),
+          attempts,
+          error,
+        });
+
+        // Emit failure event
+        if (this.events) {
+          await this.events.emit(`job.failed`, {
+            jobId: job.id,
+            name: job.name,
+            error,
+            attempts,
+          });
+          await this.events.emit(`job.${job.name}.failed`, {
+            jobId: job.id,
+            error,
+            attempts,
+          });
+        }
+      }
+    } finally {
+      this.activeJobs--;
+    }
+  }
+}
+
+export function createJobs(config?: JobsConfig): Jobs {
+  return new JobsImpl(config);
+}

package/src/core/logger.ts

@@ -0,0 +1,131 @@
+// Core Logger Service
+// Structured logging with levels and child loggers
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LogEntry {
+  timestamp: Date;
+  level: LogLevel;
+  message: string;
+  data?: Record<string, any>;
+  context?: Record<string, any>;
+}
+
+export interface LogTransport {
+  log(entry: LogEntry): void;
+}
+
+export interface LoggerConfig {
+  level?: LogLevel;
+  transports?: LogTransport[];
+  format?: "json" | "pretty";
+}
+
+export interface Logger {
+  debug(message: string, data?: Record<string, any>): void;
+  info(message: string, data?: Record<string, any>): void;
+  warn(message: string, data?: Record<string, any>): void;
+  error(message: string, data?: Record<string, any>): void;
+  child(context: Record<string, any>): Logger;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  debug: "\x1b[90m", // gray
+  info: "\x1b[36m",  // cyan
+  warn: "\x1b[33m",  // yellow
+  error: "\x1b[31m", // red
+};
+
+const RESET = "\x1b[0m";
+
+// Console transport with pretty or JSON formatting
+export class ConsoleTransport implements LogTransport {
+  constructor(private format: "json" | "pretty" = "pretty") {}
+
+  log(entry: LogEntry): void {
+    if (this.format === "json") {
+      console.log(JSON.stringify({
+        timestamp: entry.timestamp.toISOString(),
+        level: entry.level,
+        message: entry.message,
+        ...entry.data,
+        ...entry.context,
+      }));
+    } else {
+      const color = LEVEL_COLORS[entry.level];
+      const time = entry.timestamp.toISOString().slice(11, 23);
+      const level = entry.level.toUpperCase().padEnd(5);
+
+      let output = `${color}[${time}] ${level}${RESET} ${entry.message}`;
+
+      const extra = { ...entry.data, ...entry.context };
+      if (Object.keys(extra).length > 0) {
+        output += ` ${"\x1b[90m"}${JSON.stringify(extra)}${RESET}`;
+      }
+
+      console.log(output);
+    }
+  }
+}
+
+class LoggerImpl implements Logger {
+  private minLevel: number;
+  private transports: LogTransport[];
+  private context: Record<string, any>;
+
+  constructor(config: LoggerConfig = {}, context: Record<string, any> = {}) {
+    this.minLevel = LOG_LEVELS[config.level ?? "info"];
+    this.transports = config.transports ?? [new ConsoleTransport(config.format ?? "pretty")];
+    this.context = context;
+  }
+
+  private log(level: LogLevel, message: string, data?: Record<string, any>): void {
+    if (LOG_LEVELS[level] < this.minLevel) return;
+
+    const entry: LogEntry = {
+      timestamp: new Date(),
+      level,
+      message,
+      data,
+      context: Object.keys(this.context).length > 0 ? this.context : undefined,
+    };
+
+    for (const transport of this.transports) {
+      transport.log(entry);
+    }
+  }
+
+  debug(message: string, data?: Record<string, any>): void {
+    this.log("debug", message, data);
+  }
+
+  info(message: string, data?: Record<string, any>): void {
+    this.log("info", message, data);
+  }
+
+  warn(message: string, data?: Record<string, any>): void {
+    this.log("warn", message, data);
+  }
+
+  error(message: string, data?: Record<string, any>): void {
+    this.log("error", message, data);
+  }
+
+  child(context: Record<string, any>): Logger {
+    return new LoggerImpl(
+      { level: Object.keys(LOG_LEVELS).find(k => LOG_LEVELS[k as LogLevel] === this.minLevel) as LogLevel, transports: this.transports },
+      { ...this.context, ...context }
+    );
+  }
+}
+
+export function createLogger(config?: LoggerConfig): Logger {
+  return new LoggerImpl(config);
+}

package/src/core/rate-limiter.ts

@@ -0,0 +1,193 @@
+// Core Rate Limiter Service
+// Request throttling with IP detection
+
+export interface RateLimitResult {
+  allowed: boolean;
+  remaining: number;
+  limit: number;
+  resetAt: Date;
+  retryAfter?: number; // seconds until retry
+}
+
+export interface RateLimitAdapter {
+  increment(key: string, windowMs: number): Promise<{ count: number; resetAt: Date }>;
+  get(key: string): Promise<{ count: number; resetAt: Date } | null>;
+  reset(key: string): Promise<void>;
+}
+
+export interface RateLimiterConfig {
+  adapter?: RateLimitAdapter;
+}
+
+export interface RateLimiter {
+  check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>;
+  reset(key: string): Promise<void>;
+}
+
+// In-memory rate limit adapter using sliding window
+export class MemoryRateLimitAdapter implements RateLimitAdapter {
+  private windows = new Map<string, { count: number; resetAt: Date }>();
+
+  async increment(key: string, windowMs: number): Promise<{ count: number; resetAt: Date }> {
+    const now = Date.now();
+    const existing = this.windows.get(key);
+
+    if (existing && existing.resetAt.getTime() > now) {
+      // Window still active
+      existing.count++;
+      return { count: existing.count, resetAt: existing.resetAt };
+    }
+
+    // Create new window
+    const resetAt = new Date(now + windowMs);
+    const entry = { count: 1, resetAt };
+    this.windows.set(key, entry);
+
+    // Clean up old entries periodically
+    this.cleanup();
+
+    return entry;
+  }
+
+  async get(key: string): Promise<{ count: number; resetAt: Date } | null> {
+    const entry = this.windows.get(key);
+    if (!entry) return null;
+
+    if (entry.resetAt.getTime() <= Date.now()) {
+      this.windows.delete(key);
+      return null;
+    }
+
+    return entry;
+  }
+
+  async reset(key: string): Promise<void> {
+    this.windows.delete(key);
+  }
+
+  private cleanup(): void {
+    const now = Date.now();
+    // Only cleanup occasionally to avoid performance issues
+    if (Math.random() > 0.1) return;
+
+    for (const [key, entry] of this.windows.entries()) {
+      if (entry.resetAt.getTime() <= now) {
+        this.windows.delete(key);
+      }
+    }
+  }
+}
+
+class RateLimiterImpl implements RateLimiter {
+  private adapter: RateLimitAdapter;
+
+  constructor(config: RateLimiterConfig = {}) {
+    this.adapter = config.adapter ?? new MemoryRateLimitAdapter();
+  }
+
+  async check(key: string, limit: number, windowMs: number): Promise<RateLimitResult> {
+    const { count, resetAt } = await this.adapter.increment(key, windowMs);
+
+    const allowed = count <= limit;
+    const remaining = Math.max(0, limit - count);
+
+    const result: RateLimitResult = {
+      allowed,
+      remaining,
+      limit,
+      resetAt,
+    };
+
+    if (!allowed) {
+      result.retryAfter = Math.ceil((resetAt.getTime() - Date.now()) / 1000);
+    }
+
+    return result;
+  }
+
+  async reset(key: string): Promise<void> {
+    await this.adapter.reset(key);
+  }
+}
+
+export function createRateLimiter(config?: RateLimiterConfig): RateLimiter {
+  return new RateLimiterImpl(config);
+}
+
+// IP Extraction Utilities
+const IP_HEADERS = [
+  "cf-connecting-ip",
+  "true-client-ip",
+  "x-real-ip",
+  "x-forwarded-for",
+] as const;
+
+/** Extract client IP address from request headers (handles Cloudflare, Nginx, etc.) */
+export function extractClientIP(req: Request, socketAddr?: string): string {
+  for (const header of IP_HEADERS) {
+    const value = req.headers.get(header);
+    if (value) {
+      // X-Forwarded-For may contain multiple IPs: "client, proxy1, proxy2"
+      if (header === "x-forwarded-for") {
+        const firstIP = value.split(",")[0]?.trim();
+        if (firstIP && isValidIP(firstIP)) return firstIP;
+      } else {
+        if (isValidIP(value)) return value;
+      }
+    }
+  }
+
+  // Fall back to socket address
+  if (socketAddr && isValidIP(socketAddr)) {
+    return socketAddr;
+  }
+
+  return "unknown";
+}
+
+/** Basic IP address validation (IPv4 and IPv6) */
+function isValidIP(ip: string): boolean {
+  // IPv4 pattern
+  const ipv4Pattern = /^(\d{1,3}\.){3}\d{1,3}$/;
+  if (ipv4Pattern.test(ip)) {
+    const parts = ip.split(".").map(Number);
+    return parts.every(n => n >= 0 && n <= 255);
+  }
+
+  // IPv6 pattern (simplified)
+  const ipv6Pattern = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
+  if (ipv6Pattern.test(ip)) return true;
+
+  // IPv4-mapped IPv6
+  if (ip.startsWith("::ffff:")) {
+    const ipv4Part = ip.slice(7);
+    return isValidIP(ipv4Part);
+  }
+
+  return false;
+}
+
+/** Parse duration string to milliseconds (supports: "100ms", "10s", "5m", "1h", "1d") */
+export function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)(ms|s|m|h|d)$/);
+  if (!match || !match[1] || !match[2]) {
+    throw new Error(`Invalid duration format: ${duration}. Use format like "10s", "5m", "1h"`);
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  switch (unit) {
+    case "ms": return value;
+    case "s": return value * 1000;
+    case "m": return value * 60 * 1000;
+    case "h": return value * 60 * 60 * 1000;
+    case "d": return value * 24 * 60 * 60 * 1000;
+    default: throw new Error(`Unknown duration unit: ${unit}`);
+  }
+}
+
+/** Create a rate limit key for a specific route + IP combination */
+export function createRateLimitKey(route: string, ip: string): string {
+  return `ratelimit:${route}:${ip}`;
+}