@onebun/core 0.1.24 → 0.2.1

package/src/application/application.ts

@@ -30,6 +30,7 @@ import {
   getSseMetadata,
   type SseDecoratorOptions,
 } from '../decorators/decorators';
+import { OneBunFile, validateFile } from '../file/onebun-file';
 import {
   NotInitializedConfig,
   type IConfig,
@@ -47,6 +48,7 @@ import {
   type ApplicationOptions,
   type HttpMethod,
   type ModuleInstance,
+  type OneBunRequest,
   type ParamMetadata,
   ParamType,
   type RouteMetadata,
@@ -113,6 +115,41 @@ function normalizePath(path: string): string {
   return path.endsWith('/') ? path.slice(0, -1) : path;
 }
 
+/**
+ * Extract query parameters from URL, handling array notation and repeated keys.
+ *
+ * @param url - The URL to extract query parameters from
+ * @returns Record of parameter names to values (string for single, string[] for repeated/array notation)
+ * @example
+ * extractQueryParams(new URL('http://x.com/?a=1&b=2'))     // { a: '1', b: '2' }
+ * extractQueryParams(new URL('http://x.com/?tag=a&tag=b')) // { tag: ['a', 'b'] }
+ * extractQueryParams(new URL('http://x.com/?tag[]=a'))     // { tag: ['a'] }
+ */
+function extractQueryParams(url: URL): Record<string, string | string[]> {
+  const queryParams: Record<string, string | string[]> = {};
+
+  for (const [rawKey, value] of url.searchParams.entries()) {
+    // Handle array notation: tag[] -> tag (as array)
+    const isArrayNotation = rawKey.endsWith('[]');
+    const key = isArrayNotation ? rawKey.replace('[]', '') : rawKey;
+
+    const existing = queryParams[key];
+    if (existing !== undefined) {
+      // Handle multiple values with same key (e.g., ?tag=a&tag=b or ?tag[]=a&tag[]=b)
+      queryParams[key] = Array.isArray(existing)
+        ? [...existing, value]
+        : [existing, value];
+    } else if (isArrayNotation) {
+      // Array notation always creates an array, even with single value
+      queryParams[key] = [value];
+    } else {
+      queryParams[key] = value;
+    }
+  }
+
+  return queryParams;
+}
+
 /**
  * Resolve port from options, environment variable, or default.
  * Priority: explicit option > PORT env > default (3000)
@@ -431,163 +468,34 @@ export class OneBunApplication {
       // Initialize Docs (OpenAPI/Swagger) if enabled and available
       await this.initializeDocs(controllers);
 
-      // Create a map of routes with metadata
-      const routes = new Map<
-        string,
-        {
-          method: string;
-          handler: Function;
-          handlerName: string;
-          controller: Controller;
-          params?: ParamMetadata[];
-          middleware?: Function[];
-          pathPattern?: RegExp;
-          pathParams?: string[];
-          responseSchemas?: RouteMetadata['responseSchemas'];
-        }
-      >();
-
-      // Build application-level path prefix from options
-      const appPrefix = this.buildPathPrefix();
-
-      // Add routes from controllers
-      for (const controllerClass of controllers) {
-        const controllerMetadata = getControllerMetadata(controllerClass);
-        if (!controllerMetadata) {
-          this.logger.warn(`No metadata found for controller: ${controllerClass.name}`);
-          continue;
-        }
-
-        // Get controller instance from module
-        if (!this.ensureModule().getControllerInstance) {
-          this.logger.warn(
-            `Module does not support getControllerInstance for ${controllerClass.name}`,
-          );
-          continue;
-        }
-
-        const controller = this.ensureModule().getControllerInstance!(controllerClass) as Controller;
-        if (!controller) {
-          this.logger.warn(`Controller instance not found for ${controllerClass.name}`);
-          continue;
-        }
-
-        const controllerPath = controllerMetadata.path;
-
-        for (const route of controllerMetadata.routes) {
-          // Combine: appPrefix + controllerPath + routePath
-          // Normalize to ensure consistent matching (e.g., '/api/users/' -> '/api/users')
-          const fullPath = normalizePath(`${appPrefix}${controllerPath}${route.path}`);
-          const method = this.mapHttpMethod(route.method);
-          const handler = (controller as unknown as Record<string, Function>)[route.handler].bind(
-            controller,
-          );
-
-          // Process path parameters
-          const pathParams: string[] = [];
-          let pathPattern: RegExp | undefined;
-
-          // Check if path contains parameters like :id
-          if (fullPath.includes(':')) {
-            // Convert path to regex pattern
-            const pattern = fullPath.replace(/:([^/]+)/g, (_, paramName) => {
-              pathParams.push(paramName);
-
-              return '([^/]+)';
-            });
-            pathPattern = new RegExp(`^${pattern}$`);
-          }
-
-          // Use method and path as key to avoid conflicts between different HTTP methods
-          const _routeKey = `${method}:${fullPath}`;
-          routes.set(_routeKey, {
-            method,
-            handler,
-            handlerName: route.handler,
-            controller,
-            params: route.params,
-            middleware: route.middleware,
-            pathPattern,
-            pathParams,
-            responseSchemas: route.responseSchemas,
-          });
-        }
-      }
-
-      // Log all routes
-      for (const controllerClass of controllers) {
-        const metadata = getControllerMetadata(controllerClass);
-        if (!metadata) {
-          continue;
-        }
-
-        for (const route of metadata.routes) {
-          const fullPath = normalizePath(`${appPrefix}${metadata.path}${route.path}`);
-          const method = this.mapHttpMethod(route.method);
-          this.logger.info(`Mapped {${method}} route: ${fullPath}`);
-        }
-      }
-
-      // Call onApplicationInit lifecycle hook for all services and controllers
-      if (this.ensureModule().callOnApplicationInit) {
-        await this.ensureModule().callOnApplicationInit!();
-        this.logger.debug('Application initialization hooks completed');
-      }
+      // Create server context binding (used by route handlers and executeHandler)
+      const app = this;
 
-      // Get metrics path
+      // Path constants for framework endpoints
       const metricsPath = this.options.metrics?.path || '/metrics';
-
-      // Get docs paths
       const docsPath = this.options.docs?.path || '/docs';
       const openApiPath = this.options.docs?.jsonPath || '/openapi.json';
 
-      // Create server with proper context binding
-      const app = this;
-      const hasWebSocketGateways = this.wsHandler?.hasGateways() ?? false;
-      
-      // Prepare WebSocket handlers if gateways exist
-      // When no gateways, use no-op handlers (required by Bun.serve)
-      const wsHandlers = hasWebSocketGateways ? this.wsHandler!.createWebSocketHandlers() : {
-         
-        open() { /* no-op */ },
-         
-        message() { /* no-op */ },
-         
-        close() { /* no-op */ },
-         
-        drain() { /* no-op */ },
-      };
-      
-      this.server = Bun.serve<WsClientData>({
-        port: this.options.port,
-        hostname: this.options.host,
-        // WebSocket handlers
-        websocket: wsHandlers,
-        async fetch(req, server) {
-          const url = new URL(req.url);
-          const rawPath = url.pathname;
-          // Normalize path to ensure consistent routing and metrics
-          // (removes trailing slash except for root path)
-          const path = normalizePath(rawPath);
-          const method = req.method;
-          const startTime = Date.now();
-
-          // Handle WebSocket upgrade if gateways exist
-          if (hasWebSocketGateways && app.wsHandler) {
-            const upgradeHeader = req.headers.get('upgrade')?.toLowerCase();
-            const socketioEnabled = app.options.websocket?.socketio?.enabled ?? false;
-            const socketioPath = app.options.websocket?.socketio?.path ?? '/socket.io';
-
-            const isSocketIoPath = socketioEnabled && path.startsWith(socketioPath);
-            if (upgradeHeader === 'websocket' || isSocketIoPath) {
-              const response = await app.wsHandler.handleUpgrade(req, server);
-              if (response === undefined) {
-                return undefined; // Successfully upgraded
-              }
+      // Build application-level path prefix from options
+      const appPrefix = this.buildPathPrefix();
 
-              return response;
-            }
-          }
+      // Build Bun routes object: { "/path": { GET: handler, POST: handler } }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const bunRoutes: Record<string, any> = {};
+
+      /**
+       * Create a route handler with the full OneBun request lifecycle:
+       * tracing setup → middleware chain → executeHandler → metrics → tracing end
+       */
+      function createRouteHandler(
+        routeMeta: RouteMetadata,
+        boundHandler: Function,
+        controller: Controller,
+        fullPath: string,
+        method: string,
+      ): (req: OneBunRequest) => Promise<Response> {
+        return async (req) => {
+          const startTime = Date.now();
 
           // Setup tracing context if available and enabled
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -626,7 +534,7 @@ export class OneBunApplication {
               const httpData = {
                 method,
                 url: req.url,
-                route: path,
+                route: fullPath,
                 userAgent: headers['user-agent'],
                 remoteAddr: headers['x-forwarded-for'] || headers['x-real-ip'],
                 requestSize: headers['content-length']
@@ -648,9 +556,6 @@ export class OneBunApplication {
                 (globalThis as Record<string, unknown>).__onebunCurrentTraceContext =
                   globalCurrentTraceContext;
               }
-
-              // Propagate trace context to logger
-              // Note: FiberRef.set should be used within Effect context
             } catch (error) {
               app.logger.error(
                 'Failed to setup tracing:',
@@ -659,232 +564,89 @@ export class OneBunApplication {
             }
           }
 
-          // Handle docs endpoints (OpenAPI/Swagger)
-          if (app.options.docs?.enabled !== false && app.openApiSpec) {
-            // Serve Swagger UI HTML
-            if (path === docsPath && method === 'GET' && app.swaggerHtml) {
-              return new Response(app.swaggerHtml, {
-                headers: {
-                  // eslint-disable-next-line @typescript-eslint/naming-convention
-                  'Content-Type': 'text/html; charset=utf-8',
-                },
-              });
-            }
+          // Extract query parameters from URL
+          const url = new URL(req.url);
+          const queryParams = extractQueryParams(url);
 
-            // Serve OpenAPI JSON spec
-            if (path === openApiPath && method === 'GET') {
-              return new Response(JSON.stringify(app.openApiSpec, null, 2), {
-                headers: {
-                  // eslint-disable-next-line @typescript-eslint/naming-convention
-                  'Content-Type': 'application/json',
-                },
-              });
-            }
-          }
+          try {
+            let response: Response;
 
-          // Handle metrics endpoint
-          if (path === metricsPath && method === 'GET' && app.metricsService) {
-            try {
-              const metrics = await app.metricsService.getMetrics();
+            // 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(
+                    {
+                      handler: boundHandler,
+                      handlerName: routeMeta.handler,
+                      controller,
+                      params: routeMeta.params,
+                      responseSchemas: routeMeta.responseSchemas,
+                    },
+                    req,
+                    queryParams,
+                  );
+                }
 
-              return new Response(metrics, {
-                headers: {
-                  // eslint-disable-next-line @typescript-eslint/naming-convention
-                  'Content-Type': app.metricsService.getContentType(),
-                },
-              });
-            } catch (error) {
-              app.logger.error(
-                'Failed to get metrics:',
-                error instanceof Error ? error : new Error(String(error)),
-              );
+                const middleware = routeMeta.middleware![index];
 
-              return new Response('Internal Server Error', {
-                status: HttpStatusCode.INTERNAL_SERVER_ERROR,
-              });
-            }
-          }
-
-          // Find exact match first using method and path
-          const exactRouteKey = `${method}:${path}`;
-          let route = routes.get(exactRouteKey);
-          const paramValues: Record<string, string | string[]> = {};
+                return await middleware(req, () => next(index + 1));
+              };
 
-          // Extract query parameters from URL
-          for (const [rawKey, value] of url.searchParams.entries()) {
-            // Handle array notation: tag[] -> tag (as array)
-            const isArrayNotation = rawKey.endsWith('[]');
-            const key = isArrayNotation ? rawKey.replace('[]', '') : rawKey;
-
-            const existing = paramValues[key];
-            if (existing !== undefined) {
-              // Handle multiple values with same key (e.g., ?tag=a&tag=b or ?tag[]=a&tag[]=b)
-              paramValues[key] = Array.isArray(existing)
-                ? [...existing, value]
-                : [existing, value];
-            } else if (isArrayNotation) {
-              // Array notation always creates an array, even with single value
-              paramValues[key] = [value];
+              response = await next(0);
             } else {
-              paramValues[key] = value;
-            }
-          }
-
-          // If no exact match, try pattern matching
-          if (!route) {
-            for (const [_routeKey, routeData] of routes) {
-              // Check if this route matches the method and has a pattern
-              if (routeData.pathPattern && routeData.method === method) {
-                const match = path.match(routeData.pathPattern);
-                if (match) {
-                  route = routeData;
-                  // Extract parameter values
-                  for (let i = 0; i < routeData.pathParams!.length; i++) {
-                    paramValues[routeData.pathParams![i]] = match[i + 1];
-                  }
-                  break;
-                }
-              }
+              response = await executeHandler(
+                {
+                  handler: boundHandler,
+                  handlerName: routeMeta.handler,
+                  controller,
+                  params: routeMeta.params,
+                  responseSchemas: routeMeta.responseSchemas,
+                },
+                req,
+                queryParams,
+              );
             }
-          }
 
-          if (!route) {
-            const response = new Response('Not Found', {
-              status: HttpStatusCode.NOT_FOUND,
-            });
             const duration = Date.now() - startTime;
 
-            // Record metrics for 404
+            // Record metrics
             if (app.metricsService && app.metricsService.recordHttpRequest) {
               const durationSeconds = duration / 1000;
               app.metricsService.recordHttpRequest({
                 method,
-                route: path,
-                statusCode: HttpStatusCode.NOT_FOUND,
+                route: fullPath,
+                statusCode: response?.status || HttpStatusCode.OK,
                 duration: durationSeconds,
-                controller: 'unknown',
+                controller: controller.constructor.name,
                 action: 'unknown',
               });
             }
 
-            // End trace for 404
+            // End trace
             if (traceSpan && app.traceService) {
               try {
                 await Effect.runPromise(
                   app.traceService.endHttpTrace(traceSpan, {
-                    statusCode: HttpStatusCode.NOT_FOUND,
+                    statusCode: response?.status || HttpStatusCode.OK,
+                    responseSize: response?.headers?.get('content-length')
+                      ? parseInt(response.headers.get('content-length')!, 10)
+                      : undefined,
                     duration,
                   }),
                 );
               } catch (traceError) {
                 app.logger.error(
-                  'Failed to end trace for 404:',
+                  'Failed to end trace:',
                   traceError instanceof Error ? traceError : new Error(String(traceError)),
                 );
               }
             }
 
-            // Clear trace context after 404
+            // Clear trace context after request
             clearGlobalTraceContext();
 
             return response;
-          }
-
-          try {
-            // Execute middleware if any
-            if (route.middleware && route.middleware.length > 0) {
-              const next = async (index: number): Promise<Response> => {
-                if (index >= route!.middleware!.length) {
-                  return await executeHandler(route!, req, paramValues);
-                }
-
-                const middleware = route!.middleware![index];
-
-                return await middleware(req, () => next(index + 1));
-              };
-
-              const response = await next(0);
-              const duration = Date.now() - startTime;
-
-              // Record metrics
-              if (app.metricsService && app.metricsService.recordHttpRequest) {
-                const durationSeconds = duration / 1000;
-                app.metricsService.recordHttpRequest({
-                  method,
-                  route: path,
-                  statusCode: response?.status || HttpStatusCode.OK,
-                  duration: durationSeconds,
-                  controller: route.controller.constructor.name,
-                  action: 'unknown',
-                });
-              }
-
-              // End trace
-              if (traceSpan && app.traceService) {
-                try {
-                  await Effect.runPromise(
-                    app.traceService.endHttpTrace(traceSpan, {
-                      statusCode: response?.status || HttpStatusCode.OK,
-                      responseSize: response?.headers?.get('content-length')
-                        ? parseInt(response.headers.get('content-length')!, 10)
-                        : undefined,
-                      duration,
-                    }),
-                  );
-                } catch (traceError) {
-                  app.logger.error(
-                    'Failed to end trace:',
-                    traceError instanceof Error ? traceError : new Error(String(traceError)),
-                  );
-                }
-              }
-
-              // Clear trace context after request
-              clearGlobalTraceContext();
-
-              return response;
-            } else {
-              const response = await executeHandler(route, req, paramValues);
-              const duration = Date.now() - startTime;
-
-              // Record metrics
-              if (app.metricsService && app.metricsService.recordHttpRequest) {
-                const durationSeconds = duration / 1000;
-                app.metricsService.recordHttpRequest({
-                  method,
-                  route: path,
-                  statusCode: response?.status || HttpStatusCode.OK,
-                  duration: durationSeconds,
-                  controller: route.controller.constructor.name,
-                  action: 'unknown',
-                });
-              }
-
-              // End trace
-              if (traceSpan && app.traceService) {
-                try {
-                  await Effect.runPromise(
-                    app.traceService.endHttpTrace(traceSpan, {
-                      statusCode: response?.status || HttpStatusCode.OK,
-                      responseSize: response?.headers?.get('content-length')
-                        ? parseInt(response.headers.get('content-length')!, 10)
-                        : undefined,
-                      duration,
-                    }),
-                  );
-                } catch (traceError) {
-                  app.logger.error(
-                    'Failed to end trace:',
-                    traceError instanceof Error ? traceError : new Error(String(traceError)),
-                  );
-                }
-              }
-
-              // Clear trace context after request
-              clearGlobalTraceContext();
-
-              return response;
-            }
           } catch (error) {
             app.logger.error(
               'Request handling error:',
@@ -900,10 +662,10 @@ export class OneBunApplication {
               const durationSeconds = duration / 1000;
               app.metricsService.recordHttpRequest({
                 method,
-                route: path,
+                route: fullPath,
                 statusCode: HttpStatusCode.INTERNAL_SERVER_ERROR,
                 duration: durationSeconds,
-                controller: route?.controller.constructor.name || 'unknown',
+                controller: controller.constructor.name,
                 action: 'unknown',
               });
             }
@@ -936,6 +698,179 @@ export class OneBunApplication {
 
             return response;
           }
+        };
+      }
+
+      // Add routes from controllers
+      for (const controllerClass of controllers) {
+        const controllerMetadata = getControllerMetadata(controllerClass);
+        if (!controllerMetadata) {
+          this.logger.warn(`No metadata found for controller: ${controllerClass.name}`);
+          continue;
+        }
+
+        // Get controller instance from module
+        if (!this.ensureModule().getControllerInstance) {
+          this.logger.warn(
+            `Module does not support getControllerInstance for ${controllerClass.name}`,
+          );
+          continue;
+        }
+
+        const controller = this.ensureModule().getControllerInstance!(controllerClass) as Controller;
+        if (!controller) {
+          this.logger.warn(`Controller instance not found for ${controllerClass.name}`);
+          continue;
+        }
+
+        const controllerPath = controllerMetadata.path;
+
+        for (const route of controllerMetadata.routes) {
+          // Combine: appPrefix + controllerPath + routePath
+          // Normalize to ensure consistent matching (e.g., '/api/users/' -> '/api/users')
+          const fullPath = normalizePath(`${appPrefix}${controllerPath}${route.path}`);
+          const method = this.mapHttpMethod(route.method);
+          const handler = (controller as unknown as Record<string, Function>)[route.handler].bind(
+            controller,
+          );
+
+          // Create wrapped handler with full OneBun lifecycle (tracing, metrics, middleware)
+          const wrappedHandler = createRouteHandler(route, handler, controller, fullPath, method);
+
+          // Add to bunRoutes grouped by path and method
+          if (!bunRoutes[fullPath]) {
+            bunRoutes[fullPath] = {};
+          }
+          bunRoutes[fullPath][method] = wrappedHandler;
+
+          // Register trailing slash variant for consistent matching
+          // (e.g., /api/users and /api/users/ both map to the same handler)
+          if (fullPath.length > 1 && !fullPath.endsWith('/')) {
+            const trailingPath = fullPath + '/';
+            if (!bunRoutes[trailingPath]) {
+              bunRoutes[trailingPath] = {};
+            }
+            bunRoutes[trailingPath][method] = wrappedHandler;
+          }
+        }
+      }
+
+      // Add framework endpoints to routes (docs, metrics)
+      if (app.options.docs?.enabled !== false && app.openApiSpec) {
+        if (app.swaggerHtml) {
+          bunRoutes[docsPath] = {
+             
+            GET: () => new Response(app.swaggerHtml!, {
+              headers: {
+                // eslint-disable-next-line @typescript-eslint/naming-convention
+                'Content-Type': 'text/html; charset=utf-8',
+              },
+            }),
+          };
+        }
+        bunRoutes[openApiPath] = {
+           
+          GET: () => new Response(JSON.stringify(app.openApiSpec, null, 2), {
+            headers: {
+              // eslint-disable-next-line @typescript-eslint/naming-convention
+              'Content-Type': 'application/json',
+            },
+          }),
+        };
+      }
+
+      if (app.metricsService) {
+        bunRoutes[metricsPath] = {
+           
+          async GET() {
+            try {
+              const metrics = await app.metricsService.getMetrics();
+
+              return new Response(metrics, {
+                headers: {
+                  // eslint-disable-next-line @typescript-eslint/naming-convention
+                  'Content-Type': app.metricsService.getContentType(),
+                },
+              });
+            } catch (error) {
+              app.logger.error(
+                'Failed to get metrics:',
+                error instanceof Error ? error : new Error(String(error)),
+              );
+
+              return new Response('Internal Server Error', {
+                status: HttpStatusCode.INTERNAL_SERVER_ERROR,
+              });
+            }
+          },
+        };
+      }
+
+      // Log all routes
+      for (const controllerClass of controllers) {
+        const metadata = getControllerMetadata(controllerClass);
+        if (!metadata) {
+          continue;
+        }
+
+        for (const route of metadata.routes) {
+          const fullPath = normalizePath(`${appPrefix}${metadata.path}${route.path}`);
+          const method = this.mapHttpMethod(route.method);
+          this.logger.info(`Mapped {${method}} route: ${fullPath}`);
+        }
+      }
+
+      // Call onApplicationInit lifecycle hook for all services and controllers
+      if (this.ensureModule().callOnApplicationInit) {
+        await this.ensureModule().callOnApplicationInit!();
+        this.logger.debug('Application initialization hooks completed');
+      }
+
+      const hasWebSocketGateways = this.wsHandler?.hasGateways() ?? false;
+      
+      // Prepare WebSocket handlers if gateways exist
+      // When no gateways, use no-op handlers (required by Bun.serve)
+      const wsHandlers = hasWebSocketGateways ? this.wsHandler!.createWebSocketHandlers() : {
+         
+        open() { /* no-op */ },
+         
+        message() { /* no-op */ },
+         
+        close() { /* no-op */ },
+         
+        drain() { /* no-op */ },
+      };
+      
+      this.server = Bun.serve<WsClientData>({
+        port: this.options.port,
+        hostname: this.options.host,
+        // WebSocket handlers
+        websocket: wsHandlers,
+        // Bun routes API: all endpoints are handled here
+        routes: bunRoutes,
+        // Fallback: only WebSocket upgrade and 404
+        async fetch(req, server) {
+          // Handle WebSocket upgrade if gateways exist
+          if (hasWebSocketGateways && app.wsHandler) {
+            const upgradeHeader = req.headers.get('upgrade')?.toLowerCase();
+            const socketioEnabled = app.options.websocket?.socketio?.enabled ?? false;
+            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);
+            if (upgradeHeader === 'websocket' || isSocketIoPath) {
+              const response = await app.wsHandler.handleUpgrade(req, server);
+              if (response === undefined) {
+                return undefined; // Successfully upgraded
+              }
+
+              return response;
+            }
+          }
+
+          // 404 for everything not matched by routes
+          return new Response('Not Found', { status: HttpStatusCode.NOT_FOUND });
         },
       });
 
@@ -978,7 +913,46 @@ export class OneBunApplication {
     }
 
     /**
-     * Execute route handler with parameter injection and validation
+     * Extract an OneBunFile from a JSON value.
+     * Supports two formats:
+     * - String: raw base64 data
+     * - Object: { data: string, filename?: string, mimeType?: string }
+     */
+    function extractFileFromJsonValue(value: unknown): OneBunFile | undefined {
+      if (typeof value === 'string' && value.length > 0) {
+        return OneBunFile.fromBase64(value);
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value as Record<string, unknown>;
+        if (typeof obj.data === 'string' && obj.data.length > 0) {
+          return OneBunFile.fromBase64(
+            obj.data,
+            typeof obj.filename === 'string' ? obj.filename : undefined,
+            typeof obj.mimeType === 'string' ? obj.mimeType : undefined,
+          );
+        }
+      }
+
+      return undefined;
+    }
+
+    /**
+     * Extract a file from a JSON body by field name
+     */
+    function extractFileFromJson(
+      jsonBody: Record<string, unknown>,
+      fieldName: string,
+    ): OneBunFile | undefined {
+      const fieldValue = jsonBody[fieldName];
+
+      return extractFileFromJsonValue(fieldValue);
+    }
+
+    /**
+     * Execute route handler with parameter injection and validation.
+     * Path parameters come from BunRequest.params (populated by Bun routes API).
+     * Query parameters are extracted separately from the URL.
      */
     async function executeHandler(
       route: {
@@ -988,8 +962,8 @@ export class OneBunApplication {
         params?: ParamMetadata[];
         responseSchemas?: RouteMetadata['responseSchemas'];
       },
-      req: Request,
-      paramValues: Record<string, string | string[]>,
+      req: OneBunRequest,
+      queryParams: Record<string, string | string[]>,
     ): Promise<Response> {
       // Check if this is an SSE endpoint
       let sseOptions: SseDecoratorOptions | undefined;
@@ -1015,14 +989,63 @@ export class OneBunApplication {
       // 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 ||
+          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. ' +
+            '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;
+
+      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>;
+            }
+          } catch {
+            jsonBody = null;
+          }
+        }
+      }
+
       for (const param of sortedParams) {
         switch (param.type) {
           case ParamType.PATH:
-            args[param.index] = param.name ? paramValues[param.name] : undefined;
+            // 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;
 
           case ParamType.QUERY:
-            args[param.index] = param.name ? paramValues[param.name] : undefined;
+            args[param.index] = param.name ? queryParams[param.name] : undefined;
             break;
 
           case ParamType.BODY:
@@ -1037,6 +1060,10 @@ export class OneBunApplication {
             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.REQUEST:
             args[param.index] = req;
             break;
@@ -1046,6 +1073,100 @@ export class OneBunApplication {
             args[param.index] = undefined;
             break;
 
+          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);
+              }
+            } else if (jsonBody && param.name) {
+              file = extractFileFromJson(jsonBody, param.name);
+            }
+
+            if (file && param.fileOptions) {
+              validateFile(file, param.fileOptions, param.name);
+            }
+
+            args[param.index] = file;
+            break;
+          }
+
+          case ParamType.FILES: {
+            let files: OneBunFile[] = [];
+
+            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 {
+                // Get all files from all fields
+                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 {
+                // Extract all file-like values from JSON
+                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 each file
+            if (param.fileOptions) {
+              for (const file of files) {
+                validateFile(file, param.fileOptions, param.name);
+              }
+            }
+
+            args[param.index] = files;
+            break;
+          }
+
+          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);
+              }
+            }
+
+            args[param.index] = value;
+            break;
+          }
+
           default:
             args[param.index] = undefined;
         }
