@stacksjs/bun-router 0.0.5 → 0.0.6

package/src/router/middleware-groups.ts

@@ -0,0 +1,222 @@
+import type { MiddlewareHandler } from '../types'
+
+/**
+ * Middleware Group Registry
+ *
+ * Allows defining named groups of middleware that can be applied to routes.
+ * Similar to Laravel's middleware groups (web, api).
+ *
+ * @example
+ * // Define groups
+ * groups.define('web', ['session', 'csrf', 'cors'])
+ * groups.define('api', ['throttle:60,1', 'cors'])
+ *
+ * // Use on routes
+ * router.group({ middleware: 'web' }, () => { ... })
+ */
+export class MiddlewareGroupRegistry {
+  private groups = new Map<string, (string | MiddlewareHandler)[]>()
+  private globalMiddleware: (string | MiddlewareHandler)[] = []
+  private middlewarePriority: Map<string, number> = new Map()
+
+  /**
+   * Define a middleware group
+   */
+  define(name: string, middleware: (string | MiddlewareHandler)[]): this {
+    this.groups.set(name, [...middleware])
+    return this
+  }
+
+  /**
+   * Extend an existing group with additional middleware
+   */
+  extend(name: string, middleware: (string | MiddlewareHandler)[]): this {
+    const existing = this.groups.get(name) || []
+    this.groups.set(name, [...existing, ...middleware])
+    return this
+  }
+
+  /**
+   * Prepend middleware to an existing group
+   */
+  prepend(name: string, middleware: (string | MiddlewareHandler)[]): this {
+    const existing = this.groups.get(name) || []
+    this.groups.set(name, [...middleware, ...existing])
+    return this
+  }
+
+  /**
+   * Get middleware for a group
+   */
+  get(name: string): (string | MiddlewareHandler)[] {
+    return this.groups.get(name) || []
+  }
+
+  /**
+   * Check if a group exists
+   */
+  has(name: string): boolean {
+    return this.groups.has(name)
+  }
+
+  /**
+   * Remove a group
+   */
+  remove(name: string): this {
+    this.groups.delete(name)
+    return this
+  }
+
+  /**
+   * Resolve a middleware reference, expanding group names into their middleware
+   */
+  resolve(middleware: string | MiddlewareHandler): (string | MiddlewareHandler)[] {
+    if (typeof middleware === 'function') {
+      return [middleware]
+    }
+
+    // Check if it's a group name
+    if (this.groups.has(middleware)) {
+      return this.get(middleware)
+    }
+
+    // It's an individual middleware reference
+    return [middleware]
+  }
+
+  /**
+   * Resolve multiple middleware references, expanding groups
+   */
+  resolveAll(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[] {
+    const resolved: (string | MiddlewareHandler)[] = []
+
+    for (const mw of middleware) {
+      resolved.push(...this.resolve(mw))
+    }
+
+    return resolved
+  }
+
+  // ─── Global Middleware Stack ────────────────────────────────────
+
+  /**
+   * Add middleware to the global stack (runs on every request)
+   */
+  pushGlobal(...middleware: (string | MiddlewareHandler)[]): this {
+    this.globalMiddleware.push(...middleware)
+    return this
+  }
+
+  /**
+   * Prepend middleware to the global stack
+   */
+  prependGlobal(...middleware: (string | MiddlewareHandler)[]): this {
+    this.globalMiddleware.unshift(...middleware)
+    return this
+  }
+
+  /**
+   * Remove middleware from the global stack
+   */
+  removeGlobal(middleware: string): this {
+    this.globalMiddleware = this.globalMiddleware.filter(mw =>
+      typeof mw === 'string' ? mw !== middleware : true,
+    )
+    return this
+  }
+
+  /**
+   * Get the global middleware stack
+   */
+  getGlobal(): (string | MiddlewareHandler)[] {
+    return [...this.globalMiddleware]
+  }
+
+  // ─── Middleware Priority ───────────────────────────────────────
+
+  /**
+   * Set execution priority for a middleware (lower = runs first)
+   */
+  setPriority(name: string, priority: number): this {
+    this.middlewarePriority.set(name, priority)
+    return this
+  }
+
+  /**
+   * Sort middleware by priority
+   */
+  sortByPriority(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[] {
+    return [...middleware].sort((a, b) => {
+      const nameA = typeof a === 'string' ? a.split(':')[0] : ''
+      const nameB = typeof b === 'string' ? b.split(':')[0] : ''
+      const priorityA = this.middlewarePriority.get(nameA) ?? 100
+      const priorityB = this.middlewarePriority.get(nameB) ?? 100
+      return priorityA - priorityB
+    })
+  }
+
+  // ─── Route-Level Exclusions ────────────────────────────────────
+
+  /**
+   * Filter middleware by applying except/only rules.
+   *
+   * @param middleware - Full middleware list
+   * @param options - except or only filter
+   */
+  filter(
+    middleware: (string | MiddlewareHandler)[],
+    options: { except?: string[], only?: string[] },
+  ): (string | MiddlewareHandler)[] {
+    if (options.only && options.only.length > 0) {
+      return middleware.filter((mw) => {
+        if (typeof mw === 'string') {
+          const name = mw.split(':')[0]
+          return options.only!.includes(name)
+        }
+        return false
+      })
+    }
+
+    if (options.except && options.except.length > 0) {
+      return middleware.filter((mw) => {
+        if (typeof mw === 'string') {
+          const name = mw.split(':')[0]
+          return !options.except!.includes(name)
+        }
+        return true // Keep function middleware when using except
+      })
+    }
+
+    return middleware
+  }
+
+  /**
+   * Clear all groups and global middleware
+   */
+  flush(): void {
+    this.groups.clear()
+    this.globalMiddleware = []
+    this.middlewarePriority.clear()
+  }
+}
+
+/**
+ * Default middleware group registry instance
+ */
+export const middlewareGroups: MiddlewareGroupRegistry = new MiddlewareGroupRegistry()
+
+// Pre-define common groups
+middlewareGroups.define('web', ['session', 'csrf', 'cors'])
+middlewareGroups.define('api', ['throttle:60,1', 'cors'])
+
+// Set default priorities (lower = runs first)
+middlewareGroups.setPriority('session', 10)
+middlewareGroups.setPriority('cors', 20)
+middlewareGroups.setPriority('csrf', 30)
+middlewareGroups.setPriority('auth', 40)
+middlewareGroups.setPriority('throttle', 50)
+middlewareGroups.setPriority('role', 60)
+middlewareGroups.setPriority('permission', 60)
+middlewareGroups.setPriority('can', 70)
+middlewareGroups.setPriority('abilities', 70)
+middlewareGroups.setPriority('verified', 80)

package/src/router/middleware-integration.ts

@@ -0,0 +1,399 @@
+import type { EnhancedRequest, MiddlewareHandler, Route } from '../types'
+import type { Router } from './router'
+
+// Type placeholders for middleware pipeline
+export type SkipConditionFn = (_req: EnhancedRequest) => boolean
+export type SkipConditionsList = SkipConditionFn[]
+
+/**
+ * Skip condition helpers
+ */
+export const SkipConditions = {
+  skipForPaths: (paths: string[]): SkipConditionFn => (req: EnhancedRequest) => {
+    const url = new URL(req.url)
+    return paths.some(path => url.pathname.startsWith(path))
+  },
+  skipForMethods: (methods: string[]): SkipConditionFn => (req: EnhancedRequest) => {
+    return methods.includes(req.method)
+  },
+}
+
+/**
+ * Dependency helpers
+ */
+export const Dependencies = {
+  cache: (config: { type: string, ttl: number }): { type: string, config: { type: string, ttl: number } } => ({
+    type: 'cache',
+    config,
+  }),
+  logger: (level: string): { type: string, config: { level: string } } => ({
+    type: 'logger',
+    config: { level },
+  }),
+}
+
+class MiddlewarePipeline {
+  registerDependency(_key: string, _dependency: any): this { return this }
+  registerSkipConditions(_middleware: MiddlewareHandler, _conditions: SkipConditionsList): void {}
+  getStats(): any { return {} }
+  getCacheInfo(): any { return {} }
+  clearCache(): this { return this }
+  compilePipeline(_key: string, _middleware: MiddlewareHandler[], _options?: any): void {}
+  execute(_key: string, _req: EnhancedRequest, _handler: () => Promise<Response>): Promise<Response> { return _handler() }
+}
+
+/**
+ * Integration layer for middleware pipeline with the router
+ */
+export function registerMiddlewarePipeline(RouterClass: typeof Router): void {
+  // Add pipeline instance to router prototype
+  Object.defineProperty(RouterClass.prototype, '_middlewarePipeline', {
+    value: new MiddlewarePipeline(),
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  })
+
+  // Override the addRoute method to compile middleware pipelines
+  const originalAddRoute = RouterClass.prototype.addRoute
+  RouterClass.prototype.addRoute = function (route: Route) {
+    // Call original addRoute
+    const result = originalAddRoute.call(this, route)
+
+    // Compile middleware pipeline for this route
+    const routeKey = `${route.method}:${route.path}`
+    if (route.middleware && route.middleware.length > 0 && this._middlewarePipeline) {
+      this._middlewarePipeline.compileMiddleware(routeKey, route.middleware)
+    }
+
+    return result
+  }
+}
+
+/**
+ * Middleware factory for common use cases
+ */
+export class MiddlewareFactory {
+  private pipeline: MiddlewarePipeline
+
+  constructor(pipeline: MiddlewarePipeline) {
+    this.pipeline = pipeline
+  }
+
+  /**
+   * Create authentication middleware with conditional execution
+   */
+  createAuthMiddleware(options: {
+    skipPaths?: string[]
+    skipMethods?: string[]
+    requireRoles?: string[]
+    jwtSecret?: string
+  } = {}): MiddlewareHandler {
+    const middleware: MiddlewareHandler = async (req, next) => {
+      // Skip authentication for public paths
+      if (options.skipPaths) {
+        const url = new URL(req.url)
+        if (options.skipPaths.some(path => url.pathname.startsWith(path))) {
+          return next()
+        }
+      }
+
+      // Extract JWT token
+      const authHeader = req.headers.get('Authorization')
+      if (!authHeader?.startsWith('Bearer ')) {
+        return new Response('Unauthorized', { status: 401 })
+      }
+
+      const _token = authHeader.slice(7)
+
+      // In a real implementation, this would verify the JWT
+      // For demo purposes, we'll simulate user extraction
+      try {
+        // Simulate JWT verification
+        const user = {
+          id: 1,
+          name: 'John Doe',
+          roles: ['user'],
+          // In real implementation: jwt.verify(token, options.jwtSecret)
+        }
+
+        // Check required roles
+        if (options.requireRoles && options.requireRoles.length > 0) {
+          const hasRequiredRole = options.requireRoles.some(role =>
+            user.roles.includes(role),
+          )
+          if (!hasRequiredRole) {
+            return new Response('Forbidden', { status: 403 })
+          }
+        }
+
+        req.user = user
+        return next()
+      }
+      catch (error) {
+        console.error(error)
+        return new Response('Invalid token', { status: 401 })
+      }
+    }
+
+    Object.defineProperty(middleware, 'name', { value: 'auth' })
+
+    // Register skip conditions
+    const skipConditions = []
+    if (options.skipPaths) {
+      skipConditions.push(SkipConditions.skipForPaths(options.skipPaths))
+    }
+    if (options.skipMethods) {
+      skipConditions.push(SkipConditions.skipForMethods(options.skipMethods))
+    }
+
+    if (skipConditions.length > 0) {
+      this.pipeline.registerSkipConditions(middleware, skipConditions)
+    }
+
+    return middleware
+  }
+
+  /**
+   * Create rate limiting middleware with dependency injection
+   */
+  createRateLimitMiddleware(options: {
+    maxRequests: number
+    windowMs: number
+    skipPaths?: string[]
+  }): MiddlewareHandler {
+    // Register cache dependency for rate limiting
+    this.pipeline.registerDependency('cache', Dependencies.cache({
+      type: 'memory',
+      ttl: Math.ceil(options.windowMs / 1000),
+    }))
+
+    interface RateLimitEntry {
+      count: number
+      resetTime: number
+    }
+
+    const middleware: MiddlewareHandler = async (req, next) => {
+      const cache = req.context?.cache
+      if (!cache) {
+        // Fallback if cache not available
+        return next()
+      }
+
+      const clientId = req.ip || req.headers.get('x-forwarded-for') || 'unknown'
+      const key = `rate_limit:${clientId}`
+
+      const current: RateLimitEntry = cache.get<RateLimitEntry>(key) || { count: 0, resetTime: Date.now() + options.windowMs }
+
+      if (Date.now() > current.resetTime) {
+        current.count = 0
+        current.resetTime = Date.now() + options.windowMs
+      }
+
+      if (current.count >= options.maxRequests) {
+        return new Response('Too Many Requests', {
+          status: 429,
+          headers: {
+            'Retry-After': Math.ceil((current.resetTime - Date.now()) / 1000).toString(),
+          },
+        })
+      }
+
+      current.count++
+      cache.set(key, current)
+
+      return next()
+    }
+
+    Object.defineProperty(middleware, 'name', { value: 'rateLimit' })
+
+    // Register skip conditions
+    if (options.skipPaths) {
+      this.pipeline.registerSkipConditions(middleware, [
+        SkipConditions.skipForPaths(options.skipPaths),
+      ])
+    }
+
+    return middleware
+  }
+
+  /**
+   * Create logging middleware with dependency injection
+   */
+  createLoggingMiddleware(options: {
+    level?: string
+    skipPaths?: string[]
+    includeBody?: boolean
+  } = {}): MiddlewareHandler {
+    // Register logger dependency
+    this.pipeline.registerDependency('logger', Dependencies.logger(options.level || 'info'))
+
+    const middleware: MiddlewareHandler = async (req, next) => {
+      const logger = req.context?.logger
+      const startTime = Date.now()
+
+      // Generate request ID
+      const requestId = Math.random().toString(36).substr(2, 9)
+      req.requestId = requestId
+
+      if (logger) {
+        logger.log(`[${requestId}] ${req.method} ${req.url} - Started`)
+      }
+
+      try {
+        const response = await next()
+        const duration = Date.now() - startTime
+
+        if (logger && response) {
+          logger.log(`[${requestId}] ${req.method} ${req.url} - ${response.status} (${duration}ms)`)
+        }
+
+        return response
+      }
+      catch (error) {
+        const duration = Date.now() - startTime
+        if (logger) {
+          logger.error(`[${requestId}] ${req.method} ${req.url} - Error: ${error} (${duration}ms)`)
+        }
+        throw error
+      }
+    }
+
+    Object.defineProperty(middleware, 'name', { value: 'logging' })
+
+    // Register skip conditions
+    if (options.skipPaths) {
+      this.pipeline.registerSkipConditions(middleware, [
+        SkipConditions.skipForPaths(options.skipPaths),
+      ])
+    }
+
+    return middleware
+  }
+
+  /**
+   * Create CORS middleware with conditional execution
+   */
+  createCorsMiddleware(options: {
+    origin?: string | string[]
+    methods?: string[]
+    allowedHeaders?: string[]
+    credentials?: boolean
+  } = {}): MiddlewareHandler {
+    const middleware: MiddlewareHandler = async (req, next) => {
+      const origin = req.headers.get('Origin')
+      const method = req.method
+
+      // Handle preflight requests
+      if (method === 'OPTIONS') {
+        const headers = new Headers()
+
+        if (options.origin) {
+          if (Array.isArray(options.origin)) {
+            if (origin && options.origin.includes(origin)) {
+              headers.set('Access-Control-Allow-Origin', origin)
+            }
+          }
+          else if (options.origin === '*' || options.origin === origin) {
+            headers.set('Access-Control-Allow-Origin', options.origin)
+          }
+        }
+
+        if (options.methods) {
+          headers.set('Access-Control-Allow-Methods', options.methods.join(', '))
+        }
+
+        if (options.allowedHeaders) {
+          headers.set('Access-Control-Allow-Headers', options.allowedHeaders.join(', '))
+        }
+
+        if (options.credentials) {
+          headers.set('Access-Control-Allow-Credentials', 'true')
+        }
+
+        return new Response(null, { status: 204, headers })
+      }
+
+      // Handle actual requests
+      const response = await next()
+      if (response && options.origin && origin) {
+        const newHeaders = new Headers(response.headers)
+
+        if (Array.isArray(options.origin)) {
+          if (options.origin.includes(origin)) {
+            newHeaders.set('Access-Control-Allow-Origin', origin)
+          }
+        }
+        else if (options.origin === '*' || options.origin === origin) {
+          newHeaders.set('Access-Control-Allow-Origin', options.origin)
+        }
+
+        if (options.credentials) {
+          newHeaders.set('Access-Control-Allow-Credentials', 'true')
+        }
+
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: newHeaders,
+        })
+      }
+
+      return response
+    }
+
+    Object.defineProperty(middleware, 'name', { value: 'cors' })
+    return middleware
+  }
+}
+
+/**
+ * Helper function to setup common middleware stack
+ */
+export function setupMiddlewareStack(router: any, options: {
+  auth?: {
+    jwtSecret: string
+    skipPaths?: string[]
+    requireRoles?: string[]
+  }
+  rateLimit?: {
+    maxRequests: number
+    windowMs: number
+    skipPaths?: string[]
+  }
+  cors?: {
+    origin?: string | string[]
+    methods?: string[]
+    allowedHeaders?: string[]
+    credentials?: boolean
+  }
+  logging?: {
+    level?: string
+    skipPaths?: string[]
+  }
+} = {}): MiddlewareHandler[] {
+  const factory = new MiddlewareFactory(router._middlewarePipeline)
+  const middleware: MiddlewareHandler[] = []
+
+  // Add CORS middleware first
+  if (options.cors) {
+    middleware.push(factory.createCorsMiddleware(options.cors))
+  }
+
+  // Add logging middleware
+  if (options.logging !== undefined) {
+    middleware.push(factory.createLoggingMiddleware(options.logging))
+  }
+
+  // Add rate limiting middleware
+  if (options.rateLimit) {
+    middleware.push(factory.createRateLimitMiddleware(options.rateLimit))
+  }
+
+  // Add authentication middleware
+  if (options.auth) {
+    middleware.push(factory.createAuthMiddleware(options.auth))
+  }
+
+  return middleware
+}