@onebun/core 0.1.1 → 0.1.3

package/README.md

@@ -291,6 +291,170 @@ return this.error('User not found', 404);
 
 Errors thrown in controller methods are automatically caught and converted to standardized error responses.
 
+## WebSocket Gateway
+
+OneBun provides WebSocket support with a Gateway pattern similar to NestJS, with full Socket.IO protocol compatibility.
+
+### Basic Gateway
+
+```typescript
+import {
+  WebSocketGateway,
+  BaseWebSocketGateway,
+  OnConnect,
+  OnDisconnect,
+  OnMessage,
+  Client,
+  MessageData,
+} from '@onebun/core';
+import type { WsClientData } from '@onebun/core';
+
+@WebSocketGateway({ path: '/ws' })
+export class ChatGateway extends BaseWebSocketGateway {
+  @OnConnect()
+  handleConnect(@Client() client: WsClientData) {
+    console.log(`Client ${client.id} connected`);
+    return { event: 'welcome', data: { clientId: client.id } };
+  }
+
+  @OnDisconnect()
+  handleDisconnect(@Client() client: WsClientData) {
+    console.log(`Client ${client.id} disconnected`);
+  }
+
+  @OnMessage('chat:message')
+  handleMessage(
+    @Client() client: WsClientData,
+    @MessageData() data: { text: string }
+  ) {
+    // Broadcast to all clients
+    this.broadcast('chat:message', {
+      userId: client.id,
+      text: data.text,
+    });
+  }
+}
+```
+
+### Pattern Matching
+
+Event patterns support wildcards and named parameters:
+
+```typescript
+// Wildcard: matches chat:general, chat:private, etc.
+@OnMessage('chat:*')
+handleAnyChat(@MessageData() data: unknown) {}
+
+// Named parameter: extracts roomId
+@OnMessage('chat:{roomId}:message')
+handleRoomMessage(@PatternParams() params: { roomId: string }) {}
+```
+
+### Room Management
+
+```typescript
+@WebSocketGateway({ path: '/ws' })
+export class RoomGateway extends BaseWebSocketGateway {
+  @OnJoinRoom('room:{roomId}')
+  async handleJoin(
+    @Client() client: WsClientData,
+    @RoomName() room: string,
+    @PatternParams() params: { roomId: string }
+  ) {
+    await this.joinRoom(client.id, room);
+    this.emitToRoom(room, 'user:joined', { userId: client.id });
+  }
+
+  @OnLeaveRoom('room:*')
+  async handleLeave(@Client() client: WsClientData, @RoomName() room: string) {
+    await this.leaveRoom(client.id, room);
+    this.emitToRoom(room, 'user:left', { userId: client.id });
+  }
+}
+```
+
+### Guards
+
+Protect WebSocket handlers with guards:
+
+```typescript
+import { UseWsGuards, WsAuthGuard, WsPermissionGuard } from '@onebun/core';
+
+@UseWsGuards(WsAuthGuard)
+@OnMessage('protected:*')
+handleProtected(@Client() client: WsClientData) {
+  // Only authenticated clients can access
+}
+
+@UseWsGuards(new WsPermissionGuard('admin'))
+@OnMessage('admin:*')
+handleAdmin(@Client() client: WsClientData) {
+  // Only clients with 'admin' permission
+}
+```
+
+### Typed Client
+
+Generate a type-safe WebSocket client:
+
+```typescript
+import { createWsServiceDefinition, createWsClient } from '@onebun/core';
+import { AppModule } from './app.module';
+
+const definition = createWsServiceDefinition(AppModule);
+const client = createWsClient(definition, {
+  url: 'ws://localhost:3000/ws',
+  auth: { token: 'your-token' },
+});
+
+await client.connect();
+
+// Type-safe event emission
+await client.ChatGateway.emit('chat:message', { text: 'Hello!' });
+
+// Subscribe to events
+client.ChatGateway.on('chat:message', (data) => {
+  console.log('Received:', data);
+});
+
+client.disconnect();
+```
+
+### Storage Options
+
+Configure client/room storage:
+
+```typescript
+const app = new OneBunApplication(AppModule, {
+  websocket: {
+    storage: {
+      type: 'memory', // or 'redis' for multi-instance
+      redis: {
+        url: 'redis://localhost:6379',
+        prefix: 'ws:',
+      },
+    },
+  },
+});
+```
+
+### Socket.IO Compatibility
+
+OneBun WebSocket Gateway is fully compatible with `socket.io-client`:
+
+```typescript
+import { io } from 'socket.io-client';
+
+const socket = io('ws://localhost:3000/ws', {
+  auth: { token: 'your-token' },
+});
+
+socket.on('chat:message', (data) => console.log(data));
+socket.emit('chat:message', { text: 'Hello!' });
+```
+
+For complete API documentation, see [docs/api/websocket.md](../../docs/api/websocket.md).
+
 ## Application
 
 Create and start an OneBun application:
@@ -313,6 +477,75 @@ app.start()
 
 The application automatically creates a logger based on NODE_ENV (development or production) and handles all Effect.js calls internally.
 
