@onebun/core 0.2.6 → 0.2.8

package/src/docs-examples.test.ts

@@ -9,6 +9,9 @@
  * - docs/api/services.md
  * - docs/api/validation.md
  * - docs/api/websocket.md
+ * - docs/api/guards.md
+ * - docs/api/exception-filters.md
+ * - docs/api/security.md
  * - docs/examples/basic-app.md
  * - docs/examples/crud-api.md
  * - docs/examples/websocket-chat.md
@@ -33,6 +36,7 @@ import type {
   BeforeApplicationDestroy,
   OnApplicationDestroy,
 } from './';
+import type { ExceptionFilter } from './exception-filters/exception-filters';
 import type {
   SseEvent,
   SseGenerator,
@@ -41,6 +45,7 @@ import type {
   MiddlewareClass,
   OnModuleConfigure,
 } from './types';
+import type { HttpExecutionContext } from './types';
 import type { ServerWebSocket } from 'bun';
 
 import {
@@ -125,6 +130,19 @@ import {
   DEFAULT_IDLE_TIMEOUT,
   DEFAULT_SSE_HEARTBEAT_MS,
   DEFAULT_SSE_TIMEOUT,
+  UseGuards,
+  AuthGuard,
+  RolesGuard,
+  createHttpGuard,
+  HttpExecutionContextImpl,
+  UseFilters,
+  createExceptionFilter,
+  defaultExceptionFilter,
+  HttpException,
+  CorsMiddleware,
+  RateLimitMiddleware,
+  MemoryRateLimitStore,
+  SecurityHeadersMiddleware,
 } from './';
 
 
@@ -1096,7 +1114,7 @@ describe('Middleware API Documentation Examples (docs/api/controllers.md)', () =
         }
       }
 
-      class CorsMiddleware extends BaseMiddleware {
+      class ExampleCorsMiddleware extends BaseMiddleware {
         async use(_req: OneBunRequest, next: () => Promise<OneBunResponse>) {
           const response = await next();
           response.headers.set('Access-Control-Allow-Origin', '*');
@@ -1115,7 +1133,7 @@ describe('Middleware API Documentation Examples (docs/api/controllers.md)', () =
 
       const app = new OneBunApplication(AppModule, {
         port: 0,
-        middleware: [RequestIdMiddleware, CorsMiddleware],
+        middleware: [RequestIdMiddleware, ExampleCorsMiddleware],
       });
 
       expect(app).toBeDefined();
@@ -1648,7 +1666,7 @@ describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', ()
 
   describe('Controller Lifecycle Hooks', () => {
     /**
-     * @source docs/api/controllers.md#lifecycle-hooks
+     * @source docs/api/services.md#lifecycle-hooks (controllers support the same hooks)
      */
     it('should implement lifecycle hooks in controllers', () => {
       // From docs: Controller lifecycle hooks example
@@ -1855,6 +1873,67 @@ describe('Lifecycle Hooks API Documentation Examples (docs/api/services.md)', ()
       // Database initialized first, then cache saw database was ready
       expect(initOrder).toEqual(['database', 'cache:db-ready=true']);
     });
+
+    /**
+     * @source docs/api/services.md#lifecycle-hooks
+     * onModuleInit is called for services in ALL modules across the entire
+     * import tree, not just the root module. Deeply nested modules are
+     * initialized in depth-first order.
+     */
+    it('should call onModuleInit for services across the entire module import tree', async () => {
+      const moduleMod = await import('./module/module');
+      const testUtils = await import('./testing/test-utils');
+      const effectLib = await import('effect');
+
+      const initLog: string[] = [];
+
+      @Service()
+      class AuthService extends BaseService implements OnModuleInit {
+        async onModuleInit(): Promise<void> {
+          initLog.push('auth');
+        }
+      }
+
+      @Module({
+        providers: [AuthService],
+      })
+      class AuthModule {}
+
+      @Service()
+      class UserService extends BaseService implements OnModuleInit {
+        async onModuleInit(): Promise<void> {
+          initLog.push('user');
+        }
+      }
+
+      @Module({
+        imports: [AuthModule],
+        providers: [UserService],
+      })
+      class UserModule {}
+
+      @Service()
+      class AppService extends BaseService implements OnModuleInit {
+        async onModuleInit(): Promise<void> {
+          initLog.push('app');
+        }
+      }
+
+      @Module({
+        imports: [UserModule],
+        providers: [AppService],
+      })
+      class AppModule {}
+
+      const mod = new moduleMod.OneBunModule(AppModule, testUtils.makeMockLoggerLayer());
+      await effectLib.Effect.runPromise(mod.setup() as import('effect').Effect.Effect<unknown, never, never>);
+
+      // All three modules' services should have onModuleInit called
+      expect(initLog).toContain('auth');
+      expect(initLog).toContain('user');
+      expect(initLog).toContain('app');
+      expect(initLog.length).toBe(3);
+    });
   });
 });
 
@@ -2406,6 +2485,34 @@ describe('OneBunApplication (docs/api/core.md)', () => {
     const app = new OneBunApplication(AppModule, { tracing: tracingOptions, loggerLayer: makeMockLoggerLayer() });
     expect(app).toBeDefined();
   });
+
+  /**
+   * @source docs/api/core.md#staticapplicationoptions
+   */
+  it('should accept static file serving configuration (SPA on same host)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const os = await import('node:os');
+
+    const tmpDir = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'onebun-docs-static-'));
+    try {
+      fs.writeFileSync(path.join(tmpDir, 'index.html'), '<!DOCTYPE html><html><body>SPA</body></html>', 'utf8');
+
+      @Module({ controllers: [] })
+      class AppModule {}
+
+      // From docs: Static files (SPA on same host)
+      const app = new OneBunApplication(AppModule, {
+        loggerLayer: makeMockLoggerLayer(),
+        static: { root: tmpDir, fallbackFile: 'index.html' },
+      });
+      expect(app).toBeDefined();
+      await app.start();
+      await app.stop();
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe('MultiServiceApplication (docs/api/core.md)', () => {
@@ -5322,3 +5429,279 @@ describe('File Upload API Documentation (docs/api/controllers.md)', () => {
     expect(FileController).toBeDefined();
   });
 });
+
+// ============================================================================
+// docs/api/guards.md examples
+// ============================================================================
+
+describe('docs/api/guards.md', () => {
+  it('createHttpGuard — function-based guard returns a class constructor', () => {
+    const apiKeyGuardClass = createHttpGuard((ctx) => {
+      return ctx.getRequest().headers.get('x-api-key') !== null;
+    });
+
+    expect(apiKeyGuardClass).toBeDefined();
+    // createHttpGuard returns a constructor — instantiate to get the guard instance
+    const instance = new apiKeyGuardClass();
+    expect(typeof instance.canActivate).toBe('function');
+  });
+
+  it('AuthGuard blocks request without Bearer token', async () => {
+    const guard = new AuthGuard();
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    expect(await guard.canActivate(ctx)).toBe(false);
+  });
+
+  it('AuthGuard allows request with Bearer token', async () => {
+    const guard = new AuthGuard();
+    const req = new Request('http://localhost/', {
+      headers: { authorization: 'Bearer my-token' },
+    }) as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    expect(await guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('RolesGuard checks x-user-roles header', async () => {
+    const guard = new RolesGuard(['admin']);
+    const h = new Headers();
+    h.set('x-user-roles', 'admin,user');
+    const req = new Request('http://localhost/', { headers: h }) as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    expect(await guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('RolesGuard rejects when role not present', async () => {
+    const guard = new RolesGuard(['admin']);
+    const h = new Headers();
+    h.set('x-user-roles', 'user');
+    const req = new Request('http://localhost/', { headers: h }) as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    expect(await guard.canActivate(ctx)).toBe(false);
+  });
+
+  it('RolesGuard with custom role extractor', async () => {
+    const guard = new RolesGuard(
+      ['admin'],
+      (ctx) => {
+        const raw = ctx.getRequest().headers.get('x-custom-roles');
+
+        return raw ? raw.split(':') : [];
+      },
+    );
+    const h = new Headers();
+    h.set('x-custom-roles', 'admin:editor');
+    const req = new Request('http://localhost/', { headers: h }) as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    expect(await guard.canActivate(ctx)).toBe(true);
+  });
+
+  it('@UseGuards applies metadata to controller', () => {
+    @UseGuards(AuthGuard)
+    @Controller('/protected')
+    class ProtectedController extends BaseController {
+      @Get('/')
+      index() {
+        return { message: 'authenticated' };
+      }
+    }
+
+    expect(ProtectedController).toBeDefined();
+  });
+});
+
+// ============================================================================
+// docs/api/exception-filters.md examples
+// ============================================================================
+
+describe('docs/api/exception-filters.md', () => {
+  it('createExceptionFilter — function-based filter', async () => {
+    const filter = createExceptionFilter((error, _ctx) => {
+      if (error instanceof Error) {
+        return new Response(JSON.stringify({ caught: error.message }), { status: 200 });
+      }
+      throw error;
+    });
+
+    expect(filter).toBeDefined();
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+    const res = await filter.catch(new Error('boom'), ctx);
+    const body = await res.json() as { caught: string };
+
+    expect(body.caught).toBe('boom');
+  });
+
+  it('class-based filter — re-throws unknown errors', async () => {
+    class TypedFilter implements ExceptionFilter {
+      catch(error: unknown, _ctx: HttpExecutionContext): Response {
+        if (error instanceof RangeError) {
+          return Response.json({ success: false, error: 'range' });
+        }
+        throw error;
+      }
+    }
+
+    const filter = new TypedFilter();
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+
+    const res = await filter.catch(new RangeError('out of range'), ctx);
+    const body = await res.json() as { success: boolean; error: string };
+
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('range');
+  });
+
+  it('defaultExceptionFilter handles OneBunBaseError subclass', async () => {
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+    const res = await defaultExceptionFilter.catch(new NotFoundError('not found'), ctx);
+    const body = await res.json() as { success: boolean };
+
+    expect(body.success).toBe(false);
+  });
+
+  it('async filter resolves correctly', async () => {
+    const asyncFilter = createExceptionFilter(async (error, _ctx) => {
+      await Promise.resolve(); // simulate async work
+
+      return new Response(JSON.stringify({ async: true, msg: String(error) }));
+    });
+
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+    const res = await asyncFilter.catch(new Error('err'), ctx);
+    const body = await res.json() as { async: boolean };
+
+    expect(body.async).toBe(true);
+  });
+
+  it('HttpException — carries statusCode', () => {
+    const ex = new HttpException(400, 'Bad request');
+
+    expect(ex).toBeInstanceOf(Error);
+    expect(ex.statusCode).toBe(400);
+    expect(ex.message).toBe('Bad request');
+  });
+
+  it('defaultExceptionFilter returns real HTTP status for HttpException', async () => {
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+    const ctx = new HttpExecutionContextImpl(req, 'handler', 'Controller');
+    const res = await defaultExceptionFilter.catch(
+      new HttpException(404, 'Not found'),
+      ctx,
+    );
+
+    expect(res.status).toBe(404);
+    const body = await res.json() as { success: boolean; error: string };
+    expect(body.success).toBe(false);
+    expect(body.error).toBe('Not found');
+  });
+
+  it('@UseFilters applies metadata to controller', () => {
+    const filter = createExceptionFilter((err, _ctx) => {
+      throw err;
+    });
+
+    @UseFilters(filter)
+    @Controller('/filtered')
+    class FilteredController extends BaseController {
+      @Get('/')
+      index() {
+        return {};
+      }
+    }
+
+    expect(FilteredController).toBeDefined();
+  });
+});
+
+// ============================================================================
+// docs/api/security.md examples
+// ============================================================================
+
+describe('docs/api/security.md', () => {
+  it('CorsMiddleware — default wildcard origin', async () => {
+    const mw = new CorsMiddleware();
+    const req = new Request('http://localhost/', {
+      headers: { origin: 'https://example.com' },
+    }) as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe('*');
+  });
+
+  it('CorsMiddleware — preflight returns 204', async () => {
+    const mw = new CorsMiddleware();
+    const req = new Request('http://localhost/', {
+      method: 'OPTIONS',
+      headers: { origin: 'https://example.com' },
+    }) as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.status).toBe(204);
+  });
+
+  it('CorsMiddleware.configure() factory', async () => {
+    const configuredClass = CorsMiddleware.configure({ origin: 'https://trusted.com' });
+    const mw = new configuredClass();
+    const req = new Request('http://localhost/', {
+      headers: { origin: 'https://trusted.com' },
+    }) as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe('https://trusted.com');
+  });
+
+  it('RateLimitMiddleware — allows below max', async () => {
+    const store = new MemoryRateLimitStore();
+    const mw = new RateLimitMiddleware({ max: 5, windowMs: 60_000, store });
+    const h1 = new Headers();
+    h1.set('x-forwarded-for', '1.2.3.4');
+    const req = new Request('http://localhost/', { headers: h1 }) as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.status).toBe(200);
+  });
+
+  it('RateLimitMiddleware — returns 429 when over limit', async () => {
+    const store = new MemoryRateLimitStore();
+    const mw = new RateLimitMiddleware({ max: 1, windowMs: 60_000, store });
+    const h2 = new Headers();
+    h2.set('x-forwarded-for', '9.9.9.9');
+    const req = new Request('http://localhost/', { headers: h2 }) as unknown as OneBunRequest;
+    await mw.use(req, async () => new Response('ok'));
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.status).toBe(429);
+  });
+
+  it('SecurityHeadersMiddleware — sets X-Frame-Options', async () => {
+    const mw = new SecurityHeadersMiddleware();
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.headers.get('X-Frame-Options')).toBe('SAMEORIGIN');
+    expect(res.headers.get('X-Content-Type-Options')).toBe('nosniff');
+  });
+
+  it('SecurityHeadersMiddleware — disabled header is absent', async () => {
+    const mw = new SecurityHeadersMiddleware({ strictTransportSecurity: false });
+    const req = new Request('http://localhost/') as unknown as OneBunRequest;
+
+    const res = await mw.use(req, async () => new Response('ok'));
+
+    expect(res.headers.get('Strict-Transport-Security')).toBeNull();
+  });
+});

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