@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/api/middleware/errorHandler.ts

@@ -0,0 +1,166 @@
+import { Context, MiddlewareHandler } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import { ZodError } from 'zod'
+import { ErrorCodes, ErrorResponse } from '../../types/api.types.js'
+
+/**
+ * Custom API error class for consistent error handling.
+ */
+export class ApiError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly statusCode: number = 400,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message)
+    this.name = 'ApiError'
+  }
+
+  toResponse(): ErrorResponse {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details && { details: this.details }),
+      },
+      status: this.statusCode,
+    } as ErrorResponse
+  }
+}
+
+/**
+ * Formats Zod validation errors into a readable format.
+ */
+function formatZodErrors(error: ZodError): string {
+  const issues = error.issues.map((issue) => {
+    const path = issue.path.join('.')
+    return path ? `${path}: ${issue.message}` : issue.message
+  })
+  return issues.join('; ')
+}
+
+/**
+ * Global error handler middleware.
+ * Catches all errors and returns consistent error responses.
+ */
+export const errorHandlerMiddleware: MiddlewareHandler = async (c: Context, next) => {
+  try {
+    return await next()
+  } catch (error) {
+    console.error('Error caught in error handler:', error)
+
+    // Handle custom API errors
+    if (error instanceof ApiError) {
+      const statusCode = error.statusCode as 400 | 401 | 403 | 404 | 409 | 429 | 500
+      return c.json(error.toResponse(), statusCode)
+    }
+
+    // Handle Zod validation errors
+    if (error instanceof ZodError) {
+      const response: ErrorResponse = {
+        error: {
+          code: ErrorCodes.VALIDATION_ERROR,
+          message: formatZodErrors(error),
+        },
+        status: 400,
+      }
+      return c.json(response, 400)
+    }
+
+    // Handle Hono HTTP exceptions
+    if (error instanceof HTTPException) {
+      const response: ErrorResponse = {
+        error: {
+          code: mapHttpStatusToCode(error.status),
+          message: error.message || getDefaultMessage(error.status),
+        },
+        status: error.status,
+      }
+      return c.json(response, error.status)
+    }
+
+    // Handle generic errors
+    const message = error instanceof Error ? error.message : 'An unexpected error occurred'
+    const response: ErrorResponse = {
+      error: {
+        code: ErrorCodes.INTERNAL_ERROR,
+        message: process.env.NODE_ENV === 'production' ? 'An unexpected error occurred' : message,
+      },
+      status: 500,
+    }
+    return c.json(response, 500)
+  }
+}
+
+/**
+ * Maps HTTP status codes to error codes.
+ */
+function mapHttpStatusToCode(status: number): string {
+  switch (status) {
+    case 400:
+      return ErrorCodes.BAD_REQUEST
+    case 401:
+      return ErrorCodes.UNAUTHORIZED
+    case 403:
+      return ErrorCodes.FORBIDDEN
+    case 404:
+      return ErrorCodes.NOT_FOUND
+    case 409:
+      return ErrorCodes.CONFLICT
+    case 429:
+      return ErrorCodes.RATE_LIMITED
+    default:
+      return ErrorCodes.INTERNAL_ERROR
+  }
+}
+
+/**
+ * Gets default error message for HTTP status codes.
+ */
+function getDefaultMessage(status: number): string {
+  switch (status) {
+    case 400:
+      return 'Bad request'
+    case 401:
+      return 'Unauthorized'
+    case 403:
+      return 'Forbidden'
+    case 404:
+      return 'Resource not found'
+    case 409:
+      return 'Resource conflict'
+    case 429:
+      return 'Too many requests'
+    default:
+      return 'Internal server error'
+  }
+}
+
+/**
+ * Helper function to throw not found errors.
+ */
+export function notFound(resource: string, id: string): never {
+  throw new ApiError(ErrorCodes.NOT_FOUND, `${resource} with id '${id}' not found`, 404)
+}
+
+/**
+ * Helper function to throw validation errors.
+ */
+export function validationError(message: string): never {
+  throw new ApiError(ErrorCodes.VALIDATION_ERROR, message, 400)
+}
+
+/**
+ * Helper function to throw conflict errors.
+ */
+export function conflict(message: string): never {
+  throw new ApiError(ErrorCodes.CONFLICT, message, 409)
+}
+
+/**
+ * Helper function to throw forbidden errors.
+ */
+export function forbidden(message: string): never {
+  throw new ApiError(ErrorCodes.FORBIDDEN, message, 403)
+}

