@onebun/core 0.2.7 → 0.2.9

package/src/http-guards/http-guards.ts

@@ -0,0 +1,173 @@
+/**
+ * HTTP Guards
+ *
+ * Guards for authorizing HTTP requests before they reach the route handler.
+ * Apply with `@UseGuards()` on controllers or individual routes.
+ */
+
+import type {
+  HttpExecutionContext,
+  HttpGuard,
+  OneBunRequest,
+} from '../types';
+
+// ============================================================================
+// Execution Context Implementation
+// ============================================================================
+
+/**
+ * Implementation of HttpExecutionContext
+ */
+export class HttpExecutionContextImpl implements HttpExecutionContext {
+  constructor(
+    private readonly request: OneBunRequest,
+    private readonly handlerName: string,
+    private readonly controllerName: string,
+  ) {}
+
+  getRequest(): OneBunRequest {
+    return this.request;
+  }
+
+  getHandler(): string {
+    return this.handlerName;
+  }
+
+  getController(): string {
+    return this.controllerName;
+  }
+}
+
+// ============================================================================
+// Guard Execution Helper
+// ============================================================================
+
+/**
+ * Execute a list of HTTP guards sequentially.
+ * Returns false as soon as any guard denies access (short-circuit).
+ *
+ * @param guards - Array of guard class constructors or instances
+ * @param context - Execution context for this request
+ * @returns Whether all guards passed
+ */
+export async function executeHttpGuards(
+  guards: (Function | HttpGuard)[],
+  context: HttpExecutionContext,
+): Promise<boolean> {
+  for (const guard of guards) {
+    let guardInstance: HttpGuard;
+
+    if (typeof guard === 'function') {
+      guardInstance = new (guard as new () => HttpGuard)();
+    } else {
+      guardInstance = guard;
+    }
+
+    const result = await guardInstance.canActivate(context);
+    if (!result) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Create a custom HTTP guard from a plain function.
+ * Returns a class constructor compatible with `@UseGuards()`.
+ *
+ * @param fn - Guard function receiving the execution context
+ * @returns Guard class constructor
+ *
+ * @example
+ * ```typescript
+ * const ApiKeyGuard = createHttpGuard((ctx) => {
+ *   return ctx.getRequest().headers.get('x-api-key') === process.env.API_KEY;
+ * });
+ *
+ * @UseGuards(ApiKeyGuard)
+ * @Get('/protected')
+ * getData() { ... }
+ * ```
+ */
+export function createHttpGuard(
+  fn: (context: HttpExecutionContext) => boolean | Promise<boolean>,
+): new () => HttpGuard {
+  return class implements HttpGuard {
+    canActivate(context: HttpExecutionContext): boolean | Promise<boolean> {
+      return fn(context);
+    }
+  };
+}
+
+// ============================================================================
+// Built-in Guards
+// ============================================================================
+
+/**
+ * Guard that requires a valid Bearer token in the Authorization header.
+ * Does NOT validate the token — only checks that the header is present.
+ * Combine with a custom middleware or guard to validate the token itself.
+ *
+ * @example
+ * ```typescript
+ * @UseGuards(AuthGuard)
+ * @Get('/profile')
+ * getProfile() { ... }
+ * ```
+ */
+export class AuthGuard implements HttpGuard {
+  canActivate(context: HttpExecutionContext): boolean {
+    const auth = context.getRequest().headers.get('authorization');
+
+    return auth !== null && auth.startsWith('Bearer ');
+  }
+}
+
+/**
+ * Default roles extractor — reads comma-separated roles from the `x-user-roles` header.
+ * Set this header from your auth middleware after validating the token.
+ */
+function defaultRolesExtractor(ctx: HttpExecutionContext): string[] {
+  const rolesHeader = ctx.getRequest().headers.get('x-user-roles');
+
+  return rolesHeader ? rolesHeader.split(',').map((r) => r.trim()) : [];
+}
+
+/**
+ * Guard that requires all specified roles to be present on the request.
+ * By default reads roles from the `x-user-roles` header (comma-separated).
+ * Provide a custom `rolesExtractor` to read roles from a different source
+ * (e.g. a JWT claim decoded by a preceding auth middleware).
+ *
+ * @example
+ * ```typescript
+ * // All specified roles must be present
+ * @UseGuards(new RolesGuard(['admin', 'moderator']))
+ * @Delete('/users/:id')
+ * deleteUser() { ... }
+ *
+ * // Custom roles extractor
+ * @UseGuards(new RolesGuard(['admin'], (ctx) => ctx.getRequest().headers.get('x-roles')?.split('|') ?? []))
+ * @Get('/admin')
+ * adminPanel() { ... }
+ * ```
+ */
+export class RolesGuard implements HttpGuard {
+  private readonly roles: string[];
+  private readonly rolesExtractor: (ctx: HttpExecutionContext) => string[];
+
+  constructor(
+    roles: string[],
+    rolesExtractor: (ctx: HttpExecutionContext) => string[] = defaultRolesExtractor,
+  ) {
+    this.roles = roles;
+    this.rolesExtractor = rolesExtractor;
+  }
+
+  canActivate(context: HttpExecutionContext): boolean {
+    const userRoles = this.rolesExtractor(context);
+
+    return this.roles.every((role) => userRoles.includes(role));
+  }
+}

package/src/http-guards/index.ts

@@ -0,0 +1 @@
+export * from './http-guards';

package/src/index.ts

@@ -132,3 +132,12 @@ export * from './validation';
 
 // Testing Utilities
 export * from './testing';
+
+// HTTP Guards
+export * from './http-guards';
+
+// Exception Filters
+export * from './exception-filters';
+
+// Security Middleware
+export * from './security';

package/src/module/module.test.ts

@@ -1422,6 +1422,84 @@ describe('OneBunModule', () => {
       expect(depValueInInit).not.toBeNull();
       expect(depValueInInit as unknown as number).toBe(8080);
     });
+
+    test('should call onModuleInit for services and controllers in deeply nested module tree', async () => {
+      const initLog: string[] = [];
+
+      @Service()
+      class GrandchildService {
+        async onModuleInit(): Promise<void> {
+          initLog.push('grandchild-service');
+        }
+      }
+
+      @CtrlDeco('/grandchild')
+      class GrandchildController extends CtrlBase {
+        async onModuleInit(): Promise<void> {
+          initLog.push('grandchild-controller');
+        }
+      }
+
+      @Module({
+        providers: [GrandchildService],
+        controllers: [GrandchildController],
+      })
+      class GrandchildModule {}
+
+      @Service()
+      class ChildService {
+        async onModuleInit(): Promise<void> {
+          initLog.push('child-service');
+        }
+      }
+
+      @CtrlDeco('/child')
+      class ChildController extends CtrlBase {
+        async onModuleInit(): Promise<void> {
+          initLog.push('child-controller');
+        }
+      }
+
+      @Module({
+        imports: [GrandchildModule],
+        providers: [ChildService],
+        controllers: [ChildController],
+      })
+      class ChildModule {}
+
+      @Service()
+      class RootService {
+        async onModuleInit(): Promise<void> {
+          initLog.push('root-service');
+        }
+      }
+
+      @CtrlDeco('/root')
+      class RootController extends CtrlBase {
+        async onModuleInit(): Promise<void> {
+          initLog.push('root-controller');
+        }
+      }
+
+      @Module({
+        imports: [ChildModule],
+        providers: [RootService],
+        controllers: [RootController],
+      })
+      class RootModule {}
+
+      const module = new ModuleClass(RootModule, mockLoggerLayer);
+      await Effect.runPromise(module.setup() as Effect.Effect<unknown, never, never>);
+
+      // All services and controllers across all levels must have onModuleInit called
+      expect(initLog).toContain('grandchild-service');
+      expect(initLog).toContain('grandchild-controller');
+      expect(initLog).toContain('child-service');
+      expect(initLog).toContain('child-controller');
+      expect(initLog).toContain('root-service');
+      expect(initLog).toContain('root-controller');
+      expect(initLog.length).toBe(6);
+    });
   });
 
   describe('Module DI scoping (exports only for cross-module)', () => {

package/src/module/module.ts

@@ -72,6 +72,16 @@ export function clearGlobalServicesRegistry(): void {
   processedGlobalModules.clear();
 }
 
+/**
+ * Register a service instance in the global services registry so it is available
+ * in all modules (including child modules) via PHASE 0 of module initialization.
+ * Must be called BEFORE creating the root module.
+ * @internal
+ */
+export function registerGlobalService<T>(tag: Context.Tag<unknown, T>, instance: T): void {
+  globalServicesRegistry.set(tag as Context.Tag<unknown, unknown>, instance);
+}
+
 /**
  * Get all global services (useful for debugging)
  * @internal
@@ -627,7 +637,21 @@ export class OneBunModule implements ModuleInstance {
       }
     }
 
-    // Find service instance that matches the type
+    // Try to find by Effect Context.Tag first.
+    // This is the primary mechanism and also makes test overrides work:
+    // TestingModule.overrideProvider(MyService).useValue(mock) registers the mock
+    // under MyService's tag, so it is found here even if mock is not instanceof MyService.
+    try {
+      const tag = getServiceTag(type as new (...args: unknown[]) => unknown);
+      const byTag = this.serviceInstances.get(tag as Context.Tag<unknown, unknown>);
+      if (byTag !== undefined) {
+        return byTag;
+      }
+    } catch {
+      // Not a @Service()-decorated class — fall through to instanceof check below
+    }
+
+    // Fallback: find service instance that matches the type by reference equality or inheritance
     const serviceInstance = Array.from(this.serviceInstances.values()).find((instance) => {
       if (!instance) {
         return false;
@@ -689,11 +713,27 @@ export class OneBunModule implements ModuleInstance {
   /**
    * Setup the module and its dependencies
    */
+  /**
+   * Collect all descendant modules in depth-first order (leaves first).
+   * This ensures that deeply nested modules are initialized before their parents.
+   */
+  private collectDescendantModules(): OneBunModule[] {
+    const result: OneBunModule[] = [];
+    for (const child of this.childModules) {
+      result.push(...child.collectDescendantModules());
+      result.push(child);
+    }
+
+    return result;
+  }
+
   setup(): Effect.Effect<unknown, never, void> {
+    const allDescendants = this.collectDescendantModules();
+
     return this.callServicesOnModuleInit().pipe(
-      // Also run onModuleInit for child modules' services
+      // Run onModuleInit for all descendant modules' services (depth-first)
       Effect.flatMap(() =>
-        Effect.forEach(this.childModules, (childModule) => childModule.callServicesOnModuleInit(), {
+        Effect.forEach(allDescendants, (mod) => mod.callServicesOnModuleInit(), {
           discard: true,
         }),
       ),
@@ -704,18 +744,18 @@ export class OneBunModule implements ModuleInstance {
           this.resolveModuleMiddleware();
         }),
       ),
-      // Create controller instances in child modules first, then this module (each uses its own DI scope)
+      // Create controller instances in all descendant modules first, then this module
       Effect.flatMap(() =>
-        Effect.forEach(this.childModules, (childModule) => childModule.createControllerInstances(), {
+        Effect.forEach(allDescendants, (mod) => mod.createControllerInstances(), {
           discard: true,
         }),
       ),
       Effect.flatMap(() => this.createControllerInstances()),
       // Then call onModuleInit for controllers
       Effect.flatMap(() => this.callControllersOnModuleInit()),
-      // Also run onModuleInit for child modules' controllers
+      // Run onModuleInit for all descendant modules' controllers
       Effect.flatMap(() =>
-        Effect.forEach(this.childModules, (childModule) => childModule.callControllersOnModuleInit(), {
+        Effect.forEach(allDescendants, (mod) => mod.callControllersOnModuleInit(), {
           discard: true,
         }),
       ),

package/src/queue/docs-examples.test.ts

@@ -435,7 +435,7 @@ describe('Custom adapter NATS JetStream (docs/api/queue.md)', () => {
     class NatsJetStreamAdapter implements QueueAdapter {
       readonly name = 'nats-jetstream';
       readonly type = 'jetstream';
-      constructor(private opts: { servers: string; stream?: string }) {}
+      constructor(private opts: { servers: string; streams?: Array<{ name: string; subjects: string[] }> }) {}
       async connect(): Promise<void> {}
       async disconnect(): Promise<void> {}
       isConnected(): boolean {
@@ -473,7 +473,7 @@ describe('Custom adapter NATS JetStream (docs/api/queue.md)', () => {
 
     const adapter = new NatsJetStreamAdapter({
       servers: 'nats://localhost:4222',
-      stream: 'EVENTS',
+      streams: [{ name: 'EVENTS', subjects: ['events.>'] }],
     });
     await adapter.connect();
     expect(adapter.name).toBe('nats-jetstream');

package/src/security/cors-middleware.ts

@@ -0,0 +1,212 @@
+import type { OneBunRequest, OneBunResponse } from '../types';
+
+import { BaseMiddleware } from '../module/middleware';
+
+/**
+ * CORS (Cross-Origin Resource Sharing) configuration options.
+ * Passed via `ApplicationOptions.cors`.
+ */
+export interface CorsOptions {
+  /**
+   * Allowed origin(s).
+   * - `'*'` — allow any origin
+   * - `string` — exact match
+   * - `RegExp` — regex match
+   * - `string[]` / `RegExp[]` — list of allowed origins
+   * - `(origin: string) => boolean` — custom predicate
+   * @defaultValue '*'
+   */
+  origin?: string | RegExp | Array<string | RegExp> | ((origin: string) => boolean);
+
+  /**
+   * Allowed HTTP methods.
+   * @defaultValue ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS']
+   */
+  methods?: string[];
+
+  /**
+   * Allowed request headers.
+   * @defaultValue ['Content-Type', 'Authorization']
+   */
+  allowedHeaders?: string[];
+
+  /**
+   * Headers to expose to the browser.
+   */
+  exposedHeaders?: string[];
+
+  /**
+   * Allow credentials (cookies, Authorization header).
+   * @defaultValue false
+   */
+  credentials?: boolean;
+
+  /**
+   * Preflight cache duration in seconds.
+   * @defaultValue 86400 (24 hours)
+   */
+  maxAge?: number;
+
+  /**
+   * Whether to pass the CORS preflight request to the next handler.
+   * When `false` (default) preflight requests are handled by the middleware
+   * and never reach route handlers.
+   * @defaultValue false
+   */
+  preflightContinue?: boolean;
+}
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'];
+const DEFAULT_ALLOWED_HEADERS = ['Content-Type', 'Authorization'];
+const DEFAULT_MAX_AGE = 86400;
+const NO_CONTENT = 204;
+
+/**
+ * Resolves whether the given `origin` is allowed by the CORS configuration.
+ */
+function isOriginAllowed(
+  origin: string,
+  allowed: NonNullable<CorsOptions['origin']>,
+): boolean {
+  if (allowed === '*') {
+    return true;
+  }
+
+  if (typeof allowed === 'string') {
+    return origin === allowed;
+  }
+
+  if (allowed instanceof RegExp) {
+    return allowed.test(origin);
+  }
+
+  if (typeof allowed === 'function') {
+    return allowed(origin);
+  }
+
+  return (allowed as Array<string | RegExp>).some((item) =>
+    typeof item === 'string' ? origin === item : item.test(origin),
+  );
+}
+
+/**
+ * Built-in CORS middleware.
+ *
+ * Handles preflight `OPTIONS` requests and sets appropriate CORS response
+ * headers for all other requests. Configure once via `ApplicationOptions.cors`
+ * and the framework will instantiate this middleware automatically.
+ *
+ * @example
+ * ```typescript
+ * const app = new OneBunApplication(AppModule, {
+ *   cors: {
+ *     origin: 'https://my-frontend.example.com',
+ *     credentials: true,
+ *   },
+ * });
+ * ```
+ *
+ * When using manually (e.g. from `ApplicationOptions.middleware`):
+ * ```typescript
+ * const app = new OneBunApplication(AppModule, {
+ *   middleware: [CorsMiddleware.configure({ origin: /example\.com$/ })],
+ * });
+ * ```
+ */
+export class CorsMiddleware extends BaseMiddleware {
+  private readonly options: Required<
+    Pick<CorsOptions, 'methods' | 'allowedHeaders' | 'maxAge' | 'credentials' | 'preflightContinue'>
+  > &
+    Pick<CorsOptions, 'origin' | 'exposedHeaders'>;
+
+  /**
+   * Create a pre-configured CorsMiddleware class with the given options.
+   * Returns a constructor — pass the result directly to `ApplicationOptions.middleware`.
+   *
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, {
+   *   middleware: [CorsMiddleware.configure({ origin: 'https://example.com' })],
+   * });
+   * ```
+   */
+  static configure(options: CorsOptions = {}): typeof CorsMiddleware {
+    class ConfiguredCorsMiddleware extends CorsMiddleware {
+      constructor() {
+        super(options);
+      }
+    }
+
+    return ConfiguredCorsMiddleware;
+  }
+
+  constructor(options: CorsOptions = {}) {
+    super();
+
+    this.options = {
+      origin: options.origin ?? '*',
+      methods: options.methods ?? DEFAULT_METHODS,
+      allowedHeaders: options.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS,
+      exposedHeaders: options.exposedHeaders,
+      credentials: options.credentials ?? false,
+      maxAge: options.maxAge ?? DEFAULT_MAX_AGE,
+      preflightContinue: options.preflightContinue ?? false,
+    };
+  }
+
+  async use(req: OneBunRequest, next: () => Promise<OneBunResponse>): Promise<OneBunResponse> {
+    const origin = req.headers.get('origin') ?? '';
+    const headers = new Headers();
+
+    // Determine the effective origin for the Access-Control-Allow-Origin header
+    const { origin: allowedOrigin } = this.options;
+    const allowAll = allowedOrigin === '*' && !this.options.credentials;
+
+    if (allowAll) {
+      headers.set('Access-Control-Allow-Origin', '*');
+    } else if (origin && isOriginAllowed(origin, allowedOrigin ?? '*')) {
+      headers.set('Access-Control-Allow-Origin', origin);
+      headers.append('Vary', 'Origin');
+    } else if (!origin) {
+      // Non-browser request (no Origin header) — set wildcard if configured
+      if (allowedOrigin === '*') {
+        headers.set('Access-Control-Allow-Origin', '*');
+      }
+    }
+
+    if (this.options.credentials) {
+      headers.set('Access-Control-Allow-Credentials', 'true');
+    }
+
+    if (this.options.exposedHeaders && this.options.exposedHeaders.length > 0) {
+      headers.set('Access-Control-Expose-Headers', this.options.exposedHeaders.join(', '));
+    }
+
+    // Handle preflight OPTIONS request
+    if (req.method === 'OPTIONS') {
+      headers.set('Access-Control-Allow-Methods', this.options.methods.join(', '));
+      headers.set('Access-Control-Allow-Headers', this.options.allowedHeaders.join(', '));
+      headers.set('Access-Control-Max-Age', String(this.options.maxAge));
+
+      if (this.options.preflightContinue) {
+        const response = await next();
+        // Copy CORS headers onto the response from next()
+        for (const [key, value] of headers.entries()) {
+          response.headers.set(key, value);
+        }
+
+        return response;
+      }
+
+      return new Response(null, { status: NO_CONTENT, headers });
+    }
+
+    // For non-OPTIONS requests — let the handler run, then attach CORS headers
+    const response = await next();
+    for (const [key, value] of headers.entries()) {
+      response.headers.set(key, value);
+    }
+
+    return response;
+  }
+}

package/src/security/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Security Middleware
+ *
+ * Built-in middleware for common security concerns: CORS, rate limiting,
+ * and HTTP security headers.
+ */
+
+export { CorsMiddleware, type CorsOptions } from './cors-middleware';
+export {
+  RateLimitMiddleware,
+  MemoryRateLimitStore,
+  RedisRateLimitStore,
+  type RateLimitOptions,
+  type RateLimitStore,
+} from './rate-limit-middleware';
+export {
+  SecurityHeadersMiddleware,
+  type SecurityHeadersOptions,
+} from './security-headers-middleware';