@onebun/core 0.2.1 → 0.2.2

package/src/index.ts

@@ -36,8 +36,11 @@ export {
   type ParamDecoratorOptions,
   type ParamMetadata,
   type ResponseSchemaMetadata,
+  type RouteOptions,
   type RouteMetadata,
   type ControllerMetadata,
+  type MiddlewareClass,
+  type OnModuleConfigure,
   // File upload types
   type FileUploadOptions,
   type FilesUploadOptions,
@@ -86,6 +89,8 @@ export {
   type OnModuleDestroy,
   type BeforeApplicationDestroy,
   type OnApplicationDestroy,
+  // Middleware
+  BaseMiddleware,
   // Lifecycle hooks helper functions
   hasOnModuleInit,
   hasOnApplicationInit,
@@ -100,6 +105,10 @@ export {
   // SSE helpers
   formatSseEvent,
   createSseStream,
+  // Server & SSE default constants
+  DEFAULT_IDLE_TIMEOUT,
+  DEFAULT_SSE_HEARTBEAT_MS,
+  DEFAULT_SSE_TIMEOUT,
 } from './module';
 
 // Application

package/src/module/controller.ts

@@ -9,6 +9,27 @@ import type { Context } from 'effect';
 import type { SyncLogger } from '@onebun/logger';
 import { HttpStatusCode } from '@onebun/requests';
 
+/**
+ * Default idle timeout for HTTP connections (in seconds).
+ * Bun.serve closes idle connections after this period.
+ * @defaultValue 120
+ */
+export const DEFAULT_IDLE_TIMEOUT = 120;
+
+/**
+ * Default heartbeat interval for SSE connections (in milliseconds).
+ * Sends a comment (`: heartbeat\n\n`) to keep the connection alive.
+ * @defaultValue 30000 (30 seconds)
+ */
+export const DEFAULT_SSE_HEARTBEAT_MS = 30_000;
+
+/**
+ * Default per-request idle timeout for SSE connections (in seconds).
+ * SSE connections are long-lived by nature, so they get a longer timeout.
+ * @defaultValue 600 (10 minutes)
+ */
+export const DEFAULT_SSE_TIMEOUT = 600;
+
 /**
  * Base controller class that can be extended to add common functionality
  */
@@ -189,8 +210,11 @@ export class Controller {
    * This method provides an alternative to the @Sse() decorator for creating
    * SSE responses programmatically.
    *
-   * @param source - Async iterable that yields SseEvent objects or raw data
-   * @param options - SSE options (heartbeat interval, etc.)
+   * @param source - Async iterable that yields SseEvent objects or raw data,
+   *   or a factory function that receives an AbortSignal and returns an async iterable.
+   *   The factory pattern is useful for SSE proxying -- pass the signal to `fetch()`
+   *   to automatically abort upstream connections when the client disconnects.
+   * @param options - SSE options (heartbeat interval, onAbort callback, etc.)
    * @returns A Response object with SSE content type
    *
    * @example Basic usage
@@ -206,20 +230,51 @@ export class Controller {
    * }
    * ```
    *
-   * @example With heartbeat
+   * @example With heartbeat and onAbort callback
    * ```typescript
    * @Get('/live')
    * live(): Response {
    *   const updates = this.dataService.getUpdateStream();
-   *   return this.sse(updates, { heartbeat: 15000 });
+   *   return this.sse(updates, {
+   *     heartbeat: 15000,
+   *     onAbort: () => this.dataService.unsubscribe(),
+   *   });
+   * }
+   * ```
+   *
+   * @example Factory function with AbortSignal (SSE proxy)
+   * ```typescript
+   * @Get('/proxy')
+   * proxy(): Response {
+   *   return this.sse((signal) => this.proxyUpstream(signal));
+   * }
+   *
+   * private async *proxyUpstream(signal: AbortSignal): SseGenerator {
+   *   const response = await fetch('https://api.example.com/events', { signal });
+   *   // parse and yield SSE events from upstream...
+   *   // When client disconnects -> signal aborted -> fetch aborted automatically
    * }
    * ```
    */
   protected sse(
-    source: AsyncIterable<SseEvent | unknown>,
+    source:
+      | AsyncIterable<SseEvent | unknown>
+      | ((signal: AbortSignal) => AsyncIterable<SseEvent | unknown>),
     options: SseOptions = {},
   ): Response {
-    const stream = createSseStream(source, options);
+    let iterable: AsyncIterable<SseEvent | unknown>;
+    let onCancel: (() => void) | undefined;
+
+    if (typeof source === 'function') {
+      // Factory pattern: create an AbortController and pass its signal to the factory
+      const ac = new AbortController();
+      iterable = source(ac.signal);
+      onCancel = () => ac.abort();
+    } else {
+      iterable = source;
+    }
+
+    const stream = createSseStream(iterable, { ...options, _onCancel: onCancel });
 
     return new Response(stream, {
       status: HttpStatusCode.OK,
@@ -309,21 +364,41 @@ export function formatSseEvent(event: SseEvent | unknown): string {
   return result;
 }
 
+/**
+ * Internal options for createSseStream, extending public SseOptions
+ * with private hooks used by controller.sse()
+ */
+interface CreateSseStreamOptions extends SseOptions {
+  /**
+   * Internal cancel hook used by controller.sse() to abort
+   * the AbortController for factory-pattern SSE sources.
+   * @internal
+   */
+  _onCancel?: () => void;
+}
+
 /**
  * Create a ReadableStream for SSE from an async iterable
  *
+ * Uses a manual async iterator so that `iterator.return()` can be called
+ * on stream cancellation, triggering the generator's `finally` blocks
+ * for proper cleanup (e.g., aborting upstream SSE connections).
+ *
  * @param source - Async iterable that yields events
- * @param options - SSE options
+ * @param options - SSE options (heartbeat, onAbort, etc.)
  * @returns ReadableStream for Response body
  */
 export function createSseStream(
   source: AsyncIterable<SseEvent | unknown>,
-  options: SseOptions = {},
+  options: CreateSseStreamOptions = {},
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder();
   let heartbeatTimer: Timer | null = null;
   let isCancelled = false;
 
+  // Obtain manual iterator handle so we can call return() on cancel
+  const iterator = source[Symbol.asyncIterator]();
+
   return new ReadableStream<Uint8Array>({
     async start(controller) {
       // Set up heartbeat timer if specified
@@ -340,11 +415,15 @@ export function createSseStream(
       }
 
       try {
-        for await (const event of source) {
+        while (true) {
           if (isCancelled) {
             break;
           }
-          const formatted = formatSseEvent(event);
+          const { value, done } = await iterator.next();
+          if (done || isCancelled) {
+            break;
+          }
+          const formatted = formatSseEvent(value);
           controller.enqueue(encoder.encode(formatted));
         }
       } catch (error) {
@@ -374,6 +453,13 @@ export function createSseStream(
         clearInterval(heartbeatTimer);
         heartbeatTimer = null;
       }
+      // Force-terminate the generator, triggering its finally blocks
+      // This enables cleanup on client disconnect (e.g., aborting upstream SSE)
+      iterator.return?.(undefined);
+      // Fire user-provided onAbort callback
+      options.onAbort?.();
+      // Fire internal cancel hook (used by controller.sse() factory pattern)
+      options._onCancel?.();
     },
   });
 }

package/src/module/index.ts

@@ -1,13 +1,14 @@
 /**
  * Module System
  *
- * Core module, controller, and service abstractions.
+ * Core module, controller, service, and middleware abstractions.
  */
 
 export * from './module';
 export * from './controller';
 // Re-export Controller as BaseController for backward compatibility
 export { Controller as BaseController } from './controller';
+export * from './middleware';
 export * from './service';
 export * from './config.service';
 export * from './config.interface';

package/src/module/lifecycle.ts

@@ -83,6 +83,11 @@ export interface OnApplicationDestroy {
   onApplicationDestroy(signal?: string): Promise<void> | void;
 }
 
+/**
+ * Interface for modules that configure middleware.
+ * Re-exported from types for convenience. Use the canonical import from types.ts.
+ */
+
 // =============================================================================
 // Helper functions for checking if an object implements lifecycle hooks
 // =============================================================================
@@ -147,6 +152,14 @@ export function hasOnApplicationDestroy(obj: unknown): obj is OnApplicationDestr
   );
 }
 
+/**
+ * Check if a class (constructor) has a configureMiddleware method on its prototype.
+ * Used to detect modules that implement OnModuleConfigure.
+ */
+export function hasConfigureMiddleware(cls: Function): boolean {
+  return typeof cls.prototype?.configureMiddleware === 'function';
+}
+
 // =============================================================================
 // Helper functions to call lifecycle hooks safely
 // =============================================================================

package/src/module/middleware.ts

@@ -0,0 +1,76 @@
+import type { IConfig, OneBunAppConfig } from './config.interface';
+import type { OneBunRequest, OneBunResponse } from '../types';
+
+import type { SyncLogger } from '@onebun/logger';
+
+/**
+ * Base class for all OneBun middleware.
+ *
+ * Extend this class to create middleware with access to the framework's
+ * logger (scoped to the middleware class name) and configuration.
+ * Constructor-based DI is fully supported — inject any service from
+ * the module's DI scope just like you would in a controller.
+ *
+ * Middleware is instantiated **once** at application startup and reused
+ * for every matching request.
+ *
+ * @example Simple middleware (no DI)
+ * ```typescript
+ * class LoggingMiddleware extends BaseMiddleware {
+ *   async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+ *     this.logger.info(`${req.method} ${new URL(req.url).pathname}`);
+ *     return next();
+ *   }
+ * }
+ * ```
+ *
+ * @example Middleware with DI
+ * ```typescript
+ * class AuthMiddleware extends BaseMiddleware {
+ *   constructor(private authService: AuthService) {
+ *     super();
+ *   }
+ *
+ *   async use(req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+ *     const secret = this.config.get('auth.jwtSecret');
+ *     const token = req.headers.get('Authorization');
+ *     if (!this.authService.verify(token, secret)) {
+ *       this.logger.warn('Authentication failed');
+ *       return new Response('Unauthorized', { status: 401 });
+ *     }
+ *     return next();
+ *   }
+ * }
+ * ```
+ */
+export abstract class BaseMiddleware {
+  /** Logger instance scoped to the middleware class name */
+  protected logger!: SyncLogger;
+
+  /** Configuration instance for accessing environment variables */
+  protected config!: IConfig<OneBunAppConfig>;
+
+  /**
+   * Initialize middleware with logger and config.
+   * Called by the framework after DI construction — do NOT call manually.
+   * @internal
+   */
+  initializeMiddleware(logger: SyncLogger, config: IConfig<OneBunAppConfig>): void {
+    const className = this.constructor.name;
+    this.logger = logger.child({ className });
+    this.config = config;
+    this.logger.debug(`Middleware ${className} initialized`);
+  }
+
+  /**
+   * The middleware handler.
+   *
+   * @param req - The incoming request (OneBunRequest with `.cookies`, `.params`, etc.)
+   * @param next - Call to invoke the next middleware or the route handler
+   * @returns A response — either from `next()` or a short-circuit response
+   */
+  abstract use(
+    req: OneBunRequest,
+    next: () => Promise<OneBunResponse>,
+  ): Promise<OneBunResponse> | OneBunResponse;
+}

package/src/module/module.test.ts

@@ -16,9 +16,19 @@ import {
   Layer,
 } from 'effect';
 
-import { Module } from '../decorators/decorators';
+import type {
+  MiddlewareClass,
+  OneBunRequest,
+  OneBunResponse,
+  OnModuleConfigure,
+} from '../types';
+
+
+import { Controller as CtrlDeco, Module } from '../decorators/decorators';
 import { makeMockLoggerLayer } from '../testing/test-utils';
 
+import { Controller as CtrlBase } from './controller';
+import { BaseMiddleware } from './middleware';
 import { OneBunModule } from './module';
 import { Service } from './service';
 
@@ -1275,4 +1285,131 @@ describe('OneBunModule', () => {
       expect(controller.getLabel()).toBe('shared');
     });
   });
+
+  describe('Module-level middleware (OnModuleConfigure)', () => {
+    class Mw1 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
+
+    class Mw2 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
+
+    class Mw3 extends BaseMiddleware {
+      async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
+        return await next(); 
+      }
+    }
+
+    test('should collect middleware from module implementing OnModuleConfigure', async () => {
+      @CtrlDeco('/test')
+      class TestController extends CtrlBase {}
+
+      @Module({ controllers: [TestController] })
+      class TestModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw1, Mw2];
+        }
+      }
+
+      const module = new OneBunModule(TestModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const middleware = module.getModuleMiddleware(TestController);
+      expect(middleware).toHaveLength(2);
+      // Resolved middleware are bound use() functions
+      expect(typeof middleware[0]).toBe('function');
+      expect(typeof middleware[1]).toBe('function');
+    });
+
+    test('should return empty middleware for modules without OnModuleConfigure', async () => {
+      @CtrlDeco('/test')
+      class TestController extends CtrlBase {}
+
+      @Module({ controllers: [TestController] })
+      class PlainModule {}
+
+      const module = new OneBunModule(PlainModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      const middleware = module.getModuleMiddleware(TestController);
+      expect(middleware).toHaveLength(0);
+    });
+
+    test('should accumulate middleware from parent to child modules', async () => {
+      @CtrlDeco('/child')
+      class ChildController extends CtrlBase {}
+
+      @Module({ controllers: [ChildController] })
+      class ChildModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw2];
+        }
+      }
+
+      @CtrlDeco('/root')
+      class RootController extends CtrlBase {}
+
+      @Module({ imports: [ChildModule], controllers: [RootController] })
+      class RootModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw1];
+        }
+      }
+
+      const module = new OneBunModule(RootModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      // ChildController should have accumulated: [Mw1 (root), Mw2 (child)]
+      const childMw = module.getModuleMiddleware(ChildController);
+      expect(childMw).toHaveLength(2);
+      expect(typeof childMw[0]).toBe('function');
+      expect(typeof childMw[1]).toBe('function');
+
+      // RootController should have only root middleware: [Mw1]
+      const rootMw = module.getModuleMiddleware(RootController);
+      expect(rootMw).toHaveLength(1);
+      expect(typeof rootMw[0]).toBe('function');
+    });
+
+    test('should handle deeply nested module middleware', async () => {
+      @CtrlDeco('/deep')
+      class DeepController extends CtrlBase {}
+
+      @Module({ controllers: [DeepController] })
+      class DeepModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw3];
+        }
+      }
+
+      @Module({ imports: [DeepModule] })
+      class MiddleModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw2];
+        }
+      }
+
+      @Module({ imports: [MiddleModule] })
+      class TopModule implements OnModuleConfigure {
+        configureMiddleware(): MiddlewareClass[] {
+          return [Mw1];
+        }
+      }
+
+      const module = new OneBunModule(TopModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      // DeepController should get: [Mw1 (top), Mw2 (middle), Mw3 (deep)]
+      const middleware = module.getModuleMiddleware(DeepController);
+      expect(middleware).toHaveLength(3);
+      expect(typeof middleware[0]).toBe('function');
+      expect(typeof middleware[1]).toBe('function');
+      expect(typeof middleware[2]).toBe('function');
+    });
+  });
 });

package/src/module/module.ts

@@ -35,7 +35,9 @@ import {
   hasOnModuleDestroy,
   hasBeforeApplicationDestroy,
   hasOnApplicationDestroy,
+  hasConfigureMiddleware,
 } from './lifecycle';
+import { BaseMiddleware } from './middleware';
 import {
   BaseService,
   getServiceMetadata,
@@ -83,10 +85,34 @@ export class OneBunModule implements ModuleInstance {
   private logger: SyncLogger;
   private config: IConfig<OneBunAppConfig>;
 
+  /**
+   * Middleware class constructors defined by this module via OnModuleConfigure.configureMiddleware()
+   */
+  private ownMiddlewareClasses: Function[] = [];
+
+  /**
+   * Accumulated middleware class constructors from ancestor modules (parent → child).
+   * Does NOT include this module's own middleware.
+   */
+  private ancestorMiddlewareClasses: Function[] = [];
+
+  /**
+   * Resolved middleware functions (bound use() methods) for this module's own middleware.
+   * Populated during setup() after services are created.
+   */
+  private resolvedOwnMiddleware: Function[] = [];
+
+  /**
+   * Resolved middleware functions from ancestor modules.
+   * Populated during setup() after services are created.
+   */
+  private resolvedAncestorMiddleware: Function[] = [];
+
   constructor(
     private moduleClass: Function,
     private loggerLayer?: Layer.Layer<never, never, unknown>,
     config?: IConfig<OneBunAppConfig>,
+    ancestorMiddleware?: Function[],
   ) {
     // Initialize logger with module class name as context
     const effectLogger = Effect.runSync(
@@ -99,6 +125,23 @@ export class OneBunModule implements ModuleInstance {
     ) as Logger;
     this.logger = createSyncLogger(effectLogger);
     this.config = config ?? new NotInitializedConfig();
+    this.ancestorMiddlewareClasses = ancestorMiddleware ?? [];
+
+    // Read module-level middleware from OnModuleConfigure interface
+    if (hasConfigureMiddleware(moduleClass)) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const moduleInstance = new (moduleClass as new () => any)();
+        this.ownMiddlewareClasses = moduleInstance.configureMiddleware();
+        this.logger.debug(
+          `Module ${moduleClass.name} configured ${this.ownMiddlewareClasses.length} middleware class(es)`,
+        );
+      } catch (error) {
+        this.logger.error(
+          `Failed to call configureMiddleware() on module ${moduleClass.name}: ${error}`,
+        );
+      }
+    }
 
     this.logger.debug(`Initializing OneBunModule for ${moduleClass.name}`);
     const { layer, controllers } = this.initModule();
@@ -166,8 +209,9 @@ export class OneBunModule implements ModuleInstance {
           continue;
         }
 
-        // Pass the logger layer and config to child modules
-        const childModule = new OneBunModule(importModule, this.loggerLayer, this.config);
+        // Pass the logger layer, config, and accumulated middleware class refs to child modules
+        const accumulatedMiddleware = [...this.ancestorMiddlewareClasses, ...this.ownMiddlewareClasses];
+        const childModule = new OneBunModule(importModule, this.loggerLayer, this.config, accumulatedMiddleware);
         this.childModules.push(childModule);
 
         // Merge layers
@@ -392,6 +436,57 @@ export class OneBunModule implements ModuleInstance {
     return exported;
   }
 
+  /**
+   * Instantiate middleware classes with DI from this module's service scope.
+   * Resolves constructor dependencies, calls initializeMiddleware(), and
+   * returns bound use() functions ready for the execution pipeline.
+   */
+  resolveMiddleware(classes: Function[]): Function[] {
+    return classes.map((cls) => {
+      // Resolve constructor dependencies (same logic as for controllers)
+      const paramTypes = getConstructorParamTypes(cls);
+      const deps: unknown[] = [];
+
+      if (paramTypes && paramTypes.length > 0) {
+        for (const paramType of paramTypes) {
+          const dep = this.resolveDependencyByType(paramType);
+          if (dep) {
+            deps.push(dep);
+          } else {
+            this.logger.warn(
+              `Could not resolve dependency ${paramType.name} for middleware ${cls.name}`,
+            );
+          }
+        }
+      }
+
+      const middlewareConstructor = cls as new (...args: unknown[]) => BaseMiddleware;
+      const instance = new middlewareConstructor(...deps);
+      instance.initializeMiddleware(this.logger, this.config);
+
+      return instance.use.bind(instance);
+    });
+  }
+
+  /**
+   * Resolve own and ancestor middleware classes into bound functions.
+   * Recursively resolves middleware for all child modules too.
+   * Must be called after services are created (DI scope is complete).
+   * @internal
+   */
+  private resolveModuleMiddleware(): void {
+    if (this.ancestorMiddlewareClasses.length > 0) {
+      this.resolvedAncestorMiddleware = this.resolveMiddleware(this.ancestorMiddlewareClasses);
+    }
+    if (this.ownMiddlewareClasses.length > 0) {
+      this.resolvedOwnMiddleware = this.resolveMiddleware(this.ownMiddlewareClasses);
+    }
+    // Recursively resolve for all descendant modules
+    for (const childModule of this.childModules) {
+      childModule.resolveModuleMiddleware();
+    }
+  }
+
   /**
    * Create controller instances and inject services
    */
@@ -550,6 +645,13 @@ export class OneBunModule implements ModuleInstance {
           discard: true,
         }),
       ),
+      // Resolve module-level middleware with DI (services are now available)
+      // resolveModuleMiddleware is recursive and handles all descendants
+      Effect.flatMap(() =>
+        Effect.sync(() => {
+          this.resolveModuleMiddleware();
+        }),
+      ),
       // Create controller instances in child modules first, then this module (each uses its own DI scope)
       Effect.flatMap(() =>
         Effect.forEach(this.childModules, (childModule) => childModule.createControllerInstances(), {
@@ -808,6 +910,29 @@ export class OneBunModule implements ModuleInstance {
     return instance;
   }
 
+  /**
+   * Get accumulated module-level middleware (resolved bound functions)
+   * for a controller class. Returns [...ancestorResolved, ...ownResolved]
+   * for controllers that belong to this module, or delegates to child modules.
+   */
+  getModuleMiddleware(controllerClass: Function): Function[] {
+    // Check if this module directly owns the controller
+    if (this.controllers.includes(controllerClass)) {
+      return [...this.resolvedAncestorMiddleware, ...this.resolvedOwnMiddleware];
+    }
+
+    // Delegate to child modules
+    for (const childModule of this.childModules) {
+      const middleware = childModule.getModuleMiddleware(controllerClass);
+      if (middleware.length > 0) {
+        return middleware;
+      }
+    }
+
+    // Controller not found in this module tree (return empty — no module middleware)
+    return [];
+  }
+
   /**
    * Get all controller instances from this module and child modules (recursive).
    */