@onebun/core 0.2.7 → 0.2.8

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

@@ -0,0 +1,172 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'bun:test';
+
+import type { OneBunRequest } from '../types';
+
+import { NotFoundError, HttpStatusCode } from '@onebun/requests';
+
+import { HttpExecutionContextImpl } from '../http-guards/http-guards';
+
+import { createExceptionFilter, defaultExceptionFilter } from './exception-filters';
+import { HttpException } from './http-exception';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function makeContext(): HttpExecutionContextImpl {
+  const req = new Request('http://localhost/test') as unknown as OneBunRequest;
+
+  return new HttpExecutionContextImpl(req, 'testHandler', 'TestController');
+}
+
+// ============================================================================
+// HttpException
+// ============================================================================
+
+describe('HttpException', () => {
+  it('stores statusCode and message', () => {
+    const ex = new HttpException(400, 'Bad request');
+    expect(ex).toBeInstanceOf(Error);
+    expect(ex.statusCode).toBe(400);
+    expect(ex.message).toBe('Bad request');
+    expect(ex.name).toBe('HttpException');
+  });
+
+  it('works with instanceof check', () => {
+    const ex = new HttpException(404, 'Not found');
+    expect(ex instanceof HttpException).toBe(true);
+    expect(ex instanceof Error).toBe(true);
+  });
+});
+
+// ============================================================================
+// createExceptionFilter
+// ============================================================================
+
+describe('createExceptionFilter', () => {
+  it('creates a filter that calls the provided function', async () => {
+    let caught: unknown;
+    const filter = createExceptionFilter((error, _ctx) => {
+      caught = error;
+
+      return new Response('handled', { status: 200 });
+    });
+
+    const err = new Error('boom');
+    const ctx = makeContext();
+    const response = await filter.catch(err, ctx);
+
+    expect(caught).toBe(err);
+    expect(response.status).toBe(200);
+    expect(await response.text()).toBe('handled');
+  });
+
+  it('receives the execution context', async () => {
+    let capturedHandler = '';
+    let capturedController = '';
+
+    const filter = createExceptionFilter((_error, ctx) => {
+      capturedHandler = ctx.getHandler();
+      capturedController = ctx.getController();
+
+      return new Response('ok');
+    });
+
+    const ctx = makeContext();
+    await filter.catch(new Error('test'), ctx);
+
+    expect(capturedHandler).toBe('testHandler');
+    expect(capturedController).toBe('TestController');
+  });
+
+  it('supports async filter functions', async () => {
+    const filter = createExceptionFilter(async () => {
+      await Promise.resolve();
+
+      return new Response('async', { status: 418 });
+    });
+
+    const response = await filter.catch(new Error('test'), makeContext());
+
+    expect(response.status).toBe(418);
+  });
+});
+
+// ============================================================================
+// defaultExceptionFilter
+// ============================================================================
+
+describe('defaultExceptionFilter', () => {
+  it('returns HTTP 200 with serialised OneBunBaseError', async () => {
+    const error = new NotFoundError('Not found');
+    const response = await defaultExceptionFilter.catch(error, makeContext());
+
+    expect(response.status).toBe(HttpStatusCode.OK);
+    const body = await response.json() as { success: boolean };
+    expect(body.success).toBe(false);
+  });
+
+  it('returns HTTP 200 with generic error details for plain Error', async () => {
+    const error = new Error('Something went wrong');
+    const response = await defaultExceptionFilter.catch(error, makeContext());
+
+    expect(response.status).toBe(HttpStatusCode.OK);
+    const body = await response.json() as { success: boolean; error: string };
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('Something went wrong');
+  });
+
+  it('returns HTTP 200 for non-Error values', async () => {
+    const response = await defaultExceptionFilter.catch('string error', makeContext());
+
+    expect(response.status).toBe(HttpStatusCode.OK);
+    const body = await response.json() as { success: boolean; error: string };
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('string error');
+  });
+
+  it('sets Content-Type to application/json', async () => {
+    const response = await defaultExceptionFilter.catch(new Error('test'), makeContext());
+
+    expect(response.headers.get('content-type')).toContain('application/json');
+  });
+
+  it('returns actual HTTP status for HttpException', async () => {
+    const error = new HttpException(400, 'Validation failed');
+    const response = await defaultExceptionFilter.catch(error, makeContext());
+    expect(response.status).toBe(400);
+    const body = await response.json() as { success: boolean; error: string };
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('Validation failed');
+  });
+
+  it('returns 404 for HttpException with 404 status', async () => {
+    const error = new HttpException(404, 'Not found');
+    const response = await defaultExceptionFilter.catch(error, makeContext());
+    expect(response.status).toBe(404);
+    const body = await response.json() as { success: boolean; error: string };
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('Not found');
+  });
+});
+
+// ============================================================================
+// Validation error via HttpException (bug reproduction)
+// ============================================================================
+
+describe('Validation error via HttpException (bug reproduction)', () => {
+  it('returns 400 with JSON body for validation HttpException', async () => {
+    const error = new HttpException(400, 'Parameter body validation failed: name must be a string (was missing)');
+    const response = await defaultExceptionFilter.catch(error, makeContext());
+
+    expect(response.status).toBe(400);
+    const body = await response.json() as { success: boolean; error: string; statusCode: number };
+    expect(body.success).toBe(false);
+    expect(body.error).toContain('validation failed');
+    expect(response.headers.get('content-type')).toContain('application/json');
+  });
+});

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);
+  });
+});