package/src/api/middleware/rateLimit.ts

@@ -0,0 +1,360 @@
+import { Context, MiddlewareHandler } from 'hono'
+import { ErrorCodes } from '../../types/api.types.js'
+import { getLogger } from '../../utils/logger.js'
+
+const logger = getLogger('rate-limit')
+
+interface RateLimitEntry {
+  count: number
+  resetTime: number
+}
+
+function isRateLimitEntry(value: unknown): value is RateLimitEntry {
+  if (!value || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Partial<RateLimitEntry>
+  return (
+    typeof candidate.count === 'number' &&
+    Number.isFinite(candidate.count) &&
+    typeof candidate.resetTime === 'number' &&
+    Number.isFinite(candidate.resetTime)
+  )
+}
+
+/**
+ * Rate limit store interface for pluggable backends
+ */
+export interface RateLimitStore {
+  get(key: string): Promise<RateLimitEntry | undefined>
+  set(key: string, entry: RateLimitEntry, ttlMs: number): Promise<void>
+  increment(key: string, windowMs: number): Promise<RateLimitEntry>
+}
+
+/**
+ * In-memory rate limit store for development/single-instance deployments
+ */
+export class MemoryRateLimitStore implements RateLimitStore {
+  private store = new Map<string, RateLimitEntry>()
+  private cleanupInterval: ReturnType<typeof setInterval> | null = null
+
+  constructor() {
+    // Cleanup old entries periodically
+    this.cleanupInterval = setInterval(() => {
+      const now = Date.now()
+      for (const [key, entry] of this.store.entries()) {
+        if (entry.resetTime <= now) {
+          this.store.delete(key)
+        }
+      }
+    }, 60 * 1000)
+  }
+
+  async get(key: string): Promise<RateLimitEntry | undefined> {
+    const entry = this.store.get(key)
+    if (entry && entry.resetTime > Date.now()) {
+      return entry
+    }
+    return undefined
+  }
+
+  async set(key: string, entry: RateLimitEntry, _ttlMs: number): Promise<void> {
+    this.store.set(key, entry)
+  }
+
+  async increment(key: string, windowMs: number): Promise<RateLimitEntry> {
+    const now = Date.now()
+    let entry = this.store.get(key)
+
+    if (!entry || entry.resetTime <= now) {
+      entry = {
+        count: 1,
+        resetTime: now + windowMs,
+      }
+    } else {
+      entry.count++
+    }
+
+    this.store.set(key, entry)
+    return entry
+  }
+
+  destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval)
+      this.cleanupInterval = null
+    }
+    this.store.clear()
+  }
+}
+
+/**
+ * Redis rate limit store for distributed deployments
+ *
+ * Requires REDIS_URL environment variable to be set.
+ * Falls back to memory store if Redis is not available.
+ */
+export class RedisRateLimitStore implements RateLimitStore {
+  private redis: RedisClient | null = null
+  private readonly keyPrefix = 'ratelimit:'
+  private fallback: MemoryRateLimitStore
+  private connectionFailed = false
+
+  constructor() {
+    this.fallback = new MemoryRateLimitStore()
+    this.initRedis()
+  }
+
+  private async initRedis(): Promise<void> {
+    const redisUrl = process.env.REDIS_URL
+    if (!redisUrl) {
+      logger.warn('REDIS_URL not set, using in-memory store')
+      return
+    }
+
+    try {
+      // Dynamic import to avoid requiring ioredis in all environments
+      // We catch the import error and fall back to in-memory store
+      const redisModule = await import('ioredis').catch(() => {
+        logger.warn('ioredis module not installed, using in-memory store')
+        return null
+      })
+
+      if (!redisModule) {
+        return
+      }
+
+      // ioredis exports the class as default - use type assertion for dynamic import
+      const RedisConstructor = (redisModule.default || redisModule) as unknown as new (url: string) => RedisClient
+      const client = new RedisConstructor(redisUrl)
+      this.redis = client
+
+      client.on('error', (err: unknown) => {
+        const errMsg =
+          err && typeof err === 'object' && 'message' in err ? (err as { message: string }).message : 'Unknown error'
+        logger.error('Redis error', { error: errMsg })
+        this.connectionFailed = true
+      })
+
+      client.on('connect', () => {
+        logger.info('Connected to Redis')
+        this.connectionFailed = false
+      })
+
+      // ioredis connects automatically on construction
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      logger.warn('Redis connection failed, using in-memory fallback', { error: message })
+      this.connectionFailed = true
+    }
+  }
+
+  private isAvailable(): boolean {
+    return this.redis !== null && !this.connectionFailed && this.redis.status === 'ready'
+  }
+
+  async get(key: string): Promise<RateLimitEntry | undefined> {
+    if (!this.isAvailable()) {
+      return this.fallback.get(key)
+    }
+
+    try {
+      const data = await this.redis!.get(this.keyPrefix + key)
+      if (data) {
+        const parsed = JSON.parse(data) as unknown
+        if (isRateLimitEntry(parsed)) {
+          return parsed
+        }
+
+        logger.warn('Redis returned malformed rate limit entry; falling back to memory store', { key })
+      }
+      return undefined
+    } catch (err) {
+      logger.error('Redis get error', { key }, err instanceof Error ? err : undefined)
+      return this.fallback.get(key)
+    }
+  }
+
+  async set(key: string, entry: RateLimitEntry, ttlMs: number): Promise<void> {
+    if (!this.isAvailable()) {
+      return this.fallback.set(key, entry, ttlMs)
+    }
+
+    try {
+      await this.redis!.set(this.keyPrefix + key, JSON.stringify(entry), 'PX', ttlMs)
+    } catch (err) {
+      logger.error('Redis set error', { key }, err instanceof Error ? err : undefined)
+      await this.fallback.set(key, entry, ttlMs)
+    }
+  }
+
+  async increment(key: string, windowMs: number): Promise<RateLimitEntry> {
+    if (!this.isAvailable()) {
+      return this.fallback.increment(key, windowMs)
+    }
+
+    try {
+      const now = Date.now()
+      const redisKey = this.keyPrefix + key
+
+      // Use Redis MULTI/EXEC for atomic increment with expiry
+      const result = await this.redis!.multi()
+        .incr(redisKey)
+        .pexpireat(redisKey, now + windowMs)
+        .exec()
+
+      // ioredis returns [[null, result], [null, result]] format
+      const count = (result?.[0]?.[1] as number) ?? 1
+
+      return {
+        count,
+        resetTime: now + windowMs,
+      }
+    } catch (err) {
+      logger.error('Redis increment error', { key }, err instanceof Error ? err : undefined)
+      return this.fallback.increment(key, windowMs)
+    }
+  }
+
+  async destroy(): Promise<void> {
+    this.fallback.destroy()
+    if (this.redis) {
+      try {
+        await this.redis.disconnect()
+      } catch {
+        // Ignore disconnect errors
+      }
+      this.redis = null
+    }
+  }
+}
+
+// Type for ioredis client (minimal interface)
+interface RedisClient {
+  status: 'ready' | 'connecting' | 'reconnecting' | 'end'
+  on(event: string, callback: (arg: unknown) => void): void
+  disconnect(): Promise<void>
+  get(key: string): Promise<string | null>
+  set(key: string, value: string, ...args: (string | number)[]): Promise<'OK' | null>
+  incr(key: string): RedisChainable
+  pexpireat(key: string, timestamp: number): RedisChainable
+  multi(): RedisChainable
+  exec(): Promise<Array<[Error | null, unknown]> | null>
+}
+
+// Type for ioredis chainable commands
+interface RedisChainable {
+  incr(key: string): RedisChainable
+  pexpireat(key: string, timestamp: number): RedisChainable
+  exec(): Promise<Array<[Error | null, unknown]> | null>
+}
+
+interface RateLimitConfig {
+  windowMs: number
+  maxRequests: number
+  keyGenerator?: (c: Context) => string
+  store?: RateLimitStore
+}
+
+const DEFAULT_CONFIG: RateLimitConfig = {
+  windowMs: 60 * 1000, // 1 minute
+  maxRequests: 100,
+}
+
+// Global store instance - uses Redis if available, falls back to memory
+let globalStore: RateLimitStore | null = null
+
+/**
+ * Get or create the global rate limit store.
+ * Uses Redis if REDIS_URL is set, otherwise uses in-memory store.
+ */
+function getGlobalStore(): RateLimitStore {
+  if (!globalStore) {
+    if (process.env.REDIS_URL) {
+      globalStore = new RedisRateLimitStore()
+    } else {
+      globalStore = new MemoryRateLimitStore()
+    }
+  }
+  return globalStore
+}
+
+/**
+ * Rate limiting middleware.
+ * Limits requests to maxRequests per windowMs per client.
+ *
+ * Supports Redis for distributed deployments (set REDIS_URL env var).
+ * Falls back to in-memory store for single-instance deployments.
+ */
+export const rateLimitMiddleware = (config: Partial<RateLimitConfig> = {}): MiddlewareHandler => {
+  const { windowMs, maxRequests, keyGenerator } = { ...DEFAULT_CONFIG, ...config }
+  const store = config.store ?? getGlobalStore()
+
+  return async (c: Context, next) => {
+    // Generate a unique key for the client
+    const key = keyGenerator ? keyGenerator(c) : getClientKey(c)
+
+    const now = Date.now()
+
+    // Increment counter atomically
+    const entry = await store.increment(key, windowMs)
+
+    // Calculate remaining requests and time
+    const remaining = Math.max(0, maxRequests - entry.count)
+    const resetSeconds = Math.ceil((entry.resetTime - now) / 1000)
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', String(maxRequests))
+    c.header('X-RateLimit-Remaining', String(remaining))
+    c.header('X-RateLimit-Reset', String(resetSeconds))
+
+    // Check if rate limit exceeded
+    if (entry.count > maxRequests) {
+      c.header('Retry-After', String(resetSeconds))
+
+      return c.json(
+        {
+          error: {
+            code: ErrorCodes.RATE_LIMITED,
+            message: `Rate limit exceeded. Try again in ${resetSeconds} seconds`,
+          },
+          status: 429,
+        },
+        429
+      )
+    }
+
+    return next()
+  }
+}
+
+/**
+ * Generates a unique key for rate limiting based on the client.
+ * Uses API key if available, otherwise falls back to IP address.
+ */
+function getClientKey(c: Context): string {
+  // Try to use the authenticated user's API key
+  const auth = c.get('auth')
+  if (auth?.apiKey) {
+    return `api:${auth.apiKey}`
+  }
+
+  // Fall back to IP address
+  const forwarded = c.req.header('x-forwarded-for')
+  const ip = forwarded?.split(',')[0]?.trim() || c.req.header('x-real-ip') || 'unknown'
+  return `ip:${ip}`
+}
+
+/**
+ * Creates a rate limiter with custom settings per endpoint.
+ */
+export const createRateLimiter = (maxRequests: number, windowMs: number = 60000): MiddlewareHandler => {
+  return rateLimitMiddleware({ maxRequests, windowMs })
+}
+
+// Pre-configured rate limiters for different use cases
+export const standardRateLimit = rateLimitMiddleware() // 100 req/min
+export const strictRateLimit = rateLimitMiddleware({ maxRequests: 20 }) // 20 req/min
+export const searchRateLimit = rateLimitMiddleware({ maxRequests: 50 }) // 50 req/min
+export const uploadRateLimit = rateLimitMiddleware({ maxRequests: 10 }) // 10 req/min