+## Graceful Shutdown
+
+OneBun supports graceful shutdown to cleanly close connections and release resources when the application stops. **Graceful shutdown is enabled by default.**
+
+### Default Behavior
+
+By default, the application automatically handles SIGTERM and SIGINT signals:
+
+```typescript
+const app = new OneBunApplication(AppModule, {
+  port: 3000,
+  // gracefulShutdown: true is the default
+});
+
+await app.start();
+// Application will automatically handle shutdown signals
+```
+
+### Disabling Graceful Shutdown
+
+If you need to manage shutdown manually, you can disable automatic handling:
+
+```typescript
+const app = new OneBunApplication(AppModule, {
+  gracefulShutdown: false, // Disable automatic SIGTERM/SIGINT handling
+});
+
+await app.start();
+
+// Now you must handle shutdown manually:
+// Option 1: Enable signal handlers later
+app.enableGracefulShutdown();
+
+// Option 2: Stop programmatically
+await app.stop();
+
+// Option 3: Stop but keep shared Redis connection open (for other consumers)
+await app.stop({ closeSharedRedis: false });
+```
+
+### What Gets Cleaned Up
+
+When the application stops, the following resources are cleaned up:
+
+1. **HTTP Server** - Bun server is stopped
+2. **WebSocket Handler** - All WebSocket connections are closed
+3. **Shared Redis** - If using SharedRedisProvider, the connection is closed (unless `closeSharedRedis: false`)
+
+### Shared Redis Connection
+
+When using `SharedRedisProvider` for cache, WebSocket storage, or other features, the connection is automatically closed on shutdown:
+
+```typescript
+import { SharedRedisProvider, OneBunApplication } from '@onebun/core';
+
+// Configure shared Redis at startup
+SharedRedisProvider.configure({
+  url: 'redis://localhost:6379',
+  keyPrefix: 'myapp:',
+});
+
+const app = new OneBunApplication(AppModule, {
+  gracefulShutdown: true,
+});
+
+await app.start();
+// Shared Redis will be closed when app receives SIGTERM/SIGINT
+```
+
 ## License
 
 [LGPL-3.0](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onebun/core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/{application.test.ts → application/application.test.ts}

@@ -9,10 +9,8 @@ import {
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { register } from 'prom-client';
 
-import type { ApplicationOptions } from './types';
+import type { ApplicationOptions } from '../types';
 
-import { OneBunApplication } from './application';
-import { Controller as BaseController } from './controller';
 import {
   Module,
   Controller,
@@ -21,8 +19,11 @@ import {
   Param,
   Query,
   Body,
-} from './decorators';
-import { makeMockLoggerLayer } from './test-utils';
+} from '../decorators/decorators';
+import { Controller as BaseController } from '../module/controller';
+import { makeMockLoggerLayer } from '../testing/test-utils';
+
+import { OneBunApplication } from './application';
 
 // Helper function to create app with mock logger to suppress logs in tests
 function createTestApp(
@@ -1102,4 +1103,123 @@ describe('OneBunApplication', () => {
       expect(mockTraceService.extractFromHeaders).not.toHaveBeenCalled();
     });
   });
+
+  describe('Graceful shutdown', () => {
+    let originalServe: typeof Bun.serve;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let mockServer: any;
+
+    beforeEach(() => {
+      register.clear();
+
+      mockServer = {
+        stop: mock(),
+        hostname: 'localhost',
+        port: 3000,
+      };
+
+      originalServe = Bun.serve;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (Bun as any).serve = mock(() => mockServer);
+    });
+
+    afterEach(() => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (Bun as any).serve = originalServe;
+    });
+
+    test('should stop server and cleanup resources on stop()', async () => {
+      @Module({})
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      await app.stop();
+
+      expect(mockServer.stop).toHaveBeenCalled();
+    });
+
+    test('should accept closeSharedRedis option in stop()', async () => {
+      @Module({})
+      class TestModule {}
+
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Stop without closing Redis
+      await app.stop({ closeSharedRedis: false });
+
+      expect(mockServer.stop).toHaveBeenCalled();
+    });
+
+    test('should enable graceful shutdown by default', async () => {
+      @Module({})
+      class TestModule {}
+
+      // Track process.on calls
+      const processOnMock = mock();
+      const originalProcessOn = process.on.bind(process);
+      process.on = processOnMock as typeof process.on;
+
+      // No gracefulShutdown option - should be enabled by default
+      const app = createTestApp(TestModule);
+      await app.start();
+
+      // Verify handlers were registered
+      expect(processOnMock).toHaveBeenCalledWith('SIGTERM', expect.any(Function));
+      expect(processOnMock).toHaveBeenCalledWith('SIGINT', expect.any(Function));
+
+      // Cleanup
+      process.on = originalProcessOn;
+      await app.stop();
+    });
+
+    test('should disable graceful shutdown when option is false', async () => {
+      @Module({})
+      class TestModule {}
+
+      // Track process.on calls
+      const processOnMock = mock();
+      const originalProcessOn = process.on.bind(process);
+      process.on = processOnMock as typeof process.on;
+
+      // Explicitly disable graceful shutdown
+      const app = createTestApp(TestModule, { gracefulShutdown: false });
+      await app.start();
+
+      // Verify handlers were NOT registered
+      expect(processOnMock).not.toHaveBeenCalledWith('SIGTERM', expect.any(Function));
+      expect(processOnMock).not.toHaveBeenCalledWith('SIGINT', expect.any(Function));
+
+      // Cleanup
+      process.on = originalProcessOn;
+      await app.stop();
+    });
+
+    test('should provide enableGracefulShutdown method for manual setup', async () => {
+      @Module({})
+      class TestModule {}
+
+      // Disable automatic graceful shutdown
+      const app = createTestApp(TestModule, { gracefulShutdown: false });
+      await app.start();
+
+      // Track process.on calls
+      const processOnMock = mock();
+      const originalProcessOn = process.on.bind(process);
+      process.on = processOnMock as typeof process.on;
+
+      // Manually enable graceful shutdown
+      app.enableGracefulShutdown();
+
+      // Verify handlers were registered
+      expect(processOnMock).toHaveBeenCalledWith('SIGTERM', expect.any(Function));
+      expect(processOnMock).toHaveBeenCalledWith('SIGINT', expect.any(Function));
+
+      // Cleanup
+      process.on = originalProcessOn;
+      await app.stop();
+    });
+  });
 });