@onebun/core 0.2.7 → 0.2.9

package/src/application/application.ts

@@ -23,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,
@@ -50,7 +53,7 @@ import {
   DEFAULT_SSE_HEARTBEAT_MS,
   DEFAULT_SSE_TIMEOUT,
 } from '../module/controller';
-import { OneBunModule } from '../module/module';
+import { OneBunModule, registerGlobalService } from '../module/module';
 import {
   QueueService,
   QueueServiceProxy,
@@ -62,6 +65,9 @@ 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,
@@ -484,18 +490,25 @@ export class OneBunApplication {
         this.logger.info('Application configuration initialized');
       }
 
-      // Create the root module AFTER config is initialized,
+      // Register QueueService proxy in global registry BEFORE creating the root module,
+      // so all modules (including child modules) pick it up via PHASE 0 of initModule().
+      // After initializeQueue(), setDelegate(real) is called when queue is enabled.
+      this.queueServiceProxy = new QueueServiceProxy();
+      registerGlobalService(
+        QueueServiceTag as Context.Tag<unknown, QueueService>,
+        this.queueServiceProxy as unknown as QueueService,
+      );
+
+      // Create the root module AFTER config is initialized and QueueService proxy is registered,
       // so services can safely use this.config.get() in their constructors
+      // and inject QueueService in any module depth.
       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
@@ -652,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;
@@ -782,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
@@ -847,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)
@@ -1201,6 +1273,7 @@ export class OneBunApplication {
         controller: Controller;
         params?: ParamMetadata[];
         responseSchemas?: RouteMetadata['responseSchemas'];
+        filters?: ExceptionFilter[];
       },
       req: OneBunRequest,
       queryParams: Record<string, string | string[]>,
@@ -1223,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);
 
@@ -1555,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,
+        ));
       }
     }
 
@@ -1918,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()}`;
   }
 
   /**