@mantiq/core 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantiq/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Service container, router, middleware, HTTP kernel, config, and exception handler",
   "type": "module",
   "license": "MIT",

package/src/exceptions/Handler.ts

@@ -54,10 +54,7 @@ export class DefaultExceptionHandler implements ExceptionHandler {
       return MantiqResponse.redirect((err as any).redirectTo)
     }
 
-    if (debug) {
-      return MantiqResponse.html(renderDevErrorPage(request, err), err.statusCode)
-    }
-
+    // API routes always get JSON — even in debug mode
     if (request.expectsJson()) {
       const body: Record<string, any> = {
         error: { message: err.message, status: err.statusCode },
@@ -65,9 +62,16 @@ export class DefaultExceptionHandler implements ExceptionHandler {
       if (err instanceof ValidationError) {
         body['error']['errors'] = err.errors
       }
+      if (debug && err.stack) {
+        body['error']['trace'] = err.stack.split('\n').map((l: string) => l.trim())
+      }
       return MantiqResponse.json(body, err.statusCode, err.headers)
     }
 
+    if (debug) {
+      return MantiqResponse.html(renderDevErrorPage(request, err), err.statusCode)
+    }
+
     return MantiqResponse.html(
       this.genericHtmlPage(err.statusCode, err.message),
       err.statusCode,
@@ -79,15 +83,18 @@ export class DefaultExceptionHandler implements ExceptionHandler {
     err: Error,
     debug: boolean,
   ): Response {
-    if (debug) {
-      return MantiqResponse.html(renderDevErrorPage(request, err), 500)
+    // API routes always get JSON — even in debug mode
+    if (request.expectsJson()) {
+      const body: Record<string, any> = { error: { message: 'Internal Server Error', status: 500 } }
+      if (debug && err.stack) {
+        body['error']['message'] = err.message
+        body['error']['trace'] = err.stack.split('\n').map((l: string) => l.trim())
+      }
+      return MantiqResponse.json(body, 500)
     }
 
-    if (request.expectsJson()) {
-      return MantiqResponse.json(
-        { error: { message: 'Internal Server Error', status: 500 } },
-        500,
-      )
+    if (debug) {
+      return MantiqResponse.html(renderDevErrorPage(request, err), 500)
     }
 
     return MantiqResponse.html(this.genericHtmlPage(500, 'Internal Server Error'), 500)

package/src/http/Request.ts

@@ -133,6 +133,8 @@ export class MantiqRequest implements MantiqRequestContract {
   }
 
   expectsJson(): boolean {
+    // Routes under /api/ always expect JSON responses
+    if (this.path().startsWith('/api/') || this.path() === '/api') return true
     const accept = this.header('accept') ?? ''
     return accept.includes('application/json') || accept.includes('text/json')
   }

package/src/index.ts

@@ -53,6 +53,9 @@ export { TrimStringsMiddleware } from './middleware/TrimStrings.ts'
 export { StartSession } from './middleware/StartSession.ts'
 export { EncryptCookies } from './middleware/EncryptCookies.ts'
 export { VerifyCsrfToken } from './middleware/VerifyCsrfToken.ts'
+export { RateLimiter, MemoryStore } from './rateLimit/RateLimiter.ts'
+export type { RateLimitConfig, RateLimitStore, LimiterResolver } from './rateLimit/RateLimiter.ts'
+export { ThrottleRequests } from './rateLimit/ThrottleRequests.ts'
 export { WebSocketKernel } from './websocket/WebSocketKernel.ts'
 export { DefaultExceptionHandler } from './exceptions/Handler.ts'
 export { CoreServiceProvider } from './providers/CoreServiceProvider.ts'

package/src/rateLimit/RateLimiter.ts

@@ -0,0 +1,146 @@
+/**
+ * Rate limiter — tracks request counts per key within time windows.
+ *
+ * Supports named limiters with custom resolvers, and pluggable stores
+ * (memory by default, cache/Redis when available).
+ *
+ * @example
+ * const limiter = new RateLimiter()
+ *
+ * // Define a named limiter
+ * limiter.for('api', (request) => ({
+ *   key: request.ip(),
+ *   maxAttempts: 60,
+ *   decayMinutes: 1,
+ * }))
+ *
+ * // Or with multiple limits
+ * limiter.for('uploads', (request) => [
+ *   { key: request.ip(), maxAttempts: 10, decayMinutes: 1 },
+ *   { key: request.user()?.id ?? request.ip(), maxAttempts: 100, decayMinutes: 60 },
+ * ])
+ */
+
+export interface RateLimitConfig {
+  key: string
+  maxAttempts: number
+  decayMinutes: number
+  responseCallback?: (request: any, headers: Record<string, string>) => Response | void
+}
+
+export interface RateLimitStore {
+  /** Get current hit count for key. */
+  get(key: string): Promise<number>
+  /** Increment hit count. Returns new count. */
+  increment(key: string, decaySeconds: number): Promise<number>
+  /** Get remaining seconds until the key resets. */
+  availableIn(key: string): Promise<number>
+  /** Reset a key. */
+  clear(key: string): Promise<void>
+}
+
+export type LimiterResolver = (request: any) => RateLimitConfig | RateLimitConfig[]
+
+export class RateLimiter {
+  private limiters = new Map<string, LimiterResolver>()
+  private store: RateLimitStore
+
+  constructor(store?: RateLimitStore) {
+    this.store = store ?? new MemoryStore()
+  }
+
+  /** Define a named rate limiter. */
+  for(name: string, resolver: LimiterResolver): this {
+    this.limiters.set(name, resolver)
+    return this
+  }
+
+  /** Get a named limiter resolver. */
+  limiter(name: string): LimiterResolver | undefined {
+    return this.limiters.get(name)
+  }
+
+  /** Check if a key has too many attempts. */
+  async tooManyAttempts(key: string, maxAttempts: number): Promise<boolean> {
+    const attempts = await this.store.get(key)
+    return attempts >= maxAttempts
+  }
+
+  /** Record a hit for a key. Returns the new count. */
+  async hit(key: string, decaySeconds: number): Promise<number> {
+    return this.store.increment(key, decaySeconds)
+  }
+
+  /** Get current attempt count. */
+  async attempts(key: string): Promise<number> {
+    return this.store.get(key)
+  }
+
+  /** Get remaining attempts. */
+  async remaining(key: string, maxAttempts: number): Promise<number> {
+    const current = await this.store.get(key)
+    return Math.max(0, maxAttempts - current)
+  }
+
+  /** Get seconds until the rate limit resets. */
+  async availableIn(key: string): Promise<number> {
+    return this.store.availableIn(key)
+  }
+
+  /** Reset a key's attempt count. */
+  async clear(key: string): Promise<void> {
+    return this.store.clear(key)
+  }
+
+  /** Set the backing store (memory, cache, redis). */
+  setStore(store: RateLimitStore): void {
+    this.store = store
+  }
+}
+
+// ── Memory Store (default) ───────────────────────────────────────────────────
+
+interface MemoryEntry {
+  count: number
+  expiresAt: number // unix ms
+}
+
+export class MemoryStore implements RateLimitStore {
+  private entries = new Map<string, MemoryEntry>()
+
+  async get(key: string): Promise<number> {
+    const entry = this.entries.get(key)
+    if (!entry) return 0
+    if (Date.now() > entry.expiresAt) {
+      this.entries.delete(key)
+      return 0
+    }
+    return entry.count
+  }
+
+  async increment(key: string, decaySeconds: number): Promise<number> {
+    const existing = this.entries.get(key)
+    const now = Date.now()
+
+    if (existing && now <= existing.expiresAt) {
+      existing.count++
+      return existing.count
+    }
+
+    // New window
+    const entry: MemoryEntry = { count: 1, expiresAt: now + decaySeconds * 1000 }
+    this.entries.set(key, entry)
+    return 1
+  }
+
+  async availableIn(key: string): Promise<number> {
+    const entry = this.entries.get(key)
+    if (!entry) return 0
+    const remaining = Math.ceil((entry.expiresAt - Date.now()) / 1000)
+    return Math.max(0, remaining)
+  }
+
+  async clear(key: string): Promise<void> {
+    this.entries.delete(key)
+  }
+}

package/src/rateLimit/ThrottleRequests.ts

@@ -0,0 +1,135 @@
+import type { MantiqRequest } from '../contracts/Request.ts'
+import { HttpError } from '../errors/HttpError.ts'
+import type { RateLimiter, RateLimitConfig } from './RateLimiter.ts'
+
+/**
+ * Middleware that throttles requests using the RateLimiter.
+ *
+ * Usage with named limiter:
+ *   router.get('/api/data', handler).middleware('throttle:api')
+ *
+ * Usage with inline limits:
+ *   router.get('/api/data', handler).middleware('throttle:60,1')
+ *   // 60 requests per 1 minute, keyed by IP
+ *
+ * Response headers:
+ *   X-RateLimit-Limit: 60
+ *   X-RateLimit-Remaining: 45
+ *   Retry-After: 30 (only when rate limited)
+ */
+export class ThrottleRequests {
+  private params: string[] = []
+
+  constructor(private readonly rateLimiter: RateLimiter) {}
+
+  setParameters(...params: string[]): void {
+    this.params = params
+  }
+
+  async handle(request: MantiqRequest, next: () => Promise<Response>): Promise<Response> {
+    const configs = this.resolveConfigs(request)
+
+    // Check all limits before proceeding
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+
+      if (await this.rateLimiter.tooManyAttempts(fullKey, config.maxAttempts)) {
+        const retryAfter = await this.rateLimiter.availableIn(fullKey)
+        return this.buildTooManyResponse(request, config, retryAfter)
+      }
+    }
+
+    // Record hits
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+      await this.rateLimiter.hit(fullKey, config.decayMinutes * 60)
+    }
+
+    // Process request
+    const response = await next()
+
+    // Add rate limit headers (use the most restrictive limit)
+    return this.addHeaders(response, configs)
+  }
+
+  private resolveConfigs(request: MantiqRequest): RateLimitConfig[] {
+    if (this.params.length === 0) {
+      // Default: 60 per minute by IP
+      return [{ key: request.ip(), maxAttempts: 60, decayMinutes: 1 }]
+    }
+
+    const first = this.params[0]!
+
+    // Check if it's a named limiter
+    const resolver = this.rateLimiter.limiter(first)
+    if (resolver) {
+      const result = resolver(request)
+      return Array.isArray(result) ? result : [result]
+    }
+
+    // Inline: throttle:maxAttempts,decayMinutes
+    const maxAttempts = parseInt(first, 10) || 60
+    const decayMinutes = parseInt(this.params[1] ?? '1', 10) || 1
+
+    return [{
+      key: request.ip(),
+      maxAttempts,
+      decayMinutes,
+    }]
+  }
+
+  private buildTooManyResponse(
+    request: MantiqRequest,
+    config: RateLimitConfig,
+    retryAfter: number,
+  ): Response {
+    if (config.responseCallback) {
+      const headers: Record<string, string> = {
+        'Retry-After': String(retryAfter),
+        'X-RateLimit-Limit': String(config.maxAttempts),
+        'X-RateLimit-Remaining': '0',
+      }
+      const custom = config.responseCallback(request, headers)
+      if (custom) return custom
+    }
+
+    const body = request.expectsJson()
+      ? JSON.stringify({ message: 'Too Many Requests', retry_after: retryAfter })
+      : 'Too Many Requests'
+
+    return new Response(body, {
+      status: 429,
+      headers: {
+        'Content-Type': request.expectsJson() ? 'application/json' : 'text/plain',
+        'Retry-After': String(retryAfter),
+        'X-RateLimit-Limit': String(config.maxAttempts),
+        'X-RateLimit-Remaining': '0',
+      },
+    })
+  }
+
+  private async addHeaders(response: Response, configs: RateLimitConfig[]): Promise<Response> {
+    // Use the most restrictive limit for headers
+    let minRemaining = Infinity
+    let limit = 0
+
+    for (const config of configs) {
+      const fullKey = `rate_limit:${config.key}`
+      const remaining = await this.rateLimiter.remaining(fullKey, config.maxAttempts)
+      if (remaining < minRemaining) {
+        minRemaining = remaining
+        limit = config.maxAttempts
+      }
+    }
+
+    const headers = new Headers(response.headers)
+    headers.set('X-RateLimit-Limit', String(limit))
+    headers.set('X-RateLimit-Remaining', String(minRemaining))
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    })
+  }
+}