@onebun/core 0.1.1 → 0.1.2

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.2",
   "description": "Core package for OneBun framework - decorators, DI, modules, controllers",
   "license": "LGPL-3.0",
   "author": "RemRyahirev",

package/src/application.test.ts

@@ -1102,4 +1102,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();
+    });
+  });
 });

package/src/application.ts

@@ -1,6 +1,7 @@
 import { Effect, type Layer } from 'effect';
 
 import type { Controller } from './controller';
+import type { WsClientData } from './ws.types';
 
 import { TypedEnv } from '@onebun/envs';
 import {
@@ -22,6 +23,7 @@ import { makeTraceService, TraceService } from '@onebun/trace';
 import { ConfigServiceImpl } from './config.service';
 import { getControllerMetadata } from './decorators';
 import { OneBunModule } from './module';
+import { SharedRedisProvider } from './shared-redis';
 import {
   type ApplicationOptions,
   type HttpMethod,
@@ -31,6 +33,7 @@ import {
   type RouteMetadata,
 } from './types';
 import { validateOrThrow } from './validation';
+import { WsHandler, isWebSocketGateway } from './ws-handler';
 
 // Conditionally import metrics
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -75,6 +78,7 @@ export class OneBunApplication {
   private metricsService: any = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private traceService: any = null;
+  private wsHandler: WsHandler | null = null;
 
   /**
    * Create application instance
@@ -260,6 +264,20 @@ export class OneBunApplication {
       const controllers = this.rootModule.getControllers();
       this.logger.debug(`Loaded ${controllers.length} controllers`);
 
+      // Initialize WebSocket handler and detect gateways
+      this.wsHandler = new WsHandler(this.logger, this.options.websocket);
+      
+      // Register WebSocket gateways (they are in controllers array but decorated with @WebSocketGateway)
+      for (const controllerClass of controllers) {
+        if (isWebSocketGateway(controllerClass)) {
+          const instance = this.rootModule.getControllerInstance?.(controllerClass);
+          if (instance) {
+            this.wsHandler.registerGateway(controllerClass, instance as import('./ws-base-gateway').BaseWebSocketGateway);
+            this.logger.info(`Registered WebSocket gateway: ${controllerClass.name}`);
+          }
+        }
+      }
+
       // Create a map of routes with metadata
       const routes = new Map<
         string,
@@ -359,15 +377,48 @@ export class OneBunApplication {
 
       // Create server with proper context binding
       const app = this;
-      this.server = Bun.serve({
+      const hasWebSocketGateways = this.wsHandler?.hasGateways() ?? false;
+      
+      // Prepare WebSocket handlers if gateways exist
+      // When no gateways, use no-op handlers (required by Bun.serve)
+      const wsHandlers = hasWebSocketGateways ? this.wsHandler!.createWebSocketHandlers() : {
+         
+        open() { /* no-op */ },
+         
+        message() { /* no-op */ },
+         
+        close() { /* no-op */ },
+         
+        drain() { /* no-op */ },
+      };
+      
+      this.server = Bun.serve<WsClientData>({
         port: this.options.port,
         hostname: this.options.host,
-        async fetch(req) {
+        // WebSocket handlers
+        websocket: wsHandlers,
+        async fetch(req, server) {
           const url = new URL(req.url);
           const path = url.pathname;
           const method = req.method;
           const startTime = Date.now();
 
+          // Handle WebSocket upgrade if gateways exist
+          if (hasWebSocketGateways && app.wsHandler) {
+            const upgradeHeader = req.headers.get('upgrade')?.toLowerCase();
+            
+            // Check for WebSocket upgrade or Socket.IO polling
+            if (upgradeHeader === 'websocket' || path.startsWith('/socket.io')) {
+              const response = await app.wsHandler.handleUpgrade(req, server);
+              if (response === undefined) {
+                return undefined; // Successfully upgraded
+              }
+
+              // Return response if upgrade failed
+              return response;
+            }
+          }
+
           // Setup tracing context if available and enabled
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           let traceSpan: any = null;
@@ -675,6 +726,12 @@ export class OneBunApplication {
         },
       });
 
+      // Initialize WebSocket gateways with server
+      if (hasWebSocketGateways && this.wsHandler && this.server) {
+        this.wsHandler.initializeGateways(this.server);
+        this.logger.info(`WebSocket server enabled at ws://${this.options.host}:${this.options.port}`);
+      }
+
       this.logger.info(`Server started on http://${this.options.host}:${this.options.port}`);
       if (this.metricsService) {
         this.logger.info(
@@ -685,6 +742,11 @@ export class OneBunApplication {
           'Metrics enabled but @onebun/metrics module not available. Install with: bun add @onebun/metrics',
         );
       }
+
+      // Enable graceful shutdown by default (can be disabled with gracefulShutdown: false)
+      if (this.options.gracefulShutdown !== false) {
+        this.enableGracefulShutdown();
+      }
     } catch (error) {
       this.logger.error(
         'Failed to start application:',
@@ -910,14 +972,59 @@ export class OneBunApplication {
   }
 
   /**
-   * Stop the application
+   * Stop the application with graceful shutdown
+   * @param options - Shutdown options
    */
-  stop(): void {
+  async stop(options?: { closeSharedRedis?: boolean }): Promise<void> {
+    const closeRedis = options?.closeSharedRedis ?? true;
+
+    this.logger.info('Stopping OneBun application...');
+
+    // Cleanup WebSocket resources
+    if (this.wsHandler) {
+      this.logger.debug('Cleaning up WebSocket handler');
+      await this.wsHandler.cleanup();
+      this.wsHandler = null;
+    }
+
+    // Stop HTTP server
     if (this.server) {
       this.server.stop();
       this.server = null;
-      this.logger.info('OneBun application stopped');
+      this.logger.debug('HTTP server stopped');
+    }
+
+    // Close shared Redis connection if configured and requested
+    if (closeRedis && SharedRedisProvider.isConnected()) {
+      this.logger.debug('Disconnecting shared Redis');
+      await SharedRedisProvider.disconnect();
     }
+
+    this.logger.info('OneBun application stopped');
+  }
+
+  /**
+   * Register signal handlers for graceful shutdown
+   * Call this after start() to enable automatic shutdown on SIGTERM/SIGINT
+   * 
+   * @example
+   * ```typescript
+   * const app = new OneBunApplication(AppModule, options);
+   * await app.start();
+   * app.enableGracefulShutdown();
+   * ```
+   */
+  enableGracefulShutdown(): void {
+    const shutdown = async (signal: string) => {
+      this.logger.info(`Received ${signal}, initiating graceful shutdown...`);
+      await this.stop();
+      process.exit(0);
+    };
+
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+
+    this.logger.debug('Graceful shutdown handlers registered');
   }
 
   /**