@onebun/core 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/application/application.test.ts

@@ -906,6 +906,42 @@ describe('OneBunApplication', () => {
       expect(Bun.serve).toHaveBeenCalled();
     });
 
+    test('should pass default idleTimeout (120s) to Bun.serve', async () => {
+      @Module({})
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const serveCall = (Bun.serve as any).mock.calls[0];
+      expect(serveCall[0].idleTimeout).toBe(120);
+    });
+
+    test('should pass custom idleTimeout to Bun.serve', async () => {
+      @Module({})
+      class TestModule {}
+
+      const app = createTestApp(TestModule, { idleTimeout: 60 });
+      await app.start();
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const serveCall = (Bun.serve as any).mock.calls[0];
+      expect(serveCall[0].idleTimeout).toBe(60);
+    });
+
+    test('should pass idleTimeout: 0 to disable timeout', async () => {
+      @Module({})
+      class TestModule {}
+
+      const app = createTestApp(TestModule, { idleTimeout: 0 });
+      await app.start();
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const serveCall = (Bun.serve as any).mock.calls[0];
+      expect(serveCall[0].idleTimeout).toBe(0);
+    });
+
     test('should start application with config initialization', async () => {
       @Module({})
       class TestModule {}

package/src/application/application.ts

@@ -27,6 +27,7 @@ import { makeTraceService, TraceService } from '@onebun/trace';
 
 import {
   getControllerMetadata,
+  getControllerMiddleware,
   getSseMetadata,
   type SseDecoratorOptions,
 } from '../decorators/decorators';
@@ -37,7 +38,12 @@ import {
   type OneBunAppConfig,
 } from '../module/config.interface';
 import { ConfigServiceImpl } from '../module/config.service';
-import { createSseStream } from '../module/controller';
+import {
+  createSseStream,
+  DEFAULT_IDLE_TIMEOUT,
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_TIMEOUT,
+} from '../module/controller';
 import { OneBunModule } from '../module/module';
 import { QueueService, type QueueAdapter } from '../queue';
 import { InMemoryQueueAdapter } from '../queue/adapters/memory.adapter';
@@ -485,7 +491,7 @@ export class OneBunApplication {
 
       /**
        * Create a route handler with the full OneBun request lifecycle:
-       * tracing setup → middleware chain → executeHandler → metrics → tracing end
+       * tracing setup → per-request timeout → middleware chain → executeHandler → metrics → tracing end
        */
       function createRouteHandler(
         routeMeta: RouteMetadata,
@@ -493,10 +499,28 @@ export class OneBunApplication {
         controller: Controller,
         fullPath: string,
         method: string,
-      ): (req: OneBunRequest) => Promise<Response> {
-        return async (req) => {
+      ): (req: OneBunRequest, server: ReturnType<typeof Bun.serve>) => Promise<Response> {
+        // Determine the effective timeout for this route:
+        // SSE endpoints check @Sse({ timeout }) first, then route-level, then DEFAULT_SSE_TIMEOUT
+        // Normal endpoints use route-level timeout only (undefined = use global idleTimeout)
+        const isSse = routeMeta.handler
+          ? getSseMetadata(Object.getPrototypeOf(controller), routeMeta.handler) !== undefined
+          : false;
+        const sseDecoratorOptions = routeMeta.handler
+          ? getSseMetadata(Object.getPrototypeOf(controller), routeMeta.handler)
+          : undefined;
+        const effectiveTimeout: number | undefined = isSse
+          ? (sseDecoratorOptions?.timeout ?? routeMeta.timeout ?? DEFAULT_SSE_TIMEOUT)
+          : routeMeta.timeout;
+
+        return async (req, server) => {
           const startTime = Date.now();
 
+          // Apply per-request idle timeout if configured
+          if (effectiveTimeout !== undefined) {
+            server.timeout(req, effectiveTimeout);
+          }
+
           // Setup tracing context if available and enabled
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           let traceSpan: any = null;
@@ -701,6 +725,12 @@ export class OneBunApplication {
         };
       }
 
+      // 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) ?? [])
+        : [];
+
       // Add routes from controllers
       for (const controllerClass of controllers) {
         const controllerMetadata = getControllerMetadata(controllerClass);
@@ -725,6 +755,15 @@ export class OneBunApplication {
 
         const controllerPath = controllerMetadata.path;
 
+        // Module-level middleware (already resolved bound functions)
+        const moduleMiddleware = this.ensureModule().getModuleMiddleware?.(controllerClass) ?? [];
+
+        // Controller-level middleware — resolve class constructors via root module DI
+        const ctrlMiddlewareClasses = getControllerMiddleware(controllerClass);
+        const ctrlMiddleware: Function[] = ctrlMiddlewareClasses.length > 0
+          ? (this.ensureModule().resolveMiddleware?.(ctrlMiddlewareClasses) ?? [])
+          : [];
+
         for (const route of controllerMetadata.routes) {
           // Combine: appPrefix + controllerPath + routePath
           // Normalize to ensure consistent matching (e.g., '/api/users/' -> '/api/users')
@@ -734,8 +773,26 @@ export class OneBunApplication {
             controller,
           );
 
+          // Route-level middleware — resolve class constructors via root module DI
+          const routeMiddlewareClasses = route.middleware ?? [];
+          const routeMiddleware: Function[] = routeMiddlewareClasses.length > 0
+            ? (this.ensureModule().resolveMiddleware?.(routeMiddlewareClasses) ?? [])
+            : [];
+
+          // Merge middleware: global → module → controller → route
+          const mergedMiddleware = [
+            ...globalMiddleware,
+            ...moduleMiddleware,
+            ...ctrlMiddleware,
+            ...routeMiddleware,
+          ];
+          const routeWithMergedMiddleware: RouteMetadata = {
+            ...route,
+            middleware: mergedMiddleware.length > 0 ? mergedMiddleware : undefined,
+          };
+
           // Create wrapped handler with full OneBun lifecycle (tracing, metrics, middleware)
-          const wrappedHandler = createRouteHandler(route, handler, controller, fullPath, method);
+          const wrappedHandler = createRouteHandler(routeWithMergedMiddleware, handler, controller, fullPath, method);
 
           // Add to bunRoutes grouped by path and method
           if (!bunRoutes[fullPath]) {
@@ -844,6 +901,8 @@ export class OneBunApplication {
       this.server = Bun.serve<WsClientData>({
         port: this.options.port,
         hostname: this.options.host,
+        // Idle timeout (seconds) — default 120s to support SSE and long-running requests
+        idleTimeout: this.options.idleTimeout ?? DEFAULT_IDLE_TIMEOUT,
         // WebSocket handlers
         websocket: wsHandlers,
         // Bun routes API: all endpoints are handled here
@@ -1358,9 +1417,14 @@ export class OneBunApplication {
 
       // Check if result is an async iterable (generator)
       if (result && typeof result === 'object' && Symbol.asyncIterator in result) {
+        // Apply default heartbeat if none specified to keep the connection alive
+        const effectiveOptions = {
+          ...options,
+          heartbeat: options.heartbeat ?? DEFAULT_SSE_HEARTBEAT_MS,
+        };
         const stream = createSseStream(
           result as AsyncIterable<unknown>,
-          options,
+          effectiveOptions,
         );
 
         return new Response(stream, {

package/src/application/multi-service-application.ts

@@ -143,6 +143,7 @@ export class MultiServiceApplication<TServices extends ServicesMap = ServicesMap
       envOverrides: { ...appOptions.envOverrides, ...serviceOptions.envOverrides },
       envSchemaExtend: serviceOptions.envSchemaExtend,
       logger: { ...appOptions.logger, ...serviceOptions.logger },
+      middleware: serviceOptions.middleware ?? appOptions.middleware,
       metrics: { ...appOptions.metrics, ...serviceOptions.metrics },
       tracing: { ...appOptions.tracing, ...serviceOptions.tracing },
     };
@@ -197,6 +198,7 @@ export class MultiServiceApplication<TServices extends ServicesMap = ServicesMap
         basePath: mergedOptions.basePath,
         // When routePrefix is true, use service name as prefix
         routePrefix: mergedOptions.routePrefix ? name : undefined,
+        middleware: mergedOptions.middleware,
         envSchema: mergedEnvSchema,
         envOptions: {
           ...this.options.envOptions,

package/src/application/multi-service.types.ts

@@ -30,7 +30,7 @@ export type TracingOptions = NonNullable<ApplicationOptions['tracing']>;
  * Any new shared options should be added to ApplicationOptions first.
  */
 export interface BaseServiceOptions
-  extends Pick<ApplicationOptions, 'host' | 'basePath' | 'metrics' | 'tracing'> {
+  extends Pick<ApplicationOptions, 'host' | 'basePath' | 'metrics' | 'tracing' | 'middleware'> {
   /**
    * Add service name as prefix to all routes.
    * When true, the service name will be used as routePrefix.

package/src/decorators/decorators.test.ts

@@ -20,8 +20,14 @@ import {
   BaseService,
   Service,
 } from '../module';
+import { BaseMiddleware } from '../module/middleware';
 import { makeMockLoggerLayer } from '../testing';
-import { HttpMethod, ParamType } from '../types';
+import {
+  HttpMethod,
+  ParamType,
+  type OneBunRequest,
+  type OneBunResponse,
+} from '../types';
 
 import {
   injectable,
@@ -52,6 +58,7 @@ import {
   UploadedFile,
   UploadedFiles,
   FormField,
+  getControllerMiddleware,
 } from './decorators';
 
 describe('decorators', () => {
@@ -678,42 +685,51 @@ describe('decorators', () => {
   });
 
   describe('UseMiddleware decorator', () => {
-    const middleware1 = () => {};
-    const middleware2 = () => {};
+    class Middleware1 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
 
-    test('should register middleware for method', () => {
+    class Middleware2 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
+
+    test('should register middleware class for method', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1)
+        @UseMiddleware(Middleware1)
         test() {}
       }
 
       const metadata = getControllerMetadata(TestController);
       const route = metadata?.routes[0];
-      expect(route?.middleware).toContain(middleware1);
+      expect(route?.middleware).toContain(Middleware1);
     });
 
-    test('should register multiple middleware functions', () => {
+    test('should register multiple middleware classes', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1, middleware2)
+        @UseMiddleware(Middleware1, Middleware2)
         test() {}
       }
 
       const metadata = getControllerMetadata(TestController);
       const route = metadata?.routes[0];
-      expect(route?.middleware).toContain(middleware1);
-      expect(route?.middleware).toContain(middleware2);
+      expect(route?.middleware).toContain(Middleware1);
+      expect(route?.middleware).toContain(Middleware2);
     });
 
     test('should append to existing middleware', () => {
       @Controller()
       class TestController {
         @Get()
-        @UseMiddleware(middleware1)
-        @UseMiddleware(middleware2)
+        @UseMiddleware(Middleware1)
+        @UseMiddleware(Middleware2)
         test() {}
       }
 
@@ -721,6 +737,41 @@ describe('decorators', () => {
       const route = metadata?.routes[0];
       expect(route?.middleware).toHaveLength(2);
     });
+
+    test('should register middleware as class decorator', () => {
+      @Controller()
+      @UseMiddleware(Middleware1, Middleware2)
+      class TestController {
+        @Get()
+        test() {}
+      }
+
+      const controllerMw = getControllerMiddleware(TestController);
+      expect(controllerMw).toHaveLength(2);
+      expect(controllerMw).toContain(Middleware1);
+      expect(controllerMw).toContain(Middleware2);
+    });
+
+    test('should keep class and method middleware separate', () => {
+      @Controller()
+      @UseMiddleware(Middleware1)
+      class TestController {
+        @Get()
+        @UseMiddleware(Middleware2)
+        test() {}
+      }
+
+      // Class-level
+      const controllerMw = getControllerMiddleware(TestController);
+      expect(controllerMw).toHaveLength(1);
+      expect(controllerMw[0]).toBe(Middleware1);
+
+      // Route-level
+      const metadata = getControllerMetadata(TestController);
+      const route = metadata?.routes[0];
+      expect(route?.middleware).toHaveLength(1);
+      expect(route?.middleware?.[0]).toBe(Middleware2);
+    });
   });
 
   describe('Module decorator', () => {

package/src/decorators/decorators.ts

@@ -9,6 +9,7 @@ import {
   type ParamDecoratorOptions,
   type ParamMetadata,
   ParamType,
+  type RouteOptions,
 } from '../types';
 
 import { getConstructorParamTypes as getDesignParamTypes, Reflect } from './metadata';
@@ -200,6 +201,18 @@ export function controllerDecorator(basePath: string = '') {
       META_CONSTRUCTOR_PARAMS.set(WrappedController, existingDeps);
     }
 
+    // Copy controller-level middleware from original class to wrapped class
+    // This ensures @UseMiddleware works regardless of decorator order
+    const existingControllerMiddleware: Function[] | undefined =
+      Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target);
+    if (existingControllerMiddleware) {
+      Reflect.defineMetadata(
+        CONTROLLER_MIDDLEWARE_METADATA,
+        existingControllerMiddleware,
+        WrappedController,
+      );
+    }
+
     return WrappedController as T;
   };
 }
@@ -266,7 +279,7 @@ const RESPONSE_SCHEMAS_METADATA = 'onebun:responseSchemas';
  * Base route decorator factory
  */
 function createRouteDecorator(method: HttpMethod) {
-  return (path: string = '') =>
+  return (path: string = '', options?: RouteOptions) =>
     (target: object, propertyKey: string, descriptor: PropertyDescriptor) => {
       const controllerClass = target.constructor as Function;
 
@@ -309,6 +322,7 @@ function createRouteDecorator(method: HttpMethod) {
           schema: rs.schema,
           description: rs.description,
         })),
+        ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}),
       });
 
       META_CONTROLLERS.set(controllerClass, metadata);
@@ -635,12 +649,72 @@ export function FormField(fieldName: string, options?: ParamDecoratorOptions): P
 }
 
 /**
- * Middleware decorator
- * @example \@UseMiddleware(authMiddleware)
+ * Metadata key for controller-level middleware
  */
+const CONTROLLER_MIDDLEWARE_METADATA = 'onebun:controller_middleware';
 
-export function UseMiddleware(...middleware: Function[]): MethodDecorator {
-  return (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+/**
+ * Middleware decorator — can be applied to both controllers (class) and individual routes (method).
+ *
+ * Pass middleware **class constructors** (extending `BaseMiddleware`), not instances.
+ * The framework instantiates them once at startup with full DI support.
+ *
+ * When applied to a class, the middleware is added to **every** route in that controller
+ * and runs after global and module-level middleware but before route-level middleware.
+ *
+ * When applied to a method, the middleware runs after controller-level middleware.
+ *
+ * Execution order: global → controller → route → handler
+ *
+ * @example Class-level (all routes)
+ * ```typescript
+ * \@Controller('/admin')
+ * \@UseMiddleware(AuthMiddleware)
+ * class AdminController extends BaseController { ... }
+ * ```
+ *
+ * @example Method-level (single route)
+ * ```typescript
+ * \@Post('/action')
+ * \@UseMiddleware(LogMiddleware)
+ * action() { ... }
+ * ```
+ *
+ * @example Combined
+ * ```typescript
+ * \@Controller('/admin')
+ * \@UseMiddleware(AuthMiddleware)       // runs on every route
+ * class AdminController extends BaseController {
+ *   \@Get('/dashboard')
+ *   \@UseMiddleware(CacheMiddleware)    // runs only on this route, after auth
+ *   getDashboard() { ... }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function UseMiddleware(...middleware: Function[]): any {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function useMiddlewareDecorator(...args: any[]): any {
+    // ---- Class decorator: target is a constructor function ----
+    if (args.length === 1 && typeof args[0] === 'function') {
+      const target = args[0] as Function;
+      const existing: Function[] =
+        Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target) || [];
+      Reflect.defineMetadata(
+        CONTROLLER_MIDDLEWARE_METADATA,
+        [...existing, ...middleware],
+        target,
+      );
+
+      return target;
+    }
+
+    // ---- Method decorator: (target, propertyKey, descriptor) ----
+    const [target, propertyKey, descriptor] = args as [
+      object,
+      string | symbol,
+      PropertyDescriptor,
+    ];
     const existingMiddleware: Function[] =
       Reflect.getMetadata(MIDDLEWARE_METADATA, target, propertyKey) || [];
     Reflect.defineMetadata(
@@ -654,6 +728,17 @@ export function UseMiddleware(...middleware: Function[]): MethodDecorator {
   };
 }
 
+/**
+ * Get controller-level middleware class constructors for a controller class.
+ * Returns middleware registered via @UseMiddleware() applied to the class.
+ *
+ * @param target - Controller class (constructor)
+ * @returns Array of middleware class constructors
+ */
+export function getControllerMiddleware(target: Function): Function[] {
+  return Reflect.getMetadata(CONTROLLER_MIDDLEWARE_METADATA, target) || [];
+}
+
 /**
  * HTTP GET decorator
  */
@@ -719,8 +804,17 @@ export interface SseDecoratorOptions {
    * Heartbeat interval in milliseconds.
    * When set, the server will send a comment (": heartbeat\n\n")
    * at this interval to keep the connection alive.
+   * @defaultValue 30000 (30 seconds) when using @Sse() decorator
    */
   heartbeat?: number;
+
+  /**
+   * Per-request idle timeout in seconds for this SSE connection.
+   * Overrides the global `idleTimeout` from `ApplicationOptions`.
+   * Set to 0 to disable the timeout entirely.
+   * @defaultValue 600 (10 minutes) for SSE endpoints
+   */
+  timeout?: number;
 }
 
 /**
@@ -766,7 +860,10 @@ export function Sse(options?: SseDecoratorOptions): MethodDecorator {
 }
 
 /**
- * Check if a method is marked as SSE endpoint
+ * Check if a method is marked as SSE endpoint.
+ * Traverses the prototype chain so that metadata stored on the original class
+ * prototype is found even when `@Controller` wraps the class.
+ *
  * @param target - Controller instance or prototype
  * @param methodName - Method name
  * @returns SSE options if method is SSE endpoint, undefined otherwise
@@ -775,7 +872,16 @@ export function getSseMetadata(
   target: object,
   methodName: string,
 ): SseDecoratorOptions | undefined {
-  return Reflect.getMetadata(SSE_METADATA, target, methodName);
+  let proto: object | null = target;
+  while (proto) {
+    const metadata = Reflect.getMetadata(SSE_METADATA, proto, methodName);
+    if (metadata !== undefined) {
+      return metadata;
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+
+  return undefined;
 }
 
 /**