@fluojs/websockets 1.0.0-beta.3 → 1.0.0-beta.5

package/README.ko.md

@@ -65,8 +65,8 @@ class MetricsGateway {
 }
 ```
 
-### Server-Backed (Node.js 전용)
-Node 기반 어댑터(Express/Fastify)의 경우 전용 리스너 포트를 사용하도록 설정할 수 있습니다.
+### Server-Backed Node adapter
+Server-backed Node adapter(Node.js, Express, Fastify)에서는 전용 listener port를 사용할 수 있습니다. Fetch-style runtime(`@fluojs/websockets/bun`, `@fluojs/websockets/deno`, `@fluojs/websockets/cloudflare-workers`)은 `serverBacked`를 거부합니다.
 
 ```typescript
 @WebSocketGateway({ 
@@ -101,7 +101,7 @@ WebSocketModule.forRoot({
 });
 ```
 
-옵션을 생략하면 `@fluojs/websockets`는 동시 연결 수와 인바운드 페이로드 크기에 대해 기본 제한값을 적용합니다. 또한 server-backed Node 리스너는 `heartbeat.enabled`를 명시적으로 `false`로 두지 않는 한 heartbeat 타이머를 활성화합니다.
+옵션을 생략하면 `@fluojs/websockets`는 동시 연결 수, inbound payload 크기, pending message buffer, shutdown cleanup에 bounded default를 적용합니다. 기본값은 `maxConnections: 1000`, `maxPayloadBytes: 1 MiB`, `buffer.maxPendingMessagesPerSocket: 256`, `shutdown.timeoutMs: 5000`, Node heartbeat interval `30s`, Node backpressure `maxBufferedAmountBytes: 1 MiB`와 drop behavior입니다. 또한 server-backed Node listener는 `heartbeat.enabled`를 명시적으로 `false`로 두지 않는 한 heartbeat timer를 활성화합니다. 공식 fetch-style runtime module(`@fluojs/websockets/bun`, `@fluojs/websockets/deno`, `@fluojs/websockets/cloudflare-workers`)은 애플리케이션 shutdown 시 추적 중인 websocket 클라이언트를 닫고 `shutdown.timeoutMs` 범위 안에서 `@OnDisconnect()` cleanup이 마무리될 수 있도록 bounded 기회를 제공합니다.
 
 ## 공개 API 개요
 
@@ -110,20 +110,20 @@ WebSocketModule.forRoot({
 - `@OnMessage(event?)`: 인바운드 메시지 핸들러를 위한 데코레이터입니다.
 - `@OnDisconnect()`: 연결 해제 핸들러를 위한 데코레이터입니다.
 - `WebSocketModule`: WebSocket 통합을 위한 루트 모듈입니다.
-- `WebSocketModule.forRoot({ upgrade, limits, heartbeat, ... })`: pre-upgrade guard와 기본 제한값을 구성합니다.
+- `WebSocketModule.forRoot({ upgrade, limits, backpressure, buffer, heartbeat, shutdown })`: pre-upgrade guard와 bounded runtime default를 구성합니다.
 - `WebSocketGatewayLifecycleService`: 기본 Node.js 기반 lifecycle service token을 위한 루트 alias입니다.
-- `WebSocketModule.forRoot(...)`: 기본 루트 WebSocket 모듈의 패키지 수준 등록을 구성합니다.
+- Metadata helper와 symbol: `defineWebSocketGatewayMetadata`, `getWebSocketGatewayMetadata`, `defineWebSocketHandlerMetadata`, `getWebSocketHandlerMetadata`, `getWebSocketHandlerMetadataEntries`, `webSocketGatewayMetadataSymbol`, `webSocketHandlerMetadataSymbol`.
 
 ## 런타임별 서브패스
 
 기본 루트 Node.js alias 대신 런타임을 명시적으로 고정하고 싶다면 런타임별 서브패스를 사용하세요. 각 서브패스는 해당 `*WebSocketModule.forRoot(...)` 진입점과 일치하는 런타임 lifecycle service export를 제공합니다.
 
-| 런타임 | 서브패스 | 모듈 |
-| --- | --- | --- |
-| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` |
-| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` |
-| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` |
-| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` |
+| 런타임 | 서브패스 | 모듈 | Lifecycle service |
+| --- | --- | --- | --- |
+| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` | `NodeWebSocketGatewayLifecycleService` |
+| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` | `BunWebSocketGatewayLifecycleService` |
+| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` | `DenoWebSocketGatewayLifecycleService` |
+| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` | `CloudflareWorkersWebSocketGatewayLifecycleService` |
 
 ## 예제 소스
 
@@ -131,3 +131,5 @@ WebSocketModule.forRoot({
 - `packages/websockets/src/public-surface.test.ts`
 - `packages/websockets/src/node/node.test.ts`
 - `packages/websockets/src/bun/bun.test.ts`
+- `packages/websockets/src/deno/deno.test.ts`
+- `packages/websockets/src/cloudflare-workers/cloudflare-workers.test.ts`

package/README.md

@@ -65,8 +65,8 @@ class MetricsGateway {
 }
 ```
 
-### Server-Backed (Node.js Only)
-For Node-based adapters (Express/Fastify), you can opt into a dedicated listener port.
+### Server-Backed Node Adapters
+For server-backed Node adapters (Node.js, Express, Fastify), you can opt into a dedicated listener port. Fetch-style runtimes (`@fluojs/websockets/bun`, `@fluojs/websockets/deno`, and `@fluojs/websockets/cloudflare-workers`) reject `serverBacked`.
 
 ```typescript
 @WebSocketGateway({ 
@@ -101,7 +101,7 @@ WebSocketModule.forRoot({
 });
 ```
 
-When omitted, `@fluojs/websockets` now applies bounded defaults for concurrent connections and inbound payload size. Server-backed Node listeners also enable heartbeat timers unless you explicitly set `heartbeat.enabled` to `false`.
+When omitted, `@fluojs/websockets` applies bounded defaults for concurrent connections, inbound payload size, pending message buffers, and shutdown cleanup. Default settings are `maxConnections: 1000`, `maxPayloadBytes: 1 MiB`, `buffer.maxPendingMessagesPerSocket: 256`, `shutdown.timeoutMs: 5000`, Node heartbeat interval `30s`, and Node backpressure `maxBufferedAmountBytes: 1 MiB` with drop behavior. Server-backed Node listeners enable heartbeat timers unless you explicitly set `heartbeat.enabled` to `false`. The official fetch-style runtime modules (`@fluojs/websockets/bun`, `@fluojs/websockets/deno`, and `@fluojs/websockets/cloudflare-workers`) close tracked websocket clients during application shutdown and give `@OnDisconnect()` cleanup a bounded chance to finish within `shutdown.timeoutMs`.
 
 ## Public API Overview
 
@@ -110,20 +110,20 @@ When omitted, `@fluojs/websockets` now applies bounded defaults for concurrent c
 - `@OnMessage(event?)`: Decorator for inbound message handlers.
 - `@OnDisconnect()`: Decorator for disconnection handlers.
 - `WebSocketModule`: Root module for WebSocket integration.
-- `WebSocketModule.forRoot({ upgrade, limits, heartbeat, ... })`: Configures pre-upgrade guards and bounded runtime defaults.
+- `WebSocketModule.forRoot({ upgrade, limits, backpressure, buffer, heartbeat, shutdown })`: Configures pre-upgrade guards and bounded runtime defaults.
 - `WebSocketGatewayLifecycleService`: Root alias for the default Node.js-backed lifecycle service token.
-- `WebSocketModule.forRoot(...)`: Configures package-level registration for the default root websocket module.
+- Metadata helpers and symbols: `defineWebSocketGatewayMetadata`, `getWebSocketGatewayMetadata`, `defineWebSocketHandlerMetadata`, `getWebSocketHandlerMetadata`, `getWebSocketHandlerMetadataEntries`, `webSocketGatewayMetadataSymbol`, `webSocketHandlerMetadataSymbol`.
 
 ## Runtime-Specific Subpaths
 
 Use the runtime subpaths when you want an explicit runtime binding instead of the default root Node.js alias. Each subpath exposes its `*WebSocketModule.forRoot(...)` entrypoint plus the matching runtime lifecycle service export.
 
-| Runtime | Subpath | Module |
-| --- | --- | --- |
-| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` |
-| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` |
-| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` |
-| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` |
+| Runtime | Subpath | Module | Lifecycle service |
+| --- | --- | --- | --- |
+| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` | `NodeWebSocketGatewayLifecycleService` |
+| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` | `BunWebSocketGatewayLifecycleService` |
+| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` | `DenoWebSocketGatewayLifecycleService` |
+| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` | `CloudflareWorkersWebSocketGatewayLifecycleService` |
 
 ## Example Sources
 
@@ -131,3 +131,5 @@ Use the runtime subpaths when you want an explicit runtime binding instead of th
 - `packages/websockets/src/public-surface.test.ts`
 - `packages/websockets/src/node/node.test.ts`
 - `packages/websockets/src/bun/bun.test.ts`
+- `packages/websockets/src/deno/deno.test.ts`
+- `packages/websockets/src/cloudflare-workers/cloudflare-workers.test.ts`

package/dist/bun/bun-service.d.ts

@@ -12,11 +12,14 @@ export declare class BunWebSocketGatewayLifecycleService implements OnApplicatio
     private readonly logger;
     private readonly adapter;
     private readonly moduleOptions;
+    private isShuttingDown;
+    private readonly pendingUpgradeOperations;
     private pendingUpgradeReservations;
     private readonly roomSockets;
     private shutdownPromise;
     private readonly socketRegistry;
     private readonly socketRooms;
+    private readonly socketStates;
     constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, adapter: HttpApplicationAdapter, moduleOptions: WebSocketModuleOptions);
     onApplicationBootstrap(): Promise<void>;
     private assertNoServerBackedGatewayOptIn;
@@ -27,6 +30,9 @@ export declare class BunWebSocketGatewayLifecycleService implements OnApplicatio
     private handleUpgradeRequest;
     private bindConnectionHandlers;
     private createConnectionHandlerState;
+    private settleOpenRegistration;
+    private settleConnectLifecycle;
+    private settleDisconnectLifecycle;
     private getBufferedMessageCount;
     private getQueuedMessageCount;
     private maybeCompactBufferedMessages;
@@ -52,8 +58,13 @@ export declare class BunWebSocketGatewayLifecycleService implements OnApplicatio
     private releaseUpgradeReservation;
     private resolveMaxPayloadBytes;
     private resolveIdleTimeoutSeconds;
+    private resolveShutdownTimeoutMs;
     private shutdown;
     private runShutdownLifecycle;
+    private trackPendingUpgradeOperation;
+    private awaitPendingUpgradeOperations;
+    private closeActiveSockets;
+    private awaitHandlerQueueDrain;
     joinRoom(socketId: string, room: string): void;
     leaveRoom(socketId: string, room: string): void;
     broadcastToRoom(room: string, event: string, data: unknown): void;

package/dist/bun/bun-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bun-service.d.ts","sourceRoot":"","sources":["../../src/bun/bun-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AASzI,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAa3D,OAAO,KAAK,EAGV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAyG7D;;GAEG;AACH,qBACa,mCACX,YAAW,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,oBAAoB;IAS7F,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAXhC,OAAO,CAAC,0BAA0B,CAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwD;IACvF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;gBAG3C,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,sBAAsB,EAC/B,aAAa,EAAE,sBAAsB;IAGlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB7C,OAAO,CAAC,gCAAgC;IAclC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,OAAO,CAAC,aAAa;IAiCrB,OAAO,CAAC,sBAAsB;YAmBhB,oBAAoB;YAkDpB,sBAAsB;IAWpC,OAAO,CAAC,4BAA4B;IAqBpC,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,4BAA4B;IASpC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,qBAAqB;IA0C7B,OAAO,CAAC,sBAAsB;YAwDhB,iBAAiB;IAmB/B,OAAO,CAAC,yBAAyB;YAsBnB,yBAAyB;YAczB,kBAAkB;YASlB,yBAAyB;IASvC,OAAO,CAAC,8BAA8B;IAoBtC,OAAO,CAAC,wBAAwB;YAUlB,uBAAuB;IAmDrC,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,8BAA8B;IAItC,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,yBAAyB;IAMjC,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,yBAAyB;YAcnB,QAAQ;YAUR,oBAAoB;IAYlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAmB9C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAc/C,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IA4BjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IAU/C,OAAO,CAAC,gBAAgB;CAgBzB"}
+{"version":3,"file":"bun-service.d.ts","sourceRoot":"","sources":["../../src/bun/bun-service.ts"],"names":[],"mappings":"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"}

package/dist/bun/bun-service.js

@@ -11,6 +11,7 @@ import { WEBSOCKET_OPTIONS_INTERNAL } from '../options-token.internal.js';
 const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 256;
 const DEFAULT_MAX_WEBSOCKET_CONNECTIONS = 1_000;
 const DEFAULT_MAX_WEBSOCKET_PAYLOAD_BYTES = 1_048_576;
+const DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS = 5_000;
 const LIFECYCLE_LOG_CONTEXT = 'WebSocketGatewayLifecycleService';
 function hasBunWebSocketBindingHost(adapter) {
   return 'configureWebSocketBinding' in adapter && typeof adapter.configureWebSocketBinding === 'function';
@@ -40,6 +41,16 @@ function resolveMessageByteLength(message) {
 function isWebSocketUpgradeRequest(request) {
   return request.headers.get('upgrade')?.toLowerCase() === 'websocket';
 }
+function createCompletionSignal() {
+  let resolve;
+  const promise = new Promise(res => {
+    resolve = res;
+  });
+  return {
+    promise,
+    resolve
+  };
+}
 
 /**
  * Boots Bun-backed websocket gateways and manages their room lifecycle state.
@@ -49,11 +60,14 @@ class BunWebSocketGatewayLifecycleService {
   static {
     [_BunWebSocketGatewayL, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, HTTP_APPLICATION_ADAPTER, WEBSOCKET_OPTIONS_INTERNAL)], []).c;
   }
+  isShuttingDown = false;
+  pendingUpgradeOperations = new Set();
   pendingUpgradeReservations = 0;
   roomSockets = new Map();
   shutdownPromise;
   socketRegistry = new Map();
   socketRooms = new Map();
+  socketStates = new Map();
   constructor(runtimeContainer, compiledModules, logger, adapter, moduleOptions) {
     this.runtimeContainer = runtimeContainer;
     this.compiledModules = compiledModules;
@@ -90,7 +104,7 @@ class BunWebSocketGatewayLifecycleService {
   createBinding(descriptors) {
     const descriptorsByPath = this.groupDescriptorsByPath(descriptors);
     return {
-      fetch: (request, server) => this.handleUpgradeRequest(request, server, descriptorsByPath),
+      fetch: (request, server) => this.trackPendingUpgradeOperation(this.handleUpgradeRequest(request, server, descriptorsByPath)),
       websocket: {
         backpressureLimit: this.resolveBackpressureLimit(),
         close: (socket, code, reason) => {
@@ -108,7 +122,7 @@ class BunWebSocketGatewayLifecycleService {
           this.handleSocketMessage(socket, message);
         },
         open: socket => {
-          void this.bindConnectionHandlers(socket).catch(error => {
+          void this.trackPendingUpgradeOperation(this.bindConnectionHandlers(socket)).catch(error => {
             this.unregisterSocket(socket.data.state.socketId);
             this.logger.error('WebSocket gateway open lifecycle failed.', error, LIFECYCLE_LOG_CONTEXT);
             socket.close(1011, 'Internal server error');
@@ -155,7 +169,14 @@ class BunWebSocketGatewayLifecycleService {
         status: rejection.status
       });
     }
+    if (this.isShuttingDown) {
+      this.releaseUpgradeReservation();
+      return new Response('WebSocket server is shutting down.', {
+        status: 503
+      });
+    }
     const state = this.createConnectionHandlerState(request, [...descriptors]);
+    void this.trackPendingUpgradeOperation(state.openRegistrationPromise);
     let upgraded = false;
     try {
       upgraded = server.upgrade(request, {
@@ -164,10 +185,12 @@ class BunWebSocketGatewayLifecycleService {
         }
       });
     } catch (error) {
+      this.settleOpenRegistration(state);
       this.releaseUpgradeReservation();
       throw error;
     }
     if (!upgraded) {
+      this.settleOpenRegistration(state);
       this.releaseUpgradeReservation();
       return new Response(null, {
         status: 400
@@ -181,27 +204,73 @@ class BunWebSocketGatewayLifecycleService {
     } = socket.data;
     this.releaseUpgradeReservation();
     this.socketRegistry.set(state.socketId, socket);
-    await this.resolveConnectionGateways(state);
-    await this.runConnectHandlers(state, socket);
-    await this.finalizeConnectionBinding(state, socket);
+    this.socketStates.set(state.socketId, state);
+    this.settleOpenRegistration(state);
+    try {
+      await this.resolveConnectionGateways(state);
+      await this.runConnectHandlers(state, socket);
+      await this.finalizeConnectionBinding(state, socket);
+      if (this.isShuttingDown && socket.readyState === 1) {
+        socket.close(1001, 'Server shutting down');
+        await state.disconnectLifecyclePromise;
+      }
+    } finally {
+      if (!state.handlersReady && state.bufferedDisconnect) {
+        this.settleDisconnectLifecycle(state);
+      }
+      this.settleConnectLifecycle(state);
+    }
   }
   createConnectionHandlerState(request, descriptors) {
+    const connectLifecycle = createCompletionSignal();
+    const disconnectLifecycle = createCompletionSignal();
+    const openRegistration = createCompletionSignal();
     return {
       bufferedDisconnect: undefined,
       bufferedMessages: [],
       bufferedMessagesStartIndex: 0,
+      connectLifecycleSettled: false,
+      connectLifecyclePromise: connectLifecycle.promise,
       descriptors,
+      disconnectLifecycleSettled: false,
+      disconnectLifecyclePromise: disconnectLifecycle.promise,
       enqueuedMessageCount: 0,
       handlerQueue: Promise.resolve(),
       handlersReady: false,
+      openRegistrationSettled: false,
+      openRegistrationPromise: openRegistration.promise,
       processingMessageQueue: false,
       queuedMessages: [],
       queuedMessagesStartIndex: 0,
       request,
+      resolveOpenRegistration: openRegistration.resolve,
+      resolveConnectLifecycle: connectLifecycle.resolve,
+      resolveDisconnectLifecycle: disconnectLifecycle.resolve,
       resolved: [],
       socketId: crypto.randomUUID()
     };
   }
+  settleOpenRegistration(state) {
+    if (state.openRegistrationSettled) {
+      return;
+    }
+    state.openRegistrationSettled = true;
+    state.resolveOpenRegistration();
+  }
+  settleConnectLifecycle(state) {
+    if (state.connectLifecycleSettled) {
+      return;
+    }
+    state.connectLifecycleSettled = true;
+    state.resolveConnectLifecycle();
+  }
+  settleDisconnectLifecycle(state) {
+    if (state.disconnectLifecycleSettled) {
+      return;
+    }
+    state.disconnectLifecycleSettled = true;
+    state.resolveDisconnectLifecycle();
+  }
   getBufferedMessageCount(state) {
     return state.bufferedMessages.length - state.bufferedMessagesStartIndex;
   }
@@ -330,6 +399,8 @@ class BunWebSocketGatewayLifecycleService {
       await dispatchGatewayDisconnect(state.resolved, socket, disconnectEvent.code, disconnectEvent.reason, state.socketId, this.logger, LIFECYCLE_LOG_CONTEXT);
     }).catch(error => {
       this.logger.error('WebSocket gateway disconnect dispatch failed.', error, LIFECYCLE_LOG_CONTEXT);
+    }).finally(() => {
+      this.settleDisconnectLifecycle(state);
     });
   }
   async resolveConnectionGateways(state) {
@@ -379,6 +450,12 @@ class BunWebSocketGatewayLifecycleService {
     return configured;
   }
   async resolveUpgradeRejection(request, path) {
+    if (this.isShuttingDown) {
+      return {
+        body: 'WebSocket server is shutting down.',
+        status: 503
+      };
+    }
     if (!this.tryReserveUpgradeSlot()) {
       return {
         body: 'WebSocket connection limit exceeded.',
@@ -465,6 +542,13 @@ class BunWebSocketGatewayLifecycleService {
     }
     return Math.max(1, Math.ceil(configured / 1000));
   }
+  resolveShutdownTimeoutMs() {
+    const configured = this.moduleOptions.shutdown?.timeoutMs;
+    if (typeof configured !== 'number' || !Number.isFinite(configured) || configured <= 0) {
+      return DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS;
+    }
+    return Math.floor(configured);
+  }
   async shutdown() {
     if (this.shutdownPromise) {
       await this.shutdownPromise;
@@ -474,15 +558,110 @@ class BunWebSocketGatewayLifecycleService {
     await this.shutdownPromise;
   }
   async runShutdownLifecycle() {
+    this.isShuttingDown = true;
     if (hasBunWebSocketBindingHost(this.adapter)) {
       const bunAdapter = this.adapter;
       bunAdapter.configureWebSocketBinding(undefined);
     }
+    const shutdownTimeoutMs = this.resolveShutdownTimeoutMs();
+    await this.awaitPendingUpgradeOperations(shutdownTimeoutMs);
+    await this.closeActiveSockets(shutdownTimeoutMs);
     this.pendingUpgradeReservations = 0;
     this.socketRegistry.clear();
     this.socketRooms.clear();
+    this.socketStates.clear();
     this.roomSockets.clear();
   }
+  trackPendingUpgradeOperation(operation) {
+    let trackedOperation;
+    trackedOperation = operation.then(() => undefined, () => undefined).finally(() => {
+      if (trackedOperation) {
+        this.pendingUpgradeOperations.delete(trackedOperation);
+      }
+    });
+    this.pendingUpgradeOperations.add(trackedOperation);
+    return operation;
+  }
+  async awaitPendingUpgradeOperations(timeoutMs) {
+    if (this.pendingUpgradeOperations.size === 0) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while waiting for in-flight Bun websocket upgrades after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      Promise.all([...this.pendingUpgradeOperations]).then(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      }).catch(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      });
+    }).catch(error => {
+      this.logger.error(`Failed to wait for in-flight Bun websocket upgrades within ${String(timeoutMs)}ms.`, error, LIFECYCLE_LOG_CONTEXT);
+    });
+  }
+  async closeActiveSockets(timeoutMs) {
+    const activeSockets = [...this.socketRegistry.entries()];
+    if (activeSockets.length === 0) {
+      return;
+    }
+    const activeStates = activeSockets.map(([socketId]) => this.socketStates.get(socketId)).filter(state => state !== undefined);
+    for (const [, socket] of activeSockets) {
+      if (socket.readyState === 1) {
+        socket.close(1001, 'Server shutting down');
+      }
+    }
+    await this.awaitHandlerQueueDrain(activeStates, timeoutMs);
+  }
+  async awaitHandlerQueueDrain(states, timeoutMs) {
+    if (states.length === 0) {
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while closing Bun websocket connections after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      Promise.all(states.map(async state => {
+        await state.connectLifecyclePromise;
+        await state.disconnectLifecyclePromise;
+      })).then(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      }).catch(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        reject(error);
+      });
+    }).catch(error => {
+      this.logger.error(`Failed to close Bun websocket connections within ${String(timeoutMs)}ms.`, error, LIFECYCLE_LOG_CONTEXT);
+    });
+  }
   joinRoom(socketId, room) {
     let rooms = this.socketRooms.get(socketId);
     if (!rooms) {
@@ -539,6 +718,7 @@ class BunWebSocketGatewayLifecycleService {
   }
   unregisterSocket(socketId) {
     this.socketRegistry.delete(socketId);
+    this.socketStates.delete(socketId);
     const rooms = this.socketRooms.get(socketId);
     if (rooms) {
       for (const room of rooms) {

package/dist/cloudflare-workers/cloudflare-workers-service.d.ts

@@ -12,20 +12,26 @@ export declare class CloudflareWorkersWebSocketGatewayLifecycleService implement
     private readonly logger;
     private readonly adapter;
     private readonly moduleOptions;
+    private isShuttingDown;
+    private readonly pendingUpgradeOperations;
     private pendingUpgradeReservations;
     private readonly roomSockets;
     private shutdownPromise;
     private readonly socketRegistry;
     private readonly socketRooms;
+    private readonly socketStates;
     constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, adapter: HttpApplicationAdapter, moduleOptions: WebSocketModuleOptions);
     onApplicationBootstrap(): Promise<void>;
     private assertNoServerBackedGatewayOptIn;
     onApplicationShutdown(): Promise<void>;
     onModuleDestroy(): Promise<void>;
     private createBinding;
+    private handleUpgradeRequest;
     private groupDescriptorsByPath;
     private bindConnectionHandlers;
     private createConnectionHandlerState;
+    private settleConnectLifecycle;
+    private settleDisconnectLifecycle;
     private attachConnectionListeners;
     private getBufferedMessageCount;
     private getQueuedMessageCount;
@@ -50,8 +56,13 @@ export declare class CloudflareWorkersWebSocketGatewayLifecycleService implement
     private tryReserveUpgradeSlot;
     private releaseUpgradeReservation;
     private resolveMaxPayloadBytes;
+    private resolveShutdownTimeoutMs;
     private shutdown;
     private runShutdownLifecycle;
+    private trackPendingUpgradeOperation;
+    private awaitPendingUpgradeOperations;
+    private closeActiveSockets;
+    private awaitHandlerQueueDrain;
     joinRoom(socketId: string, room: string): void;
     leaveRoom(socketId: string, room: string): void;
     broadcastToRoom(room: string, event: string, data: unknown): void;

package/dist/cloudflare-workers/cloudflare-workers-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare-workers-service.d.ts","sourceRoot":"","sources":["../../src/cloudflare-workers/cloudflare-workers-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEzI,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAa3D,OAAO,KAAK,EAA8B,oBAAoB,EAA6B,MAAM,aAAa,CAAC;AAC/G,OAAO,KAAK,EAKV,sBAAsB,EACvB,MAAM,+BAA+B,CAAC;AA0GvC;;GAEG;AACH,qBACa,iDACX,YAAW,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,oBAAoB;IAS7F,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAXhC,OAAO,CAAC,0BAA0B,CAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgD;IAC/E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;gBAG3C,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,sBAAsB,EAC/B,aAAa,EAAE,sBAAsB;IAGlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB7C,OAAO,CAAC,gCAAgC;IAclC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,OAAO,CAAC,aAAa;IAqDrB,OAAO,CAAC,sBAAsB;YAmBhB,sBAAsB;IAgBpC,OAAO,CAAC,4BAA4B;IAqBpC,OAAO,CAAC,yBAAyB;IAyCjC,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,4BAA4B;IASpC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,qBAAqB;IA0C7B,OAAO,CAAC,sBAAsB;YAyDhB,iBAAiB;YAqBjB,gBAAgB;IAU9B,OAAO,CAAC,yBAAyB;YAsBnB,yBAAyB;YAczB,kBAAkB;YAgBlB,yBAAyB;YAUzB,8BAA8B;IAqB5C,OAAO,CAAC,YAAY;YAUN,uBAAuB;IAmDrC,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,8BAA8B;IAItC,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,yBAAyB;IAMjC,OAAO,CAAC,sBAAsB;YAUhB,QAAQ;YAUR,oBAAoB;IAWlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAmB9C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAc/C,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IA4BjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IAU/C,OAAO,CAAC,gBAAgB;CAoBzB"}
+{"version":3,"file":"cloudflare-workers-service.d.ts","sourceRoot":"","sources":["../../src/cloudflare-workers/cloudflare-workers-service.ts"],"names":[],"mappings":"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"}