@stacksjs/bun-router 0.0.15 → 0.0.17

package/src/middleware/rate_limit.ts

@@ -1,3 +1,4 @@
+import type { StorageProvider } from 'ts-rate-limiter'
 import type { EnhancedRequest, Middleware, MiddlewareHandler, NextFunction } from '../types'
 import { createRateLimiter } from 'ts-rate-limiter'
 import { config } from '../config'
@@ -11,7 +12,12 @@ export interface RateLimitOptions {
   keyGenerator?: (request: Request) => string | Promise<string>
   handler?: (request: Request, limit: { remaining: number, limit: number, resetTime: number }) => Response | Promise<Response>
   skip?: (request: Request) => boolean | Promise<boolean>
-  storage?: any
+  /**
+   * Custom storage backend (ts-rate-limiter `StorageProvider`), or the
+   * string `'redis'` to use the built-in Redis store configured via
+   * the `redis` option.
+   */
+  storage?: StorageProvider | 'redis'
   algorithm?: 'fixed-window' | 'sliding-window' | 'token-bucket'
   draftMode?: boolean
   redis?: {

package/src/middleware/request_signing.ts

@@ -149,6 +149,8 @@ export class InMemoryNonceStore implements NonceStore {
 
   constructor(cleanupIntervalMs: number = 60000) {
     this.cleanupInterval = setInterval(() => this.cleanup(), cleanupIntervalMs)
+    // Background housekeeping must not keep the process alive
+    this.cleanupInterval.unref?.()
   }
 
   has(nonce: string): boolean {

package/src/middleware/request_tracer.ts

@@ -9,18 +9,30 @@ export interface TraceSpan {
   startTime: number
   endTime?: number
   duration?: number
-  tags: Record<string, any>
+  tags: Record<string, unknown>
   logs: Array<{
     timestamp: number
     level: 'debug' | 'info' | 'warn' | 'error'
     message: string
-    fields?: Record<string, any>
+    fields?: Record<string, unknown>
   }>
   status: 'ok' | 'error' | 'timeout'
   error?: string
   stackTrace?: string[]
 }
 
+/**
+ * Destination for exported spans. `endpoint`/`headers` configure the
+ * HTTP-based exporters (jaeger/zipkin/otlp); `customExporter` receives
+ * the spans directly.
+ */
+export interface TraceExporterConfig {
+  type: 'console' | 'jaeger' | 'zipkin' | 'otlp' | 'custom'
+  endpoint?: string
+  headers?: Record<string, string>
+  customExporter?: (spans: TraceSpan[]) => Promise<void>
+}
+
 export interface TracingOptions {
   enabled?: boolean
   sampleRate?: number
@@ -30,12 +42,7 @@ export interface TracingOptions {
   includeRequestBody?: boolean
   includeResponseBody?: boolean
   maxBodySize?: number
-  exporters?: Array<{
-    type: 'console' | 'jaeger' | 'zipkin' | 'otlp' | 'custom'
-    endpoint?: string
-    headers?: Record<string, string>
-    customExporter?: (spans: TraceSpan[]) => Promise<void>
-  }>
+  exporters?: TraceExporterConfig[]
   propagation?: {
     enabled?: boolean
     headers?: string[]
@@ -83,6 +90,8 @@ export default class RequestTracer {
         console.warn('Error exporting spans:', error)
       }
     }, 100) // Export every 100ms for faster testing
+    // Background export must not keep the process alive
+    this.exportInterval.unref?.()
   }
 
   private shouldSample(): boolean {
@@ -120,7 +129,7 @@ export default class RequestTracer {
     return { traceId, parentSpanId }
   }
 
-  private async captureRequestBody(req: EnhancedRequest): Promise<any> {
+  private async captureRequestBody(req: EnhancedRequest): Promise<unknown> {
     if (!this.options.includeRequestBody)
       return undefined
 
@@ -157,7 +166,7 @@ export default class RequestTracer {
     return undefined
   }
 
-  private async captureResponseBody(response: Response): Promise<any> {
+  private async captureResponseBody(response: Response): Promise<unknown> {
     if (!this.options.includeResponseBody)
       return undefined
 
@@ -203,7 +212,7 @@ export default class RequestTracer {
     }
   }
 
-  private addSpanTag(spanId: string, key: string, value: any): void {
+  private addSpanTag(spanId: string, key: string, value: unknown): void {
     const span = this.spans.get(spanId)
     if (span) {
       span.tags[key] = value
@@ -247,15 +256,23 @@ export default class RequestTracer {
   }
 
   private async exportSpans(): Promise<void> {
-    // For debugging
-    console.warn(`[RequestTracer] Exporting spans, queue size: ${this.exportQueue.length}, active spans: ${this.spans.size}`)
+    // Drop orphaned spans: anything unfinished for over a minute will
+    // never be completed (its request died mid-flight) and would pin the
+    // map forever
+    if (this.spans.size > 0) {
+      const cutoff = performance.now() - 60_000
+      for (const [spanId, span] of this.spans) {
+        if (span.endTime === undefined && span.startTime < cutoff) {
+          this.spans.delete(spanId)
+        }
+      }
+    }
 
     if (this.exportQueue.length === 0) {
       // Also check if there are any finished spans that need to be exported
       // This ensures spans are exported even if they weren't properly moved to the queue
       const finishedSpans = Array.from(this.spans.values()).filter(span => span.endTime !== undefined)
       if (finishedSpans.length > 0) {
-        console.warn(`[RequestTracer] Found ${finishedSpans.length} finished spans to export`)
         // Move finished spans to export queue
         this.exportQueue.push(...finishedSpans)
         // Remove them from the spans map
@@ -323,7 +340,7 @@ export default class RequestTracer {
     }
   }
 
-  private async exportToJaeger(spans: TraceSpan[], exporter: any): Promise<void> {
+  private async exportToJaeger(spans: TraceSpan[], exporter: TraceExporterConfig): Promise<void> {
     if (!exporter.endpoint)
       return
 
@@ -366,7 +383,7 @@ export default class RequestTracer {
     })
   }
 
-  private async exportToZipkin(spans: TraceSpan[], exporter: any): Promise<void> {
+  private async exportToZipkin(spans: TraceSpan[], exporter: TraceExporterConfig): Promise<void> {
     if (!exporter.endpoint)
       return
 
@@ -590,7 +607,7 @@ export default class RequestTracer {
     return childSpanId
   }
 
-  addTag(spanId: string, key: string, value: any): void {
+  addTag(spanId: string, key: string, value: unknown): void {
     this.addSpanTag(spanId, key, value)
   }
 

package/src/middleware/response_cache.ts

@@ -9,7 +9,9 @@ export interface CacheEntry {
     status: number
     statusText: string
     headers: Record<string, string>
-    body: number[] // Store as number array for JSON serialization
+    // In-memory entries hold the raw bytes; entries round-tripped through
+    // the JSON file cache come back as a plain number array
+    body: Uint8Array | number[]
     contentType: string
   }
   createdAt: number
@@ -73,6 +75,7 @@ export class ResponseCache implements Middleware {
   }
 
   private cleanupInterval?: ReturnType<typeof setInterval>
+  private compiledInvalidationPatterns: RegExp[] = []
 
   constructor(options: ResponseCacheOptions = {}) {
     this.options = {
@@ -121,6 +124,20 @@ export class ResponseCache implements Middleware {
       },
     } as Required<ResponseCacheOptions>
 
+    // Compile invalidation patterns once — matching per request with
+    // `new RegExp(pattern)` recompiled the regex on every invalidation check
+    this.compiledInvalidationPatterns = (this.options.invalidation.patterns ?? [])
+      .map((pattern) => {
+        try {
+          return new RegExp(pattern)
+        }
+        catch {
+          console.warn(`[ResponseCache] Invalid invalidation pattern: ${pattern}`)
+          return null
+        }
+      })
+      .filter((re): re is RegExp => re !== null)
+
     this.initializeStorage()
     this.startCleanupInterval()
   }
@@ -142,6 +159,8 @@ export class ResponseCache implements Middleware {
     this.cleanupInterval = setInterval(() => {
       void this.cleanup()
     }, 60000) // Cleanup every minute
+    // Background housekeeping must not keep the process alive
+    this.cleanupInterval.unref?.()
   }
 
   public async cleanup(): Promise<void> {
@@ -370,7 +389,12 @@ export class ResponseCache implements Middleware {
 
     try {
       const filePath = join(this.options.storage.directory, `${key}.cache`)
-      const content = JSON.stringify(entry)
+      // Uint8Array doesn't JSON-serialize as an array — convert at the
+      // file boundary only (memory entries keep the compact byte view)
+      const serializable = entry.response.body instanceof Uint8Array
+        ? { ...entry, response: { ...entry.response, body: Array.from(entry.response.body) } }
+        : entry
+      const content = JSON.stringify(serializable)
       await Bun.write(filePath, content)
     }
     catch (error) {
@@ -574,9 +598,11 @@ export class ResponseCache implements Middleware {
   }
 
   private async createCacheEntry(req: EnhancedRequest, res: Response): Promise<{ entry: CacheEntry, response: Response }> {
-    // Clone the response to avoid consuming the original stream
-    const clonedRes = res.clone()
-    const body = await clonedRes.arrayBuffer()
+    // Read the body once and rebuild the outgoing response from the same
+    // bytes — cheaper than clone(), which tees the stream and buffers it
+    // twice. Bytes are kept as a Uint8Array (the old number[] conversion
+    // boxed every byte into a JS number array element).
+    const body = await res.arrayBuffer()
     const bodyBytes = new Uint8Array(body)
     const ttl = this.getTTL(req)
     const now = Date.now()
@@ -587,7 +613,7 @@ export class ResponseCache implements Middleware {
         status: res.status,
         statusText: res.statusText,
         headers: Object.fromEntries(res.headers.entries()),
-        body: Array.from(bodyBytes), // Convert to regular array for JSON serialization
+        body: bodyBytes,
         contentType: res.headers.get('Content-Type') || 'text/plain',
       },
       createdAt: now,
@@ -595,21 +621,31 @@ export class ResponseCache implements Middleware {
       size: bodyBytes.length,
     }
 
+    const outHeaders = new Headers(res.headers)
+
     // Generate ETag if enabled
     if (this.options.etag && this.options.etag.enabled) {
       entry.etag = this.generateETag(bodyBytes)
       if (entry.etag) {
         entry.response.headers.ETag = entry.etag
-        res.headers.set('ETag', entry.etag)
+        outHeaders.set('ETag', entry.etag)
       }
     }
 
     // Set Last-Modified
     entry.lastModified = new Date(now).toUTCString()
     entry.response.headers['Last-Modified'] = entry.lastModified
-    res.headers.set('Last-Modified', entry.lastModified)
+    outHeaders.set('Last-Modified', entry.lastModified)
 
-    return { entry, response: res }
+    const outBody = res.status === 204 || res.status === 304 ? null : bodyBytes
+    return {
+      entry,
+      response: new Response(outBody, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: outHeaders,
+      }),
+    }
   }
 
   private createResponseFromEntry(entry: CacheEntry): Response {
@@ -645,13 +681,12 @@ export class ResponseCache implements Middleware {
 
   async invalidateCache(req?: EnhancedRequest): Promise<void> {
     if (req) {
-      const patterns = this.options.invalidation.patterns
-      if (patterns && patterns.length > 0) {
+      if (this.compiledInvalidationPatterns.length > 0) {
         // Invalidate specific patterns
         const url = new URL(req.url)
 
-        for (const pattern of patterns) {
-          if (url.pathname.match(new RegExp(pattern))) {
+        for (const pattern of this.compiledInvalidationPatterns) {
+          if (pattern.test(url.pathname)) {
             await this.clearCache()
             return
           }

package/src/middleware/session.ts

@@ -1,4 +1,4 @@
-import type { EnhancedRequest, NextFunction } from '../types'
+import type { CookieOptions, EnhancedRequest, NextFunction } from '../types'
 import type { SessionStore, SessionData } from '../types/core'
 import { config } from '../config'
 import { MemorySessionStore } from '../session/memory-store'
@@ -49,7 +49,7 @@ export default class Session {
 
     // Create session manager and attach to request
     const manager = new SessionManager(sessionId, sessionData, this.store)
-    req.session = manager as any
+    req.session = manager
 
     // Continue to next middleware/handler
     const response = await next()
@@ -58,7 +58,7 @@ export default class Session {
     await manager.save()
 
     // Set session cookie on the response
-    const cookieOptions: any = {
+    const cookieOptions: CookieOptions = {
       maxAge: sessionConfig?.cookie?.maxAge || 86400000,
       path: sessionConfig?.cookie?.path || '/',
     }

package/src/observability/metrics.ts

@@ -520,7 +520,7 @@ export class MetricsRegistry {
     if (this.config.collectInterval && this.config.collectInterval > 0) {
       setInterval(() => {
         this.collectSystemMetrics()
-      }, this.config.collectInterval)
+      }, this.config.collectInterval).unref?.()
     }
   }
 

package/src/request/context.ts

@@ -17,12 +17,45 @@ interface RequestContextStore {
 
 const storage: AsyncLocalStorage<RequestContextStore> = new AsyncLocalStorage<RequestContextStore>()
 
+// AsyncLocalStorage.run costs roughly a microsecond per request — a large
+// share of total dispatch time — so it only runs once something actually
+// uses the context API. Until then a plain module variable tracks the
+// in-flight request: exact in the synchronous phase of a handler and for
+// non-overlapping requests, which covers the call that flips
+// `contextEnabled`. Every request that starts after the first use gets
+// full ALS isolation. Apps that need guaranteed isolation from the very
+// first request under concurrency can call `enableRequestContext()` at
+// startup.
+let contextEnabled = false
+let syncCurrent: EnhancedRequest | null = null
+
+/**
+ * Force AsyncLocalStorage-backed request context on for all subsequent
+ * requests. Calling `request()`/`getCurrentRequest()` enables it
+ * automatically — use this when the very first request must already be
+ * fully isolated under concurrent load.
+ */
+export function enableRequestContext(): void {
+  contextEnabled = true
+}
+
 /**
- * Run `fn` inside an AsyncLocalStorage scope where `request()` and
+ * Run `fn` inside a request-context scope where `request()` and
  * `getCurrentRequest()` resolve to `initial`. The Router calls this around
  * each request automatically.
  */
 export function runWithRequest<T>(initial: EnhancedRequest | Request, fn: () => T | Promise<T>): T | Promise<T> {
+  if (!contextEnabled) {
+    syncCurrent = initial as EnhancedRequest
+    const result = fn()
+    if (result instanceof Promise) {
+      return result.finally(() => {
+        syncCurrent = null
+      }) as Promise<T>
+    }
+    syncCurrent = null
+    return result
+  }
   return storage.run({ current: initial as EnhancedRequest }, fn)
 }
 
@@ -33,16 +66,30 @@ export function runWithRequest<T>(initial: EnhancedRequest | Request, fn: () =>
  */
 export function setCurrentRequest(req: EnhancedRequest): void {
   const store = storage.getStore()
-  if (store)
+  if (store) {
     store.current = req
+    return
+  }
+  // Pre-enablement fallback: only refresh it while a request is in flight
+  if (syncCurrent !== null) {
+    syncCurrent = req
+  }
 }
 
 /**
  * Returns the active request, or `undefined` when called outside a request
  * scope. Prefer `request()` when the request is required.
+ *
+ * First use switches the router to AsyncLocalStorage-backed context for
+ * all subsequent requests; this call itself resolves via a synchronous
+ * fallback (see `enableRequestContext` for eager opt-in).
  */
 export function getCurrentRequest(): EnhancedRequest | undefined {
-  return storage.getStore()?.current ?? undefined
+  if (!contextEnabled) {
+    contextEnabled = true
+    return syncCurrent ?? undefined
+  }
+  return storage.getStore()?.current ?? syncCurrent ?? undefined
 }
 
 /**

package/src/request/enhanced-request.ts

@@ -433,8 +433,21 @@ export function enhanceRequestWithMethods(request: EnhancedRequest): EnhancedReq
     _oldInput?: RequestInput
   }
 
-  // Get all input data
+  // Merged input (query + JSON body + form body + route params).
+  // Memoized: many of the helpers below call this several times per
+  // request, and the merge result only changes when a body is parsed
+  // later — so the cache keys off the body object identities.
+  let cachedInput: RequestInput | null = null
+  let cachedJsonBody: unknown
+  let cachedFormBody: unknown
+
   const getAllInput = (): RequestInput => {
+    if (cachedInput
+      && cachedJsonBody === request.jsonBody
+      && cachedFormBody === request.formBody) {
+      return cachedInput
+    }
+
     const input: RequestInput = {}
 
     // Query parameters
@@ -465,6 +478,9 @@ export function enhanceRequestWithMethods(request: EnhancedRequest): EnhancedReq
       }
     }
 
+    cachedInput = input
+    cachedJsonBody = request.jsonBody
+    cachedFormBody = request.formBody
     return input
   }
 
@@ -827,6 +843,9 @@ export function enhanceRequestWithMethods(request: EnhancedRequest): EnhancedReq
     else {
       (request as any).jsonBody = data
     }
+    // In-place mutation doesn't change jsonBody's identity, so drop the
+    // memoized merge explicitly
+    cachedInput = null
   }
 
   /**