@fluojs/websockets 1.0.0-beta.1

package/dist/bun/bun-service.js

@@ -0,0 +1,558 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { dispatchGatewayDisconnect, dispatchGatewayMessage, discoverGatewayDescriptors, isFinitePositiveInteger, normalizeGatewayPath, resolveGatewayInstance, runGatewayHandlers } from '../internal/shared.js';
+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 LIFECYCLE_LOG_CONTEXT = 'WebSocketGatewayLifecycleService';
+function hasBunWebSocketBindingHost(adapter) {
+  return 'configureWebSocketBinding' in adapter && typeof adapter.configureWebSocketBinding === 'function';
+}
+function resolveSupportedFetchStyleRealtimeCapability(adapter) {
+  if (typeof adapter.getRealtimeCapability !== 'function') {
+    throw new Error('Bun WebSocket gateway bootstrap requires an HTTP adapter with getRealtimeCapability(). Use @fluojs/platform-bun together with @fluojs/websockets/bun.');
+  }
+  const capability = adapter.getRealtimeCapability();
+  if (capability.kind !== 'fetch-style' || capability.contract !== 'raw-websocket-expansion') {
+    throw new Error('Bun WebSocket gateway bootstrap requires a fetch-style raw-websocket-expansion realtime capability from the selected HTTP adapter.');
+  }
+  if (capability.support !== 'supported') {
+    throw new Error(`Bun WebSocket gateway bootstrap requires supported fetch-style websocket hosting. ${capability.reason}`);
+  }
+  return capability;
+}
+function isHttpExceptionLike(error) {
+  return typeof error === 'object' && error !== null && 'message' in error && 'status' in error;
+}
+function resolveMessageByteLength(message) {
+  if (typeof message === 'string') {
+    return Buffer.byteLength(message);
+  }
+  return message.byteLength;
+}
+function isWebSocketUpgradeRequest(request) {
+  return request.headers.get('upgrade')?.toLowerCase() === 'websocket';
+}
+
+/**
+ * Boots Bun-backed websocket gateways and manages their room lifecycle state.
+ */
+let _BunWebSocketGatewayL;
+class BunWebSocketGatewayLifecycleService {
+  static {
+    [_BunWebSocketGatewayL, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, HTTP_APPLICATION_ADAPTER, WEBSOCKET_OPTIONS_INTERNAL)], []).c;
+  }
+  pendingUpgradeReservations = 0;
+  roomSockets = new Map();
+  shutdownPromise;
+  socketRegistry = new Map();
+  socketRooms = new Map();
+  constructor(runtimeContainer, compiledModules, logger, adapter, moduleOptions) {
+    this.runtimeContainer = runtimeContainer;
+    this.compiledModules = compiledModules;
+    this.logger = logger;
+    this.adapter = adapter;
+    this.moduleOptions = moduleOptions;
+  }
+  async onApplicationBootstrap() {
+    const descriptors = discoverGatewayDescriptors(this.compiledModules, this.logger, LIFECYCLE_LOG_CONTEXT);
+    if (descriptors.length === 0) {
+      return;
+    }
+    this.assertNoServerBackedGatewayOptIn(descriptors);
+    resolveSupportedFetchStyleRealtimeCapability(this.adapter);
+    if (!hasBunWebSocketBindingHost(this.adapter)) {
+      throw new Error('Bun WebSocket gateway bootstrap requires the selected adapter to expose Bun websocket binding configuration. Use @fluojs/platform-bun with @fluojs/websockets/bun.');
+    }
+    const bunAdapter = this.adapter;
+    bunAdapter.configureWebSocketBinding(this.createBinding(descriptors));
+  }
+  assertNoServerBackedGatewayOptIn(descriptors) {
+    const descriptor = descriptors.find(entry => entry.serverBacked !== undefined);
+    if (!descriptor) {
+      return;
+    }
+    throw new Error(`@WebSocketGateway({ serverBacked }) is not supported on @fluojs/websockets/bun. Gateway path ${descriptor.path} must use the default fetch-style request-upgrade host instead.`);
+  }
+  async onApplicationShutdown() {
+    await this.shutdown();
+  }
+  async onModuleDestroy() {
+    await this.shutdown();
+  }
+  createBinding(descriptors) {
+    const descriptorsByPath = this.groupDescriptorsByPath(descriptors);
+    return {
+      fetch: (request, server) => this.handleUpgradeRequest(request, server, descriptorsByPath),
+      websocket: {
+        backpressureLimit: this.resolveBackpressureLimit(),
+        close: (socket, code, reason) => {
+          this.unregisterSocket(socket.data.state.socketId);
+          this.handleSocketClose(socket, code, reason);
+        },
+        closeOnBackpressureLimit: this.moduleOptions.backpressure?.policy === 'close',
+        error: (socket, error) => {
+          this.unregisterSocket(socket.data.state.socketId);
+          this.logger.error('WebSocket gateway socket emitted an error.', error, LIFECYCLE_LOG_CONTEXT);
+        },
+        idleTimeout: this.resolveIdleTimeoutSeconds(),
+        maxPayloadLength: this.resolveMaxPayloadBytes(),
+        message: (socket, message) => {
+          this.handleSocketMessage(socket, message);
+        },
+        open: socket => {
+          void 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');
+          });
+        },
+        sendPings: this.moduleOptions.heartbeat?.enabled !== false
+      }
+    };
+  }
+  groupDescriptorsByPath(descriptors) {
+    const descriptorsByPath = new Map();
+    for (const descriptor of descriptors) {
+      const current = descriptorsByPath.get(descriptor.path);
+      if (current) {
+        current.push(descriptor);
+        continue;
+      }
+      descriptorsByPath.set(descriptor.path, [descriptor]);
+    }
+    return descriptorsByPath;
+  }
+  async handleUpgradeRequest(request, server, descriptorsByPath) {
+    let targetPath;
+    try {
+      targetPath = normalizeGatewayPath(new URL(request.url).pathname);
+    } catch {
+      return new Response(null, {
+        status: 400
+      });
+    }
+    const descriptors = descriptorsByPath.get(targetPath);
+    if (!descriptors) {
+      return undefined;
+    }
+    if (!isWebSocketUpgradeRequest(request)) {
+      return new Response(null, {
+        status: 426
+      });
+    }
+    const rejection = await this.resolveUpgradeRejection(request, targetPath);
+    if (rejection) {
+      return new Response(rejection.body ?? null, {
+        headers: rejection.headers,
+        status: rejection.status
+      });
+    }
+    const state = this.createConnectionHandlerState(request, [...descriptors]);
+    let upgraded = false;
+    try {
+      upgraded = server.upgrade(request, {
+        data: {
+          state
+        }
+      });
+    } catch (error) {
+      this.releaseUpgradeReservation();
+      throw error;
+    }
+    if (!upgraded) {
+      this.releaseUpgradeReservation();
+      return new Response(null, {
+        status: 400
+      });
+    }
+    return undefined;
+  }
+  async bindConnectionHandlers(socket) {
+    const {
+      state
+    } = socket.data;
+    this.releaseUpgradeReservation();
+    this.socketRegistry.set(state.socketId, socket);
+    await this.resolveConnectionGateways(state);
+    await this.runConnectHandlers(state, socket);
+    await this.finalizeConnectionBinding(state, socket);
+  }
+  createConnectionHandlerState(request, descriptors) {
+    return {
+      bufferedDisconnect: undefined,
+      bufferedMessages: [],
+      bufferedMessagesStartIndex: 0,
+      descriptors,
+      enqueuedMessageCount: 0,
+      handlerQueue: Promise.resolve(),
+      handlersReady: false,
+      processingMessageQueue: false,
+      queuedMessages: [],
+      queuedMessagesStartIndex: 0,
+      request,
+      resolved: [],
+      socketId: crypto.randomUUID()
+    };
+  }
+  getBufferedMessageCount(state) {
+    return state.bufferedMessages.length - state.bufferedMessagesStartIndex;
+  }
+  getQueuedMessageCount(state) {
+    return state.queuedMessages.length - state.queuedMessagesStartIndex;
+  }
+  maybeCompactBufferedMessages(state) {
+    if (state.bufferedMessagesStartIndex === 0 || state.bufferedMessagesStartIndex < state.bufferedMessages.length / 2) {
+      return;
+    }
+    state.bufferedMessages = state.bufferedMessages.slice(state.bufferedMessagesStartIndex);
+    state.bufferedMessagesStartIndex = 0;
+  }
+  clearBufferedMessages(state) {
+    state.bufferedMessages = [];
+    state.bufferedMessagesStartIndex = 0;
+  }
+  maybeCompactQueuedMessages(state) {
+    if (state.queuedMessagesStartIndex === 0 || state.queuedMessagesStartIndex < state.queuedMessages.length / 2) {
+      return;
+    }
+    state.queuedMessages = state.queuedMessages.slice(state.queuedMessagesStartIndex);
+    state.queuedMessagesStartIndex = 0;
+  }
+  clearQueuedMessages(state) {
+    state.queuedMessages = [];
+    state.queuedMessagesStartIndex = 0;
+    state.enqueuedMessageCount = 0;
+  }
+  handleSocketMessage(socket, message) {
+    const {
+      state
+    } = socket.data;
+    if (this.closeOversizedPayload(state.socketId, socket, message)) {
+      return;
+    }
+    if (!state.handlersReady) {
+      this.bufferIncomingMessage(state, socket, message);
+      return;
+    }
+    this.enqueueMessageDispatch(state, socket, message);
+  }
+  handleSocketClose(socket, code, reason) {
+    const {
+      state
+    } = socket.data;
+    const disconnectEvent = {
+      code,
+      reason
+    };
+    if (!state.handlersReady) {
+      state.bufferedDisconnect = disconnectEvent;
+      return;
+    }
+    this.enqueueDisconnectDispatch(state, socket, disconnectEvent);
+  }
+  bufferIncomingMessage(state, socket, message) {
+    const limit = isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+    const policy = this.moduleOptions.buffer?.overflowPolicy ?? 'drop-oldest';
+    if (this.getBufferedMessageCount(state) < limit) {
+      state.bufferedMessages.push(message);
+      return;
+    }
+    if (policy === 'close') {
+      socket.close(1013, 'Pending message buffer limit exceeded');
+      this.clearBufferedMessages(state);
+      this.logger.warn(`WebSocket connection ${state.socketId} exceeded pending message buffer limit (${String(limit)}). Connection closed.`, LIFECYCLE_LOG_CONTEXT);
+      return;
+    }
+    if (policy === 'drop-newest') {
+      this.logger.warn(`WebSocket connection ${state.socketId} dropped an incoming message due to pending buffer limit (${String(limit)}).`, LIFECYCLE_LOG_CONTEXT);
+      return;
+    }
+    state.bufferedMessagesStartIndex += 1;
+    this.maybeCompactBufferedMessages(state);
+    state.bufferedMessages.push(message);
+    this.logger.warn(`WebSocket connection ${state.socketId} dropped the oldest pending message due to buffer limit (${String(limit)}).`, LIFECYCLE_LOG_CONTEXT);
+  }
+  enqueueMessageDispatch(state, socket, message) {
+    const limit = isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+    const policy = this.moduleOptions.buffer?.overflowPolicy ?? 'drop-oldest';
+    if (this.getQueuedMessageCount(state) >= limit) {
+      if (policy === 'close') {
+        socket.close(1013, 'Ready-state message queue limit exceeded');
+        this.clearQueuedMessages(state);
+        this.unregisterSocket(state.socketId);
+        this.logger.warn(`WebSocket connection ${state.socketId} exceeded ready-state message queue limit (${String(limit)}). Connection closed.`, LIFECYCLE_LOG_CONTEXT);
+        return;
+      }
+      if (policy === 'drop-oldest') {
+        state.queuedMessagesStartIndex += 1;
+        this.maybeCompactQueuedMessages(state);
+        this.logger.warn(`WebSocket connection ${state.socketId} dropped the oldest ready-state message because queue limit (${String(limit)}) was reached.`, LIFECYCLE_LOG_CONTEXT);
+      } else {
+        this.logger.warn(`WebSocket connection ${state.socketId} dropped a ready-state message because queue limit (${String(limit)}) was reached.`, LIFECYCLE_LOG_CONTEXT);
+        return;
+      }
+    }
+    state.queuedMessages.push(message);
+    state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+    if (state.processingMessageQueue) {
+      return;
+    }
+    state.processingMessageQueue = true;
+    state.handlerQueue = this.drainMessageQueue(state, socket).finally(() => {
+      state.processingMessageQueue = false;
+      state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+    }).catch(error => {
+      this.logger.error('WebSocket gateway message dispatch failed.', error, LIFECYCLE_LOG_CONTEXT);
+    });
+  }
+  async drainMessageQueue(state, socket) {
+    while (state.queuedMessagesStartIndex < state.queuedMessages.length) {
+      const nextMessage = state.queuedMessages[state.queuedMessagesStartIndex];
+      state.queuedMessagesStartIndex += 1;
+      state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+      if (nextMessage === undefined) {
+        continue;
+      }
+      await dispatchGatewayMessage(state.resolved, socket, state.request, nextMessage, this.logger, LIFECYCLE_LOG_CONTEXT);
+    }
+    this.clearQueuedMessages(state);
+  }
+  enqueueDisconnectDispatch(state, socket, disconnectEvent) {
+    state.handlerQueue = state.handlerQueue.then(async () => {
+      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);
+    });
+  }
+  async resolveConnectionGateways(state) {
+    const resolved = [];
+    for (const descriptor of state.descriptors) {
+      const instance = await resolveGatewayInstance(this.runtimeContainer, descriptor, this.logger, LIFECYCLE_LOG_CONTEXT);
+      if (instance !== undefined) {
+        resolved.push({
+          descriptor,
+          instance
+        });
+      }
+    }
+    state.resolved = resolved;
+  }
+  async runConnectHandlers(state, socket) {
+    for (const {
+      descriptor,
+      instance
+    } of state.resolved) {
+      await runGatewayHandlers(instance, descriptor, 'connect', [socket, state.request, state.socketId], this.logger, LIFECYCLE_LOG_CONTEXT);
+    }
+  }
+  async finalizeConnectionBinding(state, socket) {
+    state.handlersReady = true;
+    this.replayBufferedConnectionEvents(state, socket);
+    await state.handlerQueue;
+  }
+  replayBufferedConnectionEvents(state, socket) {
+    for (let index = state.bufferedMessagesStartIndex; index < state.bufferedMessages.length; index += 1) {
+      const message = state.bufferedMessages[index];
+      if (message !== undefined) {
+        this.enqueueMessageDispatch(state, socket, message);
+      }
+    }
+    if (state.bufferedDisconnect) {
+      this.enqueueDisconnectDispatch(state, socket, state.bufferedDisconnect);
+      state.bufferedDisconnect = undefined;
+    }
+    this.clearBufferedMessages(state);
+  }
+  resolveBackpressureLimit() {
+    const configured = this.moduleOptions.backpressure?.maxBufferedAmountBytes;
+    if (!isFinitePositiveInteger(configured)) {
+      return 1_048_576;
+    }
+    return configured;
+  }
+  async resolveUpgradeRejection(request, path) {
+    if (!this.tryReserveUpgradeSlot()) {
+      return {
+        body: 'WebSocket connection limit exceeded.',
+        status: 429
+      };
+    }
+    const guard = this.moduleOptions.upgrade?.guard;
+    if (!guard) {
+      return undefined;
+    }
+    try {
+      const result = await guard(request, {
+        activeConnectionCount: this.resolveReservedConnectionCount() - 1,
+        path
+      });
+      if (result === false) {
+        this.releaseUpgradeReservation();
+        return {
+          body: 'WebSocket upgrade rejected.',
+          status: 403
+        };
+      }
+      if (typeof result === 'object' && result !== null && 'status' in result) {
+        this.releaseUpgradeReservation();
+        return result;
+      }
+      return undefined;
+    } catch (error) {
+      this.releaseUpgradeReservation();
+      if (isHttpExceptionLike(error)) {
+        return {
+          body: error.message,
+          status: error.status
+        };
+      }
+      throw error;
+    }
+  }
+  closeOversizedPayload(socketId, socket, message) {
+    const maxPayloadBytes = this.resolveMaxPayloadBytes();
+    if (resolveMessageByteLength(message) <= maxPayloadBytes) {
+      return false;
+    }
+    socket.close(1009, 'Payload too large');
+    this.logger.warn(`WebSocket connection ${socketId} exceeded payload limit (${String(maxPayloadBytes)} bytes). Connection closed.`, LIFECYCLE_LOG_CONTEXT);
+    return true;
+  }
+  resolveMaxConnectionCount() {
+    const configured = this.moduleOptions.limits?.maxConnections;
+    if (!isFinitePositiveInteger(configured)) {
+      return DEFAULT_MAX_WEBSOCKET_CONNECTIONS;
+    }
+    return configured;
+  }
+  resolveReservedConnectionCount() {
+    return this.socketRegistry.size + this.pendingUpgradeReservations;
+  }
+  tryReserveUpgradeSlot() {
+    if (this.resolveReservedConnectionCount() >= this.resolveMaxConnectionCount()) {
+      return false;
+    }
+    this.pendingUpgradeReservations += 1;
+    return true;
+  }
+  releaseUpgradeReservation() {
+    if (this.pendingUpgradeReservations > 0) {
+      this.pendingUpgradeReservations -= 1;
+    }
+  }
+  resolveMaxPayloadBytes() {
+    const configured = this.moduleOptions.limits?.maxPayloadBytes;
+    if (!isFinitePositiveInteger(configured)) {
+      return DEFAULT_MAX_WEBSOCKET_PAYLOAD_BYTES;
+    }
+    return configured;
+  }
+  resolveIdleTimeoutSeconds() {
+    if (this.moduleOptions.heartbeat?.enabled === false) {
+      return 0;
+    }
+    const configured = this.moduleOptions.heartbeat?.timeoutMs;
+    if (!isFinitePositiveInteger(configured)) {
+      return 120;
+    }
+    return Math.max(1, Math.ceil(configured / 1000));
+  }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      await this.shutdownPromise;
+      return;
+    }
+    this.shutdownPromise = this.runShutdownLifecycle();
+    await this.shutdownPromise;
+  }
+  async runShutdownLifecycle() {
+    if (hasBunWebSocketBindingHost(this.adapter)) {
+      const bunAdapter = this.adapter;
+      bunAdapter.configureWebSocketBinding(undefined);
+    }
+    this.pendingUpgradeReservations = 0;
+    this.socketRegistry.clear();
+    this.socketRooms.clear();
+    this.roomSockets.clear();
+  }
+  joinRoom(socketId, room) {
+    let rooms = this.socketRooms.get(socketId);
+    if (!rooms) {
+      rooms = new Set();
+      this.socketRooms.set(socketId, rooms);
+    }
+    rooms.add(room);
+    let sockets = this.roomSockets.get(room);
+    if (!sockets) {
+      sockets = new Set();
+      this.roomSockets.set(room, sockets);
+    }
+    sockets.add(socketId);
+  }
+  leaveRoom(socketId, room) {
+    const rooms = this.socketRooms.get(socketId);
+    rooms?.delete(room);
+    if (rooms && rooms.size === 0) {
+      this.socketRooms.delete(socketId);
+    }
+    const sockets = this.roomSockets.get(room);
+    sockets?.delete(socketId);
+    if (sockets && sockets.size === 0) {
+      this.roomSockets.delete(room);
+    }
+  }
+  broadcastToRoom(room, event, data) {
+    const socketIds = this.roomSockets.get(room);
+    if (!socketIds) {
+      return;
+    }
+    const message = JSON.stringify({
+      data,
+      event
+    });
+    for (const socketId of socketIds) {
+      const socket = this.socketRegistry.get(socketId);
+      if (!socket || socket.readyState !== 1) {
+        continue;
+      }
+      const result = socket.send(message);
+      if (result === 0) {
+        this.unregisterSocket(socketId);
+        this.logger.warn(`WebSocket connection ${socketId} dropped a room broadcast because the socket was unavailable.`, LIFECYCLE_LOG_CONTEXT);
+      }
+    }
+  }
+  getRooms(socketId) {
+    const rooms = this.socketRooms.get(socketId);
+    if (!rooms) {
+      return new Set();
+    }
+    return new Set(rooms);
+  }
+  unregisterSocket(socketId) {
+    this.socketRegistry.delete(socketId);
+    const rooms = this.socketRooms.get(socketId);
+    if (rooms) {
+      for (const room of rooms) {
+        const sockets = this.roomSockets.get(room);
+        sockets?.delete(socketId);
+        if (sockets && sockets.size === 0) {
+          this.roomSockets.delete(room);
+        }
+      }
+      this.socketRooms.delete(socketId);
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _BunWebSocketGatewayL as BunWebSocketGatewayLifecycleService };

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

@@ -0,0 +1,58 @@
+import type { WebSocketModuleOptions as SharedWebSocketModuleOptions } from '../types.js';
+export type BunWebSocketMessage = string | ArrayBuffer | Uint8Array;
+export interface BunServerWebSocket<TData = unknown> {
+    readonly data: TData;
+    readonly readyState: number;
+    readonly remoteAddress: string;
+    readonly subscriptions: string[];
+    close(code?: number, reason?: string): void;
+    cork(callback: (socket: BunServerWebSocket<TData>) => void): void;
+    isSubscribed(topic: string): boolean;
+    publish(topic: string, message: BunWebSocketMessage): void;
+    send(message: BunWebSocketMessage, compress?: boolean): number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+}
+export interface BunServerLike {
+    fetch?(request: Request): Response | Promise<Response> | undefined | Promise<Response | undefined>;
+    hostname?: string;
+    port?: number;
+    stop(closeActiveConnections?: boolean): void;
+    upgrade<TData = unknown>(request: Request, options?: {
+        data?: TData;
+        headers?: HeadersInit;
+    }): boolean;
+    url?: URL;
+}
+export interface BunWebSocketHandler<TData = unknown> {
+    backpressureLimit?: number;
+    close?(socket: BunServerWebSocket<TData>, code: number, reason: string): void | Promise<void>;
+    closeOnBackpressureLimit?: boolean;
+    data?: TData;
+    drain?(socket: BunServerWebSocket<TData>): void | Promise<void>;
+    error?(socket: BunServerWebSocket<TData>, error: Error): void | Promise<void>;
+    idleTimeout?: number;
+    maxPayloadLength?: number;
+    message?(socket: BunServerWebSocket<TData>, message: BunWebSocketMessage): void | Promise<void>;
+    open?(socket: BunServerWebSocket<TData>): void | Promise<void>;
+    perMessageDeflate?: boolean | {
+        compress?: boolean | '128KB' | '16KB' | '256KB' | '32KB' | '3KB' | '4KB' | '64KB' | '8KB' | 'dedicated' | 'disable' | 'shared';
+        decompress?: boolean | '128KB' | '16KB' | '256KB' | '32KB' | '3KB' | '4KB' | '64KB' | '8KB' | 'dedicated' | 'disable' | 'shared';
+    };
+    publishToSelf?: boolean;
+    sendPings?: boolean;
+}
+export interface BunWebSocketBinding<TData = unknown> {
+    fetch(request: Request, server: BunServerLike): Response | Promise<Response> | undefined | Promise<Response | undefined>;
+    websocket: BunWebSocketHandler<TData>;
+}
+export interface BunWebSocketBindingHost {
+    configureWebSocketBinding<TData>(binding: BunWebSocketBinding<TData> | undefined): void;
+}
+export type TypedOnMessageHandler<TEvents extends Record<string, unknown>, K extends keyof TEvents> = (payload: TEvents[K], socket: BunServerWebSocket, request: Request) => void | Promise<void>;
+export interface WebSocketGatewayContext {
+    request: Request;
+    socket: BunServerWebSocket;
+}
+export type WebSocketModuleOptions = SharedWebSocketModuleOptions;
+//# sourceMappingURL=bun-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bun-types.d.ts","sourceRoot":"","sources":["../../src/bun/bun-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,IAAI,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAE1F,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpE,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,OAAO;IACjD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAClE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC3D,IAAI,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC/D,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,sBAAsB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7C,OAAO,CAAC,KAAK,GAAG,OAAO,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,KAAK,CAAC;QACb,OAAO,CAAC,EAAE,WAAW,CAAC;KACvB,GACA,OAAO,CAAC;IACX,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED,MAAM,WAAW,mBAAmB,CAAC,KAAK,GAAG,OAAO;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,KAAK,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,IAAI,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,iBAAiB,CAAC,EACd,OAAO,GACP;QACE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;QAC/H,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;KAClI,CAAC;IACN,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB,CAAC,KAAK,GAAG,OAAO;IAClD,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IACzH,SAAS,EAAE,mBAAmB,CAAC,KAAK,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,uBAAuB;IACtC,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,mBAAmB,CAAC,KAAK,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;CACzF;AAED,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,OAAO,IAAI,CACpG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,OAAO,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,4BAA4B,CAAC"}

package/dist/bun/bun-types.js

@@ -0,0 +1 @@
+export {};

package/dist/bun/bun.d.ts

@@ -0,0 +1,4 @@
+export * from './bun-module.js';
+export * from './bun-service.js';
+export * from './bun-types.js';
+//# sourceMappingURL=bun.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../../src/bun/bun.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/bun/bun.js

@@ -0,0 +1,3 @@
+export * from './bun-module.js';
+export * from './bun-service.js';
+export * from './bun-types.js';

package/dist/bun.d.ts

@@ -0,0 +1,2 @@
+export * from './bun/bun.js';
+//# sourceMappingURL=bun.d.ts.map

package/dist/bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.d.ts","sourceRoot":"","sources":["../src/bun.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

package/dist/bun.js

@@ -0,0 +1 @@
+export * from './bun/bun.js';

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

@@ -0,0 +1,15 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { WebSocketModuleOptions } from './cloudflare-workers-types.js';
+/**
+ * Explicit Cloudflare Workers websocket module entrypoint.
+ */
+export declare class CloudflareWorkersWebSocketModule {
+    /**
+     * Registers the Cloudflare Workers websocket lifecycle service for request-upgrade gateway hosting.
+     *
+     * @param options Websocket gateway runtime options for guards, limits, heartbeat, and shutdown behavior.
+     * @returns A runtime module definition scoped to the Cloudflare Workers websocket adapter.
+     */
+    static forRoot(options?: WebSocketModuleOptions): ModuleType;
+}
+//# sourceMappingURL=cloudflare-workers-module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-workers-module.d.ts","sourceRoot":"","sources":["../../src/cloudflare-workers/cloudflare-workers-module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAY5E;;GAEG;AACH,qBAAa,gCAAgC;IAC3C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU;CAOjE"}