@@ -1055,6 +1176,16 @@ export class OneBunApplication {
           throw new Error(`Required parameter ${param.name || param.index} is missing`);
         }
 
+        // 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`);
+        }
+
         // Apply arktype schema validation if provided
         if (param.schema && args[param.index] !== undefined) {
           try {
@@ -1085,7 +1216,6 @@ export class OneBunApplication {
         // If the result is already a Response object, extract body and validate it
         if (result instanceof Response) {
           responseStatusCode = result.status;
-          const responseHeaders = Object.fromEntries(result.headers.entries());
 
           // Extract and parse response body for validation
           const contentType = result.headers.get('content-type') || '';
@@ -1119,14 +1249,16 @@ export class OneBunApplication {
                 validatedResult = bodyData;
               }
 
+              // Preserve all original headers (including multiple Set-Cookie)
+              // using new Headers() constructor instead of Object.fromEntries()
+              // which would lose duplicate header keys
+              const newHeaders = new Headers(result.headers);
+              newHeaders.set('Content-Type', 'application/json');
+
               // Create new Response with validated data
               return new Response(JSON.stringify(validatedResult), {
                 status: responseStatusCode,
-                headers: {
-                  ...responseHeaders,
-                  // eslint-disable-next-line @typescript-eslint/naming-convention
-                  'Content-Type': 'application/json',
-                },
+                headers: newHeaders,
               });
             } catch {
               // If parsing fails, return original response