@onebun/core 0.2.6 → 0.2.8

package/src/application/application.ts

@@ -1,4 +1,10 @@
-import { Effect, type Layer } from 'effect';
+import path from 'node:path';
+
+import {
+  type Context,
+  Effect,
+  type Layer,
+} from 'effect';
 
 import type { Controller } from '../module/controller';
 import type { WsClientData } from '../websocket/ws.types';
@@ -17,21 +23,24 @@ import {
   type SyncLogger,
 } from '@onebun/logger';
 import {
-  type ApiResponse,
   createErrorResponse,
   createSuccessResponse,
   HttpStatusCode,
-  OneBunBaseError,
 } from '@onebun/requests';
 import { makeTraceService, TraceService } from '@onebun/trace';
 
 import {
+  getControllerFilters,
+  getControllerGuards,
   getControllerMetadata,
   getControllerMiddleware,
   getSseMetadata,
   type SseDecoratorOptions,
 } from '../decorators/decorators';
+import { defaultExceptionFilter, type ExceptionFilter } from '../exception-filters/exception-filters';
+import { HttpException } from '../exception-filters/http-exception';
 import { OneBunFile, validateFile } from '../file/onebun-file';
+import { executeHttpGuards, HttpExecutionContextImpl } from '../http-guards/http-guards';
 import {
   NotInitializedConfig,
   type IConfig,
@@ -45,11 +54,20 @@ import {
   DEFAULT_SSE_TIMEOUT,
 } from '../module/controller';
 import { OneBunModule } from '../module/module';
-import { QueueService, type QueueAdapter } from '../queue';
+import {
+  QueueService,
+  QueueServiceProxy,
+  QueueServiceTag,
+  type QueueAdapter,
+  type QueueConfig,
+} from '../queue';
 import { InMemoryQueueAdapter } from '../queue/adapters/memory.adapter';
 import { RedisQueueAdapter } from '../queue/adapters/redis.adapter';
 import { hasQueueDecorators } from '../queue/decorators';
 import { SharedRedisProvider } from '../redis/shared-redis';
+import { CorsMiddleware } from '../security/cors-middleware';
+import { RateLimitMiddleware } from '../security/rate-limit-middleware';
+import { SecurityHeadersMiddleware } from '../security/security-headers-middleware';
 import {
   type ApplicationOptions,
   type HttpMethod,
@@ -88,6 +106,17 @@ try {
   // Docs module not available - this is optional
 }
 
+// Optional CacheService for static file existence caching
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let cacheServiceClass: new (...args: unknown[]) => any = null as any;
+try {
+  // eslint-disable-next-line import/no-extraneous-dependencies
+  const cacheModule = require('@onebun/cache');
+  cacheServiceClass = cacheModule.CacheService;
+} catch {
+  // @onebun/cache not available - use in-memory Map fallback
+}
+
 // Import tracing modules directly
 
 // Global trace context for current request
@@ -113,12 +142,12 @@ function clearGlobalTraceContext(): void {
  * normalizePath('/')       // => '/'
  * normalizePath('/api/v1/') // => '/api/v1'
  */
-function normalizePath(path: string): string {
-  if (path === '/' || path.length <= 1) {
-    return path;
+function normalizePath(pathStr: string): string {
+  if (pathStr === '/' || pathStr.length <= 1) {
+    return pathStr;
   }
 
-  return path.endsWith('/') ? path.slice(0, -1) : path;
+  return pathStr.endsWith('/') ? pathStr.slice(0, -1) : pathStr;
 }
 
 /**
@@ -191,6 +220,29 @@ function resolveHost(explicitHost: string | undefined): string {
   return '0.0.0.0';
 }
 
+/** Default TTL for static file existence cache (ms) when not specified */
+const DEFAULT_STATIC_FILE_EXISTENCE_CACHE_TTL_MS = 60_000;
+
+/** Cache key prefix for static file existence in CacheService */
+const STATIC_EXISTS_CACHE_PREFIX = 'onebun:static:exists:';
+
+/**
+ * Resolve a relative path under a root directory and ensure the result stays inside the root (path traversal protection).
+ * @param rootDir - Absolute path to the static root directory
+ * @param relativePath - URL path segment (e.g. from request path after prefix); must not contain '..' that escapes root
+ * @returns Absolute path if under root, otherwise null
+ */
+function resolvePathUnderRoot(rootDir: string, relativePath: string): string | null {
+  const normalized = path.join(rootDir, relativePath.startsWith('/') ? relativePath.slice(1) : relativePath);
+  const resolved = path.resolve(normalized);
+  const rootResolved = path.resolve(rootDir);
+  if (resolved === rootResolved || resolved.startsWith(rootResolved + path.sep)) {
+    return resolved;
+  }
+
+  return null;
+}
+
 /**
  * OneBun Application
  */
@@ -210,6 +262,7 @@ export class OneBunApplication {
   private wsHandler: WsHandler | null = null;
   private queueService: QueueService | null = null;
   private queueAdapter: QueueAdapter | null = null;
+  private queueServiceProxy: QueueServiceProxy | null = null;
   // Docs (OpenAPI/Swagger) - generated on start()
   private openApiSpec: Record<string, unknown> | null = null;
   private swaggerHtml: string | null = null;
@@ -364,11 +417,11 @@ export class OneBunApplication {
    * const port = app.getConfigValue('server.port'); // number
    * const host = app.getConfigValue('server.host'); // string
    */
-  getConfigValue<P extends DeepPaths<OneBunAppConfig>>(path: P): DeepValue<OneBunAppConfig, P>;
+  getConfigValue<P extends DeepPaths<OneBunAppConfig>>(pathKey: P): DeepValue<OneBunAppConfig, P>;
   /** Fallback for dynamic paths */
-  getConfigValue<T = unknown>(path: string): T;
-  getConfigValue(path: string): unknown {
-    return this.getConfig().get(path);
+  getConfigValue<T = unknown>(pathKey: string): T;
+  getConfigValue(pathKey: string): unknown {
+    return this.getConfig().get(pathKey);
   }
 
   /**
@@ -441,6 +494,23 @@ export class OneBunApplication {
       // so services can safely use this.config.get() in their constructors
       this.rootModule = OneBunModule.create(this.moduleClass, this.loggerLayer, this.config);
 
+      // Register QueueService proxy in DI so controllers/providers/middleware can inject QueueService.
+      // After initializeQueue(), setDelegate(real) is called when queue is enabled.
+      this.queueServiceProxy = new QueueServiceProxy();
+      if (this.ensureModule().registerService) {
+        this.ensureModule().registerService!(
+          QueueServiceTag as Context.Tag<unknown, QueueService>,
+          this.queueServiceProxy as unknown as QueueService,
+        );
+      }
+
+      // Register test provider overrides (must happen before setup() so controllers receive mocks)
+      if (this.options._testProviders) {
+        for (const { tag, value } of this.options._testProviders) {
+          this.ensureModule().registerService?.(tag, value);
+        }
+      }
+
       // Start metrics collection if enabled
       if (this.metricsService && this.metricsService.startSystemMetricsCollection) {
         this.metricsService.startSystemMetricsCollection();
@@ -595,41 +665,65 @@ export class OneBunApplication {
           try {
             let response: Response;
 
-            // Execute middleware chain if any, then handler
-            if (routeMeta.middleware && routeMeta.middleware.length > 0) {
-              const next = async (index: number): Promise<Response> => {
-                if (index >= routeMeta.middleware!.length) {
-                  return await executeHandler(
+            // Run guards then handler — shared by middleware chain and direct path
+            const runGuardedHandler = async (): Promise<Response> => {
+              if (routeMeta.guards && routeMeta.guards.length > 0) {
+                const guardCtx = new HttpExecutionContextImpl(
+                  req,
+                  routeMeta.handler,
+                  controller.constructor.name,
+                );
+                const allowed = await executeHttpGuards(routeMeta.guards, guardCtx);
+
+                if (!allowed) {
+                  return new Response(
+                    JSON.stringify(
+                      createErrorResponse(
+                        'Forbidden',
+                        HttpStatusCode.FORBIDDEN,
+                        'Forbidden',
+                      ),
+                    ),
                     {
-                      handler: boundHandler,
-                      handlerName: routeMeta.handler,
-                      controller,
-                      params: routeMeta.params,
-                      responseSchemas: routeMeta.responseSchemas,
+                      status: HttpStatusCode.OK,
+                      headers: {
+                        // eslint-disable-next-line @typescript-eslint/naming-convention
+                        'Content-Type': 'application/json',
+                      },
                     },
-                    req,
-                    queryParams,
                   );
                 }
+              }
 
-                const middleware = routeMeta.middleware![index];
-
-                return await middleware(req, () => next(index + 1));
-              };
-
-              response = await next(0);
-            } else {
-              response = await executeHandler(
+              return await executeHandler(
                 {
                   handler: boundHandler,
                   handlerName: routeMeta.handler,
                   controller,
                   params: routeMeta.params,
                   responseSchemas: routeMeta.responseSchemas,
+                  filters: routeMeta.filters,
                 },
                 req,
                 queryParams,
               );
+            };
+
+            // Execute middleware chain if any, then guarded handler
+            if (routeMeta.middleware && routeMeta.middleware.length > 0) {
+              const next = async (index: number): Promise<Response> => {
+                if (index >= routeMeta.middleware!.length) {
+                  return await runGuardedHandler();
+                }
+
+                const middleware = routeMeta.middleware![index];
+
+                return await middleware(req, () => next(index + 1));
+              };
+
+              response = await next(0);
+            } else {
+              response = await runGuardedHandler();
             }
 
             const duration = Date.now() - startTime;
@@ -725,10 +819,31 @@ export class OneBunApplication {
         };
       }
 
+      // Build auto-configured security middleware from shorthand options.
+      // These are prepended/appended in a fixed order: CORS → RateLimit → [user] → Security.
+      const autoPrefix: Function[] = [];
+      const autoSuffix: Function[] = [];
+
+      if (this.options.cors) {
+        const corsOpts = this.options.cors === true ? {} : this.options.cors;
+        autoPrefix.push(CorsMiddleware.configure(corsOpts));
+      }
+
+      if (this.options.rateLimit) {
+        const rlOpts = this.options.rateLimit === true ? {} : this.options.rateLimit;
+        autoPrefix.push(RateLimitMiddleware.configure(rlOpts));
+      }
+
+      if (this.options.security) {
+        const secOpts = this.options.security === true ? {} : this.options.security;
+        autoSuffix.push(SecurityHeadersMiddleware.configure(secOpts));
+      }
+
       // Application-wide middleware — resolve class constructors via root module DI
-      const globalMiddlewareClasses = (this.options.middleware as Function[] | undefined) ?? [];
-      const globalMiddleware: Function[] = globalMiddlewareClasses.length > 0
-        ? (this.ensureModule().resolveMiddleware?.(globalMiddlewareClasses) ?? [])
+      const userMiddlewareClasses = (this.options.middleware as Function[] | undefined) ?? [];
+      const allGlobalClasses = [...autoPrefix, ...userMiddlewareClasses, ...autoSuffix];
+      const globalMiddleware: Function[] = allGlobalClasses.length > 0
+        ? (this.ensureModule().resolveMiddleware?.(allGlobalClasses) ?? [])
         : [];
 
       // Add routes from controllers
@@ -790,9 +905,23 @@ export class OneBunApplication {
             ...ctrlMiddleware,
             ...routeMiddleware,
           ];
+
+          // Merge guards: controller-level first, then route-level
+          const ctrlGuards = getControllerGuards(controllerClass);
+          const routeGuards = route.guards ?? [];
+          const mergedGuards = [...ctrlGuards, ...routeGuards];
+
+          // Merge exception filters: global → controller → route (route has highest priority)
+          const globalFilters = (this.options.filters as ExceptionFilter[] | undefined) ?? [];
+          const ctrlFilters = getControllerFilters(controllerClass);
+          const routeFilters = route.filters ?? [];
+          const mergedFilters = [...globalFilters, ...ctrlFilters, ...routeFilters];
+
           const routeWithMergedMiddleware: RouteMetadata = {
             ...route,
             middleware: mergedMiddleware.length > 0 ? mergedMiddleware : undefined,
+            guards: mergedGuards.length > 0 ? mergedGuards : undefined,
+            filters: mergedFilters.length > 0 ? mergedFilters : undefined,
           };
 
           // Create wrapped handler with full OneBun lifecycle (tracing, metrics, middleware)
@@ -901,6 +1030,69 @@ export class OneBunApplication {
          
         drain() { /* no-op */ },
       };
+
+      // Static file serving: resolve root and setup existence cache (CacheService or in-memory Map)
+      const staticOpts = this.options.static;
+      let staticRootResolved: string | null = null;
+      let staticPathPrefix: string | undefined;
+      let staticFallbackFile: string | undefined;
+      let staticCacheTtlMs = 0;
+      // Cache interface: get(key) => value | undefined, set(key, value, ttlMs)
+      type StaticExistsCache = {
+        get(key: string): Promise<boolean | undefined>;
+        set(key: string, value: boolean, ttlMs: number): Promise<void>;
+      };
+      let staticExistsCache: StaticExistsCache | null = null;
+
+      if (staticOpts?.root) {
+        staticRootResolved = path.resolve(staticOpts.root);
+        staticPathPrefix = staticOpts.pathPrefix;
+        staticFallbackFile = staticOpts.fallbackFile;
+        staticCacheTtlMs = staticOpts.fileExistenceCacheTtlMs ?? DEFAULT_STATIC_FILE_EXISTENCE_CACHE_TTL_MS;
+
+        if (staticCacheTtlMs > 0) {
+          if (cacheServiceClass) {
+            try {
+              const cacheService = this.ensureModule().getServiceByClass?.(cacheServiceClass);
+              if (cacheService && typeof cacheService.get === 'function' && typeof cacheService.set === 'function') {
+                staticExistsCache = {
+                  get: (key: string) => cacheService.get(STATIC_EXISTS_CACHE_PREFIX + key),
+                  set: (key: string, value: boolean, ttlMs: number) =>
+                    cacheService.set(STATIC_EXISTS_CACHE_PREFIX + key, value, { ttl: ttlMs }),
+                };
+                this.logger.debug('Static file existence cache using CacheService');
+              }
+            } catch {
+              // CacheService not in module, use fallback
+            }
+          }
+          if (!staticExistsCache) {
+            const map = new Map<string, { exists: boolean; expiresAt: number }>();
+            staticExistsCache = {
+              async get(key: string): Promise<boolean | undefined> {
+                const entry = map.get(key);
+                if (!entry) {
+                  return undefined;
+                }
+                if (staticCacheTtlMs > 0 && Date.now() > entry.expiresAt) {
+                  map.delete(key);
+
+                  return undefined;
+                }
+
+                return entry.exists;
+              },
+              async set(key: string, value: boolean, ttlMs: number): Promise<void> {
+                map.set(key, {
+                  exists: value,
+                  expiresAt: ttlMs > 0 ? Date.now() + ttlMs : Number.MAX_SAFE_INTEGER,
+                });
+              },
+            };
+            this.logger.debug('Static file existence cache using in-memory Map');
+          }
+        }
+      }
       
       this.server = Bun.serve<WsClientData>({
         port: this.options.port,
@@ -920,8 +1112,8 @@ export class OneBunApplication {
             const socketioPath = app.options.websocket?.socketio?.path ?? '/socket.io';
 
             const url = new URL(req.url);
-            const path = normalizePath(url.pathname);
-            const isSocketIoPath = socketioEnabled && path.startsWith(socketioPath);
+            const requestPath = normalizePath(url.pathname);
+            const isSocketIoPath = socketioEnabled && requestPath.startsWith(socketioPath);
             if (upgradeHeader === 'websocket' || isSocketIoPath) {
               const response = await app.wsHandler.handleUpgrade(req, server);
               if (response === undefined) {
@@ -932,6 +1124,60 @@ export class OneBunApplication {
             }
           }
 
+          // Static file serving (GET/HEAD only)
+          if (staticRootResolved && (req.method === 'GET' || req.method === 'HEAD')) {
+            const requestPath = normalizePath(new URL(req.url).pathname);
+            const prefix = staticPathPrefix ?? '/';
+            const hasPrefix = prefix !== '' && prefix !== '/';
+            if (hasPrefix && !requestPath.startsWith(prefix)) {
+              return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+            }
+            const relativePath = hasPrefix ? requestPath.slice(prefix.length) || '/' : requestPath;
+            const resolvedPath = resolvePathUnderRoot(staticRootResolved, relativePath);
+            if (resolvedPath === null) {
+              return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+            }
+
+            const cache = staticCacheTtlMs > 0 ? staticExistsCache : null;
+            const cacheKey = resolvedPath;
+            if (cache) {
+              const cached = await cache.get(cacheKey);
+              if (cached === true) {
+                return new Response(Bun.file(resolvedPath));
+              }
+              if (cached === false) {
+                if (staticFallbackFile) {
+                  const fallbackResolved = resolvePathUnderRoot(staticRootResolved, staticFallbackFile);
+                  if (fallbackResolved !== null) {
+                    return new Response(Bun.file(fallbackResolved));
+                  }
+                }
+
+                return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+              }
+            }
+
+            const file = Bun.file(resolvedPath);
+            const exists = await file.exists();
+            if (cache && staticCacheTtlMs > 0) {
+              await cache.set(cacheKey, exists, staticCacheTtlMs);
+            }
+            if (exists) {
+              return new Response(file);
+            }
+            if (staticFallbackFile) {
+              const fallbackResolved = resolvePathUnderRoot(staticRootResolved, staticFallbackFile);
+              if (fallbackResolved !== null) {
+                const fallbackFile = Bun.file(fallbackResolved);
+                if (await fallbackFile.exists()) {
+                  return new Response(fallbackFile);
+                }
+              }
+            }
+
+            return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
+          }
+
           // 404 for everything not matched by routes
           return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
         },
@@ -953,6 +1199,9 @@ export class OneBunApplication {
       }
 
       this.logger.info(`Server started on http://${this.options.host}:${this.options.port}`);
+      if (staticRootResolved) {
+        this.logger.info(`Static files served from ${staticRootResolved}`);
+      }
       if (this.metricsService) {
         this.logger.info(
           `Metrics available at http://${this.options.host}:${this.options.port}${metricsPath}`,
@@ -1024,6 +1273,7 @@ export class OneBunApplication {
         controller: Controller;
         params?: ParamMetadata[];
         responseSchemas?: RouteMetadata['responseSchemas'];
+        filters?: ExceptionFilter[];
       },
       req: OneBunRequest,
       queryParams: Record<string, string | string[]>,
@@ -1046,224 +1296,226 @@ export class OneBunApplication {
         return result;
       }
 
+      try {
       // Prepare arguments array based on parameter metadata
-      const args: unknown[] = [];
+        const args: unknown[] = [];
 
-      // Sort params by index to ensure correct order
-      const sortedParams = [...(route.params || [])].sort((a, b) => a.index - b.index);
+        // Sort params by index to ensure correct order
+        const sortedParams = [...(route.params || [])].sort((a, b) => a.index - b.index);
 
-      // Pre-parse body for file upload params (FormData or JSON, cached for all params)
-      const needsFileData = sortedParams.some(
-        (p) =>
-          p.type === ParamType.FILE ||
+        // Pre-parse body for file upload params (FormData or JSON, cached for all params)
+        const needsFileData = sortedParams.some(
+          (p) =>
+            p.type === ParamType.FILE ||
           p.type === ParamType.FILES ||
           p.type === ParamType.FORM_FIELD,
-      );
+        );
 
-      // Validate that @Body and file decorators are not used on the same method
-      if (needsFileData) {
-        const hasBody = sortedParams.some((p) => p.type === ParamType.BODY);
-        if (hasBody) {
-          throw new Error(
-            'Cannot use @Body() together with @UploadedFile/@UploadedFiles/@FormField on the same method. ' +
+        // Validate that @Body and file decorators are not used on the same method
+        if (needsFileData) {
+          const hasBody = sortedParams.some((p) => p.type === ParamType.BODY);
+          if (hasBody) {
+            throw new HttpException(
+              HttpStatusCode.BAD_REQUEST,
+              'Cannot use @Body() together with @UploadedFile/@UploadedFiles/@FormField on the same method. ' +
             'Both consume the request body. Use file decorators for multipart/base64 uploads.',
-          );
+            );
+          }
         }
-      }
 
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let formData: any = null;
-      let jsonBody: Record<string, unknown> | null = null;
-      let isMultipart = false;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let formData: any = null;
+        let jsonBody: Record<string, unknown> | null = null;
+        let isMultipart = false;
 
-      if (needsFileData) {
-        const contentType = req.headers.get('content-type') || '';
+        if (needsFileData) {
+          const contentType = req.headers.get('content-type') || '';
 
-        if (contentType.includes('multipart/form-data')) {
-          isMultipart = true;
-          try {
-            formData = await req.formData();
-          } catch {
-            formData = null;
-          }
-        } else if (contentType.includes('application/json')) {
-          try {
-            const parsed = await req.json();
-            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-              jsonBody = parsed as Record<string, unknown>;
+          if (contentType.includes('multipart/form-data')) {
+            isMultipart = true;
+            try {
+              formData = await req.formData();
+            } catch {
+              formData = null;
+            }
+          } else if (contentType.includes('application/json')) {
+            try {
+              const parsed = await req.json();
+              if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                jsonBody = parsed as Record<string, unknown>;
+              }
+            } catch {
+              jsonBody = null;
             }
-          } catch {
-            jsonBody = null;
           }
         }
-      }
 
-      for (const param of sortedParams) {
-        switch (param.type) {
-          case ParamType.PATH:
+        for (const param of sortedParams) {
+          switch (param.type) {
+            case ParamType.PATH:
             // Use req.params from BunRequest (natively populated by Bun routes API)
-            args[param.index] = param.name
-              ? (req.params as Record<string, string>)[param.name]
-              : undefined;
-            break;
+              args[param.index] = param.name
+                ? (req.params as Record<string, string>)[param.name]
+                : undefined;
+              break;
 
-          case ParamType.QUERY:
-            args[param.index] = param.name ? queryParams[param.name] : undefined;
-            break;
+            case ParamType.QUERY:
+              args[param.index] = param.name ? queryParams[param.name] : undefined;
+              break;
 
-          case ParamType.BODY:
-            try {
-              args[param.index] = await req.json();
-            } catch {
-              args[param.index] = undefined;
-            }
-            break;
+            case ParamType.BODY:
+              try {
+                args[param.index] = await req.json();
+              } catch {
+                args[param.index] = undefined;
+              }
+              break;
 
-          case ParamType.HEADER:
-            args[param.index] = param.name ? req.headers.get(param.name) : undefined;
-            break;
+            case ParamType.HEADER:
+              args[param.index] = param.name ? req.headers.get(param.name) : undefined;
+              break;
 
-          case ParamType.COOKIE:
-            args[param.index] = param.name ? req.cookies.get(param.name) ?? undefined : undefined;
-            break;
+            case ParamType.COOKIE:
+              args[param.index] = param.name ? req.cookies.get(param.name) ?? undefined : undefined;
+              break;
 
-          case ParamType.REQUEST:
-            args[param.index] = req;
-            break;
+            case ParamType.REQUEST:
+              args[param.index] = req;
+              break;
 
-          case ParamType.RESPONSE:
+            case ParamType.RESPONSE:
             // For now, we don't support direct response manipulation
-            args[param.index] = undefined;
-            break;
+              args[param.index] = undefined;
+              break;
 
-          case ParamType.FILE: {
-            let file: OneBunFile | undefined;
+            case ParamType.FILE: {
+              let file: OneBunFile | undefined;
 
-            if (isMultipart && formData && param.name) {
-              const entry = formData.get(param.name);
-              if (entry instanceof File) {
-                file = new OneBunFile(entry);
+              if (isMultipart && formData && param.name) {
+                const entry = formData.get(param.name);
+                if (entry instanceof File) {
+                  file = new OneBunFile(entry);
+                }
+              } else if (jsonBody && param.name) {
+                file = extractFileFromJson(jsonBody, param.name);
               }
-            } else if (jsonBody && param.name) {
-              file = extractFileFromJson(jsonBody, param.name);
-            }
 
-            if (file && param.fileOptions) {
-              validateFile(file, param.fileOptions, param.name);
-            }
+              if (file && param.fileOptions) {
+                validateFile(file, param.fileOptions, param.name);
+              }
 
-            args[param.index] = file;
-            break;
-          }
+              args[param.index] = file;
+              break;
+            }
 
-          case ParamType.FILES: {
-            let files: OneBunFile[] = [];
+            case ParamType.FILES: {
+              let files: OneBunFile[] = [];
 
-            if (isMultipart && formData) {
-              if (param.name) {
+              if (isMultipart && formData) {
+                if (param.name) {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const entries: any[] = formData.getAll(param.name);
-                files = entries
-                  .filter((entry: unknown): entry is File => entry instanceof File)
-                  .map((f: File) => new OneBunFile(f));
-              } else {
+                  const entries: any[] = formData.getAll(param.name);
+                  files = entries
+                    .filter((entry: unknown): entry is File => entry instanceof File)
+                    .map((f: File) => new OneBunFile(f));
+                } else {
                 // Get all files from all fields
-                for (const [, value] of formData.entries()) {
-                  if (value instanceof File) {
-                    files.push(new OneBunFile(value));
+                  for (const [, value] of formData.entries()) {
+                    if (value instanceof File) {
+                      files.push(new OneBunFile(value));
+                    }
                   }
                 }
-              }
-            } else if (jsonBody) {
-              if (param.name) {
-                const fieldValue = jsonBody[param.name];
-                if (Array.isArray(fieldValue)) {
-                  files = fieldValue
-                    .map((item) => extractFileFromJsonValue(item))
-                    .filter((f): f is OneBunFile => f !== undefined);
-                }
-              } else {
+              } else if (jsonBody) {
+                if (param.name) {
+                  const fieldValue = jsonBody[param.name];
+                  if (Array.isArray(fieldValue)) {
+                    files = fieldValue
+                      .map((item) => extractFileFromJsonValue(item))
+                      .filter((f): f is OneBunFile => f !== undefined);
+                  }
+                } else {
                 // Extract all file-like values from JSON
-                for (const [, value] of Object.entries(jsonBody)) {
-                  const file = extractFileFromJsonValue(value);
-                  if (file) {
-                    files.push(file);
+                  for (const [, value] of Object.entries(jsonBody)) {
+                    const file = extractFileFromJsonValue(value);
+                    if (file) {
+                      files.push(file);
+                    }
                   }
                 }
               }
-            }
 
-            // Validate maxCount
-            if (param.fileOptions?.maxCount !== undefined && files.length > param.fileOptions.maxCount) {
-              throw new Error(
-                `Too many files for "${param.name || 'upload'}". Got ${files.length}, max is ${param.fileOptions.maxCount}`,
-              );
-            }
+              // Validate maxCount
+              if (param.fileOptions?.maxCount !== undefined && files.length > param.fileOptions.maxCount) {
+                throw new HttpException(
+                  HttpStatusCode.BAD_REQUEST,
+                  `Too many files for "${param.name || 'upload'}". Got ${files.length}, max is ${param.fileOptions.maxCount}`,
+                );
+              }
 
-            // Validate each file
-            if (param.fileOptions) {
-              for (const file of files) {
-                validateFile(file, param.fileOptions, param.name);
+              // Validate each file
+              if (param.fileOptions) {
+                for (const file of files) {
+                  validateFile(file, param.fileOptions, param.name);
+                }
               }
-            }
 
-            args[param.index] = files;
-            break;
-          }
+              args[param.index] = files;
+              break;
+            }
 
-          case ParamType.FORM_FIELD: {
-            let value: string | undefined;
+            case ParamType.FORM_FIELD: {
+              let value: string | undefined;
 
-            if (isMultipart && formData && param.name) {
-              const entry = formData.get(param.name);
-              if (typeof entry === 'string') {
-                value = entry;
-              }
-            } else if (jsonBody && param.name) {
-              const jsonValue = jsonBody[param.name];
-              if (jsonValue !== undefined && jsonValue !== null) {
-                value = String(jsonValue);
+              if (isMultipart && formData && param.name) {
+                const entry = formData.get(param.name);
+                if (typeof entry === 'string') {
+                  value = entry;
+                }
+              } else if (jsonBody && param.name) {
+                const jsonValue = jsonBody[param.name];
+                if (jsonValue !== undefined && jsonValue !== null) {
+                  value = String(jsonValue);
+                }
               }
+
+              args[param.index] = value;
+              break;
             }
 
-            args[param.index] = value;
-            break;
+            default:
+              args[param.index] = undefined;
           }
 
-          default:
-            args[param.index] = undefined;
-        }
-
-        // Validate parameter if required
-        if (param.isRequired && (args[param.index] === undefined || args[param.index] === null)) {
-          throw new Error(`Required parameter ${param.name || param.index} is missing`);
-        }
+          // Validate parameter if required
+          if (param.isRequired && (args[param.index] === undefined || args[param.index] === null)) {
+            throw new HttpException(HttpStatusCode.BAD_REQUEST, `Required parameter ${param.name || param.index} is missing`);
+          }
 
-        // For FILES type, also check for empty array when required
-        if (
-          param.isRequired &&
+          // For FILES type, also check for empty array when required
+          if (
+            param.isRequired &&
           param.type === ParamType.FILES &&
           Array.isArray(args[param.index]) &&
           (args[param.index] as unknown[]).length === 0
-        ) {
-          throw new Error(`Required parameter ${param.name || param.index} is missing`);
-        }
+          ) {
+            throw new HttpException(HttpStatusCode.BAD_REQUEST, `Required parameter ${param.name || param.index} is missing`);
+          }
 
-        // Apply arktype schema validation if provided
-        if (param.schema && args[param.index] !== undefined) {
-          try {
-            args[param.index] = validateOrThrow(param.schema, args[param.index]);
-          } catch (error) {
-            const errorMessage =
-              error instanceof Error ? error.message : String(error);
-            throw new Error(
-              `Parameter ${param.name || param.index} validation failed: ${errorMessage}`,
-            );
+          // Apply arktype schema validation if provided
+          if (param.schema && args[param.index] !== undefined) {
+            try {
+              args[param.index] = validateOrThrow(param.schema, args[param.index]);
+            } catch (error) {
+              const errorMessage =
+                error instanceof Error ? error.message : String(error);
+              throw new HttpException(
+                HttpStatusCode.BAD_REQUEST,
+                `Parameter ${param.name || param.index} validation failed: ${errorMessage}`,
+              );
+            }
           }
         }
-      }
-
-      try {
         // Call handler with injected parameters
         const result = await route.handler(...args);
 
@@ -1378,31 +1630,25 @@ export class OneBunApplication {
           },
         });
       } catch (error) {
-        // Convert any thrown errors to standardized error response
-        let errorResponse: ApiResponse<never>;
+        // Run through exception filters (route → controller → global), then default
+        const filters = route.filters ?? [];
+
+        if (filters.length > 0) {
+          const guardCtx = new HttpExecutionContextImpl(
+            req,
+            route.handlerName ?? '',
+            route.controller.constructor.name,
+          );
 
-        if (error instanceof OneBunBaseError) {
-          errorResponse = error.toErrorResponse();
-        } else {
-          const message = error instanceof Error ? error.message : String(error);
-          const code =
-            error instanceof Error && 'code' in error
-              ? Number((error as { code: unknown }).code)
-              : HttpStatusCode.INTERNAL_SERVER_ERROR;
-          errorResponse = createErrorResponse(message, code, message, undefined, {
-            originalErrorName: error instanceof Error ? error.name : 'UnknownError',
-            stack: error instanceof Error ? error.stack : undefined,
-          });
+          // Last filter wins (route-level filters were appended last and take highest priority)
+          return await filters[filters.length - 1].catch(error, guardCtx);
         }
 
-        // Always return 200 for consistency with API response format
-        return new Response(JSON.stringify(errorResponse), {
-          status: HttpStatusCode.OK,
-          headers: {
-            // eslint-disable-next-line @typescript-eslint/naming-convention
-            'Content-Type': 'application/json',
-          },
-        });
+        return await defaultExceptionFilter.catch(error, new HttpExecutionContextImpl(
+          req,
+          route.handlerName ?? '',
+          route.controller.constructor.name,
+        ));
       }
     }
 
@@ -1481,6 +1727,7 @@ export class OneBunApplication {
       await this.queueService.stop();
       this.queueService = null;
     }
+    this.queueServiceProxy?.setDelegate(null);
 
     // Disconnect queue adapter
     if (this.queueAdapter) {
@@ -1542,43 +1789,57 @@ export class OneBunApplication {
     }
 
     // Create the appropriate adapter
-    const adapterType = queueOptions?.adapter ?? 'memory';
-    
-    if (adapterType === 'memory') {
-      this.queueAdapter = new InMemoryQueueAdapter();
-      this.logger.info('Queue system initialized with in-memory adapter');
-    } else if (adapterType === 'redis') {
-      const redisOptions = queueOptions?.redis ?? {};
-      if (redisOptions.useSharedProvider !== false) {
-        // Use shared Redis provider
-        this.queueAdapter = new RedisQueueAdapter({
-          useSharedClient: true,
-          keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
-        });
-        this.logger.info('Queue system initialized with Redis adapter (shared provider)');
-      } else if (redisOptions.url) {
-        // Create dedicated Redis connection
-        this.queueAdapter = new RedisQueueAdapter({
-          useSharedClient: false,
-          url: redisOptions.url,
-          keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
-        });
-        this.logger.info('Queue system initialized with Redis adapter (dedicated connection)');
+    const adapterOpt = queueOptions?.adapter ?? 'memory';
+
+    if (typeof adapterOpt === 'function') {
+      // Custom adapter constructor (e.g. NATS JetStream)
+      const adapterCtor = adapterOpt;
+      this.queueAdapter = new adapterCtor(queueOptions?.options);
+      await this.queueAdapter.connect();
+      this.logger.info(`Queue system initialized with custom adapter: ${this.queueAdapter.name}`);
+    } else {
+      const adapterType = adapterOpt;
+      if (adapterType === 'memory') {
+        this.queueAdapter = new InMemoryQueueAdapter();
+        this.logger.info('Queue system initialized with in-memory adapter');
+      } else if (adapterType === 'redis') {
+        const redisOptions = queueOptions?.redis ?? {};
+        if (redisOptions.useSharedProvider !== false) {
+          // Use shared Redis provider
+          this.queueAdapter = new RedisQueueAdapter({
+            useSharedClient: true,
+            keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
+          });
+          this.logger.info('Queue system initialized with Redis adapter (shared provider)');
+        } else if (redisOptions.url) {
+          // Create dedicated Redis connection
+          this.queueAdapter = new RedisQueueAdapter({
+            useSharedClient: false,
+            url: redisOptions.url,
+            keyPrefix: redisOptions.prefix ?? 'onebun:queue:',
+          });
+          this.logger.info('Queue system initialized with Redis adapter (dedicated connection)');
+        } else {
+          throw new Error('Redis queue adapter requires either useSharedProvider: true or a url');
+        }
       } else {
-        throw new Error('Redis queue adapter requires either useSharedProvider: true or a url');
+        throw new Error(`Unknown queue adapter type: ${adapterType}`);
       }
-    } else {
-      throw new Error(`Unknown queue adapter type: ${adapterType}`);
-    }
 
-    // Connect the adapter
-    await this.queueAdapter.connect();
+      // Connect the adapter
+      await this.queueAdapter.connect();
+    }
 
     // Create queue service with config
-    this.queueService = new QueueService({
-      adapter: adapterType,
-      options: queueOptions?.redis,
-    });
+    const queueServiceConfig: QueueConfig = {
+      adapter:
+        typeof adapterOpt === 'function' ? this.queueAdapter.type : adapterOpt,
+      options:
+        typeof adapterOpt === 'function'
+          ? (queueOptions?.options as Record<string, unknown> | undefined)
+          : queueOptions?.redis,
+    };
+    this.queueService = new QueueService(queueServiceConfig);
     
     // Initialize with the adapter
     await this.queueService.initialize(this.queueAdapter);
@@ -1603,6 +1864,9 @@ export class OneBunApplication {
     // Start the queue service
     await this.queueService.start();
     this.logger.info('Queue service started');
+
+    // Wire the real QueueService into the DI proxy so injected consumers use it
+    this.queueServiceProxy?.setDelegate(this.queueService);
   }
 
   /**
@@ -1723,12 +1987,31 @@ export class OneBunApplication {
     return this.logger;
   }
 
+  /**
+   * Get the actual port the server is listening on.
+   * When `port: 0` is passed, the OS assigns a free port — use this method
+   * to obtain the real port after `start()`.
+   * @returns Actual listening port, or the configured port if not yet started
+   */
+  getPort(): number {
+    return this.server?.port ?? this.options.port ?? 3000;
+  }
+
+  /**
+   * Get the underlying Bun server instance.
+   * Use this to dispatch requests directly (bypassing the global `fetch`) e.g. in tests.
+   * @internal
+   */
+  getServer(): ReturnType<typeof Bun.serve> | null {
+    return this.server;
+  }
+
   /**
    * Get the HTTP URL where the application is listening
    * @returns The HTTP URL
    */
   getHttpUrl(): string {
-    return `http://${this.options.host}:${this.options.port}`;
+    return `http://${this.options.host ?? '0.0.0.0'}:${this.getPort()}`;
   }
 
   /**