@onebun/core 0.2.6 → 0.2.8

package/src/exception-filters/exception-filters.ts

@@ -0,0 +1,129 @@
+/**
+ * Exception Filters
+ *
+ * Intercept and transform errors thrown by route handlers.
+ * Apply with `@UseFilters()` on controllers or individual routes,
+ * or globally via `ApplicationOptions.filters`.
+ */
+
+import type { HttpExecutionContext, OneBunResponse } from '../types';
+
+import {
+  createErrorResponse,
+  HttpStatusCode,
+  OneBunBaseError,
+} from '@onebun/requests';
+
+import { HttpException } from './http-exception';
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * Exception Filter interface — implement to handle errors thrown by route handlers.
+ *
+ * @example
+ * ```typescript
+ * class HttpExceptionFilter implements ExceptionFilter {
+ *   catch(error: unknown, ctx: HttpExecutionContext): Response {
+ *     const status = error instanceof OneBunBaseError ? error.code : 500;
+ *     return new Response(JSON.stringify({ message: String(error) }), {
+ *       status,
+ *       headers: { 'Content-Type': 'application/json' },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export interface ExceptionFilter {
+  catch(error: unknown, context: HttpExecutionContext): OneBunResponse | Promise<OneBunResponse>;
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+/**
+ * Create a custom exception filter from a plain function.
+ *
+ * @param fn - Filter function receiving the error and execution context
+ * @returns An ExceptionFilter instance
+ *
+ * @example
+ * ```typescript
+ * const logAndForwardFilter = createExceptionFilter((error, ctx) => {
+ *   console.error(`[${ctx.getController()}#${ctx.getHandler()}]`, error);
+ *   return new Response('Internal Error', { status: 500 });
+ * });
+ *
+ * @UseFilters(logAndForwardFilter)
+ * @Get('/risky')
+ * riskyRoute() { ... }
+ * ```
+ */
+export function createExceptionFilter(
+  fn: (error: unknown, context: HttpExecutionContext) => OneBunResponse | Promise<OneBunResponse>,
+): ExceptionFilter {
+  return { catch: fn };
+}
+
+// ============================================================================
+// Default filter (wraps existing error-handling logic)
+// ============================================================================
+
+/**
+ * Default exception filter — mirrors the built-in error handling behaviour.
+ * - `OneBunBaseError` instances are serialised with their own `toErrorResponse()`.
+ * - Every other error is converted to a generic 500 response.
+ * All responses use HTTP 200 with the standardised `ApiResponse` envelope,
+ * consistent with the rest of the framework.
+ */
+export const defaultExceptionFilter: ExceptionFilter = {
+  catch(error: unknown): OneBunResponse {
+    if (error instanceof HttpException) {
+      const errorResponse = createErrorResponse(
+        error.message,
+        error.statusCode,
+        error.message,
+      );
+
+      return new Response(JSON.stringify(errorResponse), {
+        status: error.statusCode,
+        headers: {
+          // eslint-disable-next-line @typescript-eslint/naming-convention
+          'Content-Type': 'application/json',
+        },
+      });
+    }
+
+    if (error instanceof OneBunBaseError) {
+      return new Response(JSON.stringify(error.toErrorResponse()), {
+        status: HttpStatusCode.OK,
+        headers: {
+          // eslint-disable-next-line @typescript-eslint/naming-convention
+          'Content-Type': 'application/json',
+        },
+      });
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    const code =
+      error instanceof Error && 'code' in error
+        ? Number((error as { code: unknown }).code)
+        : HttpStatusCode.INTERNAL_SERVER_ERROR;
+
+    const errorResponse = createErrorResponse(message, code, message, undefined, {
+      originalErrorName: error instanceof Error ? error.name : 'UnknownError',
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+
+    return new Response(JSON.stringify(errorResponse), {
+      status: HttpStatusCode.OK,
+      headers: {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        'Content-Type': 'application/json',
+      },
+    });
+  },
+};

package/src/exception-filters/http-exception.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP exception that carries a status code.
+ *
+ * Throw from route handlers, guards, or middleware to return
+ * a specific HTTP status. The default exception filter converts
+ * these into JSON responses with the matching status code.
+ *
+ * @example
+ * ```typescript
+ * throw new HttpException(404, 'User not found');
+ * // → HTTP 404 { success: false, error: "User not found", ... }
+ * ```
+ */
+export class HttpException extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'HttpException';
+  }
+}

package/src/exception-filters/index.ts

@@ -0,0 +1,2 @@
+export * from './exception-filters';
+export * from './http-exception';

package/src/file/onebun-file.ts

@@ -1,3 +1,7 @@
+import { HttpStatusCode } from '@onebun/requests';
+
+import { HttpException } from '../exception-filters/http-exception';
+
 /**
  * OneBunFile - Unified file wrapper for file uploads
  *
@@ -287,7 +291,8 @@ export function validateFile(
 
   // Validate file size
   if (options.maxSize !== undefined && file.size > options.maxSize) {
-    throw new Error(
+    throw new HttpException(
+      HttpStatusCode.BAD_REQUEST,
       `${prefix} exceeds maximum size. Got ${file.size} bytes, max is ${options.maxSize} bytes`,
     );
   }
@@ -296,7 +301,8 @@ export function validateFile(
   if (options.mimeTypes && options.mimeTypes.length > 0) {
     const matches = options.mimeTypes.some((pattern) => matchMimeType(file.type, pattern));
     if (!matches) {
-      throw new Error(
+      throw new HttpException(
+        HttpStatusCode.BAD_REQUEST,
         `${prefix} has invalid MIME type "${file.type}". Allowed: ${options.mimeTypes.join(', ')}`,
       );
     }

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

@@ -0,0 +1,230 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'bun:test';
+
+import type {
+  HttpExecutionContext,
+  HttpGuard,
+  OneBunRequest,
+} from '../types';
+
+import {
+  AuthGuard,
+  createHttpGuard,
+  executeHttpGuards,
+  HttpExecutionContextImpl,
+  RolesGuard,
+} from './http-guards';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeRequest(headers?: Headers): OneBunRequest {
+  return new Request('http://localhost/test', { headers }) as unknown as OneBunRequest;
+}
+
+function makeHeaders(entries: [string, string][]): Headers {
+  const h = new Headers();
+  for (const [key, value] of entries) {
+    h.set(key, value);
+  }
+
+  return h;
+}
+
+function makeContext(
+  headers: [string, string][] = [],
+  handler = 'testHandler',
+  controller = 'TestController',
+): HttpExecutionContext {
+  return new HttpExecutionContextImpl(makeRequest(makeHeaders(headers)), handler, controller);
+}
+
+// ============================================================================
+// HttpExecutionContextImpl
+// ============================================================================
+
+describe('HttpExecutionContextImpl', () => {
+  it('returns request from getRequest()', () => {
+    const req = makeRequest(makeHeaders([['authorization', 'Bearer token']]));
+    const ctx = new HttpExecutionContextImpl(req, 'myHandler', 'MyController');
+
+    expect(ctx.getRequest()).toBe(req);
+  });
+
+  it('returns handler name from getHandler()', () => {
+    const ctx = makeContext([], 'getUser', 'UserController');
+
+    expect(ctx.getHandler()).toBe('getUser');
+  });
+
+  it('returns controller name from getController()', () => {
+    const ctx = makeContext([], 'getUser', 'UserController');
+
+    expect(ctx.getController()).toBe('UserController');
+  });
+});
+
+// ============================================================================
+// executeHttpGuards
+// ============================================================================
+
+describe('executeHttpGuards', () => {
+  it('returns true when there are no guards', async () => {
+    const ctx = makeContext();
+
+    expect(await executeHttpGuards([], ctx)).toBe(true);
+  });
+
+  it('returns true when all guards pass', async () => {
+    const passGuard = createHttpGuard(() => true);
+    const ctx = makeContext();
+
+    expect(await executeHttpGuards([passGuard, passGuard], ctx)).toBe(true);
+  });
+
+  it('returns false when any guard fails', async () => {
+    const passGuard = createHttpGuard(() => true);
+    const failGuard = createHttpGuard(() => false);
+    const ctx = makeContext();
+
+    expect(await executeHttpGuards([passGuard, failGuard, passGuard], ctx)).toBe(false);
+  });
+
+  it('short-circuits on first failing guard', async () => {
+    let secondCalled = false;
+
+    const failGuard = createHttpGuard(() => false);
+    const trackGuard = createHttpGuard(() => {
+      secondCalled = true;
+
+      return true;
+    });
+    const ctx = makeContext();
+
+    await executeHttpGuards([failGuard, trackGuard], ctx);
+
+    expect(secondCalled).toBe(false);
+  });
+
+  it('accepts guard instances (not just class constructors)', async () => {
+    const instance: HttpGuard = { canActivate: () => true };
+    const ctx = makeContext();
+
+    expect(await executeHttpGuards([instance], ctx)).toBe(true);
+  });
+
+  it('accepts async guards', async () => {
+    const asyncPassGuard = createHttpGuard(async () => {
+      await Promise.resolve();
+
+      return true;
+    });
+    const ctx = makeContext();
+
+    expect(await executeHttpGuards([asyncPassGuard], ctx)).toBe(true);
+  });
+});
+
+// ============================================================================
+// createHttpGuard
+// ============================================================================
+
+describe('createHttpGuard', () => {
+  it('returns a class constructor', () => {
+    const guardClass = createHttpGuard(() => true);
+
+    expect(typeof guardClass).toBe('function');
+  });
+
+  it('instantiated class calls the provided function', async () => {
+    let called = false;
+    const guardClass = createHttpGuard((ctx) => {
+      called = true;
+
+      return ctx.getHandler() === 'target';
+    });
+    const ctx = makeContext([], 'target');
+    const instance = new guardClass();
+
+    expect(await instance.canActivate(ctx)).toBe(true);
+    expect(called).toBe(true);
+  });
+});
+
+// ============================================================================
+// AuthGuard
+// ============================================================================
+
+describe('AuthGuard', () => {
+  it('allows request with Bearer token', () => {
+    const guard = new AuthGuard();
+    const ctx = makeContext([['authorization', 'Bearer my-token']]);
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('blocks request without Authorization header', () => {
+    const guard = new AuthGuard();
+    const ctx = makeContext();
+
+    expect(guard.canActivate(ctx)).toBe(false);
+  });
+
+  it('blocks request with non-Bearer Authorization header', () => {
+    const guard = new AuthGuard();
+    const ctx = makeContext([['authorization', 'Basic dXNlcjpwYXNz']]);
+
+    expect(guard.canActivate(ctx)).toBe(false);
+  });
+});
+
+// ============================================================================
+// RolesGuard
+// ============================================================================
+
+describe('RolesGuard', () => {
+  it('allows when user has all required roles (default extractor)', () => {
+    const guard = new RolesGuard(['admin', 'editor']);
+    const headers = makeHeaders([['x-user-roles', 'admin, editor, viewer']]);
+    const ctx = new HttpExecutionContextImpl(makeRequest(headers), 'handler', 'Controller');
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('blocks when user is missing a required role', () => {
+    const guard = new RolesGuard(['admin']);
+    const headers = makeHeaders([['x-user-roles', 'viewer']]);
+    const ctx = new HttpExecutionContextImpl(makeRequest(headers), 'handler', 'Controller');
+
+    expect(guard.canActivate(ctx)).toBe(false);
+  });
+
+  it('blocks when x-user-roles header is absent', () => {
+    const guard = new RolesGuard(['admin']);
+    const ctx = makeContext();
+
+    expect(guard.canActivate(ctx)).toBe(false);
+  });
+
+  it('uses custom roles extractor when provided', () => {
+    const headers = makeHeaders([['x-roles', 'admin|user']]);
+    const guard = new RolesGuard(['admin'], (ctx) =>
+      ctx.getRequest().headers.get('x-roles')?.split('|') ?? [],
+    );
+    const ctx = new HttpExecutionContextImpl(makeRequest(headers), 'handler', 'Controller');
+
+    expect(guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('requires ALL roles to be present (not just one)', () => {
+    const guard = new RolesGuard(['admin', 'superuser']);
+    const headers = makeHeaders([['x-user-roles', 'admin']]);
+    const ctx = new HttpExecutionContextImpl(makeRequest(headers), 'handler', 'Controller');
+
+    expect(guard.canActivate(ctx)).toBe(false);
+  });
+});

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

@@ -48,6 +48,7 @@ export {
   type WsStorageType,
   type WsStorageOptions,
   type WebSocketApplicationOptions,
+  type StaticApplicationOptions,
   // Docs types
   type DocsApplicationOptions,
   // SSE types
@@ -131,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)', () => {