@znight/websocket 0.0.0 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ugho STEPHAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# @znight/websocket
+
+WebSocket **gateways** for Znight, served by the `HttpPlugin` server on the same port. A gateway is
+a provider class whose methods handle the connection lifecycle (`@OnConnect`, `@OnDisconnect`) and
+inbound events (`@OnMessage`), with Standard Schema validation, replies, rooms, broadcasts,
+backpressure, heartbeats and a graceful shutdown. Like every Znight feature, gateways are resolved
+**at build time**: the compiler extension reads the decorators, reports invalid gateways
+(ZNIGHT050...) and generates one `invoke` function per handler.
+
+- The handshake **is an HTTP request**: request scope, `http:request` hook, `HttpPlugin` global
+  guards, `@UseHandshakeGuard` guards, exception mappers, `trustProxy`. The request scope lasts as
+  long as the connection: request-scoped providers filled by a guard are there for every message.
+- One server, every adapter: `node`, `fastify`, `express` and `hono` on Node.js and Bun. The `ws`
+  transport serves `node:http` servers (Bun ships its own `ws`); Bun's native WebSocket serves
+  `honoAdapter()` on `Bun.serve()`.
+- A tiny wire protocol for `events` gateways (JSON `{ event, data?, id? }`), and `raw` gateways for
+  anything else.
+
+## Install
+
+```sh
+bun add @znight/core @znight/http @znight/websocket zod
+npm i ws          # Node.js only: Bun provides it
+bun add -d @znight/compiler vite
+```
+
+```ts
+import { Application } from '@znight/core'
+import { HttpPlugin } from '@znight/http'
+import { WebSocketPlugin } from '@znight/websocket'
+import { __ZNIGHT_METADATA__ } from './.znight/container.generated.js'
+
+const app = await Application.create({
+  metadata: __ZNIGHT_METADATA__,
+  plugins: [HttpPlugin.configure({ port: 3000 }), WebSocketPlugin.configure({ maxPayload: '64kb' })],
+})
+await app.start()
+```
+
+## Gateways
+
+```ts
+import { z } from 'zod'
+import {
+  Conn,
+  Gateway,
+  OnConnect,
+  OnDisconnect,
+  OnMessage,
+  Payload,
+  WsException,
+  WsServer,
+  type WsConnection,
+} from '@znight/websocket'
+
+export const JoinRoom = z.object({ room: z.string().regex(/^[a-z0-9-]{1,32}$/) })
+export type JoinRoom = z.output<typeof JoinRoom>
+export const SendMessage = z.object({ room: z.string(), text: z.string().min(1).max(2000) })
+export type SendMessage = z.output<typeof SendMessage>
+
+interface ChatEvents {
+  'message.new': { readonly room: string; readonly text: string }
+}
+
+@Gateway({ path: '/chat', protocols: ['chat.v1'], rateLimit: { messages: 30, intervalMs: 1_000 } })
+export class ChatGateway {
+  constructor(private readonly ws: WsServer) {}
+
+  @OnConnect()
+  connected(@Conn() conn: WsConnection): void {
+    conn.join('lobby')
+  }
+
+  @OnMessage('room.join')
+  join(@Conn() conn: WsConnection, @Payload(JoinRoom) input: JoinRoom): { members: number } {
+    conn.join(input.room)
+    return { members: this.ws.of(ChatGateway).members(input.room).size } // the reply
+  }
+
+  @OnMessage('message.send')
+  send(@Conn() conn: WsConnection, @Payload(SendMessage) input: SendMessage): void {
+    if (!conn.rooms.has(input.room)) throw new WsException('FORBIDDEN', `Join "${input.room}" first`)
+    this.ws.of<ChatEvents>(ChatGateway).to(input.room).emit('message.new', input) // encoded once
+  }
+
+  @OnDisconnect()
+  disconnected(): void {}
+}
+```
+
+| Decorator                               | Target        | Description                                                                                         |
+| --------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
+| `@Gateway(path?)` / `@Gateway(options)` | class         | A provider handling the connections of `path` (default `/`), joined to the `HttpPlugin` prefix      |
+| `@OnConnect()`                          | method        | Runs once the handshake succeeded, before any message. Throwing closes the connection               |
+| `@OnMessage(event?)`                    | method        | Handles an event; without event, the default handler (unknown events, every frame of a raw gateway) |
+| `@OnDisconnect()`                       | method        | Runs once per connection whose `@OnConnect` completed, after its running handlers                   |
+| `@Payload(schema?)`                     | parameter     | The message `data` (`events`) or the frame (`raw`), validated by a Standard Schema                  |
+| `@Conn()`                               | parameter     | The `WsConnection`                                                                                  |
+| `@Ctx()`                                | parameter     | The `WsMessageContext` of the message                                                               |
+| `@UseHandshakeGuard(...guards)`         | class         | HTTP guards (`CanActivate`) of the handshake, after the `HttpPlugin` global guards                  |
+| `@UseMessageGuard(...guards)`           | class, method | `WsGuard`s run before each handler (plugin, class, then method)                                     |
+| `createRouteDecorator` decorators       | class, method | Class: handshake and messages; method: its messages (nearest wins)                                  |
+
+`@Gateway` options (static): `path`, `scope` (`'singleton'` or `'request'`: one instance per
+connection, which may inject `WsConnection`), `protocol` (`'events'` or `'raw'`), `protocols`
+(accepted subprotocols; a client offering none of them is refused with `400`), `maxPayload`
+(`'64kb'`), `concurrency` (messages of a connection handled at once, default `1`: in order),
+`rateLimit` (`{ messages, intervalMs, onLimit?: 'reject' | 'close' }`) and `backpressure`
+(`{ limit?, onLimit?: 'close' | 'drop' }`).
+
+Handlers may be `async`; their return value is the reply of a message that carried an `id`.
+Handlers are inherited from abstract base classes. Core AOP (`@Logged`, `@Traced`, `@Intercept`)
+applies to handlers.
+
+## Wire protocol (`events` gateways)
+
+| Direction       | Frame                                                                          | Meaning                                   |
+| --------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| client → server | `{ "event": "message.send", "data": {...} }`                                   | fire and forget                           |
+| client → server | `{ "event": "room.join", "data": {...}, "id": 7 }`                             | a request: one reply                      |
+| server → client | `{ "id": 7, "data": {...} }` / `{ "id": 7, "error": { code, message } }`       | reply                                     |
+| server → client | `{ "event": "message.new", "data": {...} }`                                    | server event (`emit`, broadcasts)         |
+| server → client | `{ "event": "$error", "data": { "event": ..., "code": ..., "message": ... } }` | failure of a message without `id`         |
+| client ↔ server | `{ "event": "$ping", "id": 1 }` → `{ "id": 1, "data": { "t": ... } }`          | application ping (never reaches handlers) |
+
+Error codes: `BAD_FRAME`, `UNSUPPORTED_FRAME`, `BAD_REQUEST` (validation, `details: [{ path,
+message }]`), `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `UNPROCESSABLE`, `RATE_LIMITED`,
+`UNKNOWN_EVENT`, `TIMEOUT`, `INTERNAL` (message hidden unless `exposeErrors`). A `WsException(code,
+message?, details?, { close? })` answers its code; an `HttpException` thrown by a service is mapped
+from its status. In `@OnConnect`, a `WsException` closes with its `close` code (default `1008`), an
+`HttpException` with `4000 + status`, anything else with `1011`.
+
+`raw` gateways have no envelope: the default handler receives each frame (`string` or
+`Uint8Array`), `conn.send()` sends frames as they are.
+
+## Connections, rooms and broadcasts
+
+`WsConnection<TData, Events>`: `id`, `gateway`, `requestId`, `handshake` (the `HttpContext`),
+`params`, `protocol`, `data` (per-connection state), `rooms`, `readyState`, `bufferedAmount`,
+`signal`, `closeInfo` (set before `@OnDisconnect`), `emit(event, data)`, `send(frame)`,
+`join(room)`, `leave(room)`, `to(room)` (the other members), `drained()`, `close(code?, reason?)`,
+`terminate()`. `emit` and `send` return `'sent'`, `'queued'` or `'dropped'`.
+
+`WsServer` (injectable): `of(GatewayClass | '/path')` returns a lazy `GatewayChannel` (`path`,
+`size`, `connection(id)`, `connections()`, `members(room)`, `rooms()`, `to(room)`, `except(...)`,
+`emit`, `send`) and `connections` counts every connection. A broadcast encodes its frame once;
+each recipient applies its own backpressure policy. Rooms are per gateway and per process.
+
+## Plugin options
+
+`WebSocketPlugin.configure(options | (container) => options)` (name `websocket`):
+
+| Option               | Default                                                            | Description                                                                                       |
+| -------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `transport`          | `'auto'`                                                           | `wsTransport()` (`@znight/websocket/ws`) or `bunTransport()` (`@znight/websocket/bun`)            |
+| `origins`            | `'same-origin'`                                                    | `'*'`, exact origins and anchored `RegExp`s, or `(origin, ctx) => boolean`; checked first (`403`) |
+| `maxPayload`         | `'1mb'`                                                            | Largest inbound message; gateways may lower it (`1009`)                                           |
+| `maxConnections`     | `Infinity`                                                         | Open connections per process (handshakes in flight count); above, `503` with `retry-after: 1`     |
+| `maxPendingMessages` | `32`                                                               | Inbound queue per connection before reading pauses                                                |
+| `backpressure`       | `{ limit: '1mb', onLimit: 'close' }`                               | Outbound buffer per connection: close with `1013`, or `'drop'` frames                             |
+| `heartbeat`          | `{ intervalMs: 30_000 }`                                           | `false` disables it; silent connections are terminated after two intervals                        |
+| `handshakeTimeoutMs` | `10_000`                                                           | `408` for handshakes whose guards did not answer                                                  |
+| `handlerTimeoutMs`   | `30_000`                                                           | Per message and `@OnConnect`: `TIMEOUT`, `ctx.signal` aborted                                     |
+| `closeTimeoutMs`     | `2_000`                                                            | Wait for the client's close frame before terminating                                              |
+| `messageGuards`      | `[]`                                                               | Global `WsGuard`s (classes or instances)                                                          |
+| `exceptionMappers`   | `[]`                                                               | `WsExceptionMapper`s: `map(error, ctx) → WsException \| undefined`                                |
+| `exposeErrors`       | `false`                                                            | Send the message of unexpected errors                                                             |
+| `shutdown`           | `{ code: 1001, reason: 'Server shutting down', timeoutMs: 3_000 }` | Graceful shutdown: close frames, then terminate                                                   |
+
+The instance exposes `server` (`WsServer`), `transport`, `gateways`, `connections`, `stats()`
+(`{ connections, opened, closed, messagesIn, messagesOut, bytesIn, bytesOut, dropped,
+slowConsumerCloses }`), `connect(path, options?)` and `initRoots()`.
+
+## Testing
+
+```ts
+import { TestApp, WsHandshakeError } from '@znight/testing'
+import { HttpPlugin } from '@znight/http'
+import { WebSocketPlugin } from '@znight/websocket'
+
+await using app = await TestApp.create({
+  metadata,
+  plugins: [HttpPlugin.configure({ port: 0 }), WebSocketPlugin.configure()],
+})
+await using alice = await app.connect('/chat', { protocols: ['chat.v1'] }) // in memory, real handshake
+expect(await alice.request('room.join', { room: 'general' })).toEqual({ members: 1 })
+await expect(app.connect('/chat', { origin: 'https://evil.example' })).rejects.toBeInstanceOf(WsHandshakeError)
+```
+
+`connectWebSocket(url, { headers?, protocols? })` of `@znight/testing` gives the same client over
+the network. For unit tests, `@znight/websocket/testing` provides fakes:
+
+```ts
+import { createTestConnection, createTestServer } from '@znight/websocket/testing'
+
+const server = createTestServer({ paths: [[ChatGateway, '/chat']] }) // records broadcasts
+const conn = createTestConnection({ data: { user: 'alice' }, rooms: ['general'] }) // records emitted frames
+```
+
+## Compiler contract
+
+The compiler extension (`@znight/websocket/compiler`) generates `metadata.extensions.websocket`
+(gateways sorted by token, handlers in declaration order, bases first) and imports from
+`@znight/websocket`:
+
+- `validatePayload(schema, value)`: Standard Schema validation of `@Payload(schema)`; returns the
+  schema output (synchronously for synchronous schemas) or throws `WsValidationException`
+  (`BAD_REQUEST`, `details: [{ path, message }]`). Stable.
+- the types `WsConnection` and `WsMessageContext` of the generated `invoke` functions.
+
+```ts
+['invoke']: async (g: ChatGateway, m: WsMessageContext) =>
+  g.join(m.connection as never, await validatePayload(JoinRoom, m.data)),
+```
+
+Diagnostics: ZNIGHT050 (invalid gateway: options, duplicate events, reserved `$` events, several
+`@OnConnect`, undecorated parameters, `@Payload` outside `@OnMessage`...), ZNIGHT005 (decorator
+misuse, parameter decorators imported from another package), ZNIGHT007 (paths), ZNIGHT017
+(`@Payload()` without schema on a structured type), ZNIGHT003 (a singleton gateway injecting
+`WsConnection`), ZNIGHT023 (required route decisions). At boot: ZNIGHT050 (options, metadata) and
+ZNIGHT051 (no `HttpPlugin`, no upgrade support, `ws` missing, mismatched transport).
+
+## Limitations
+
+- `conn.handshake` keeps the native request of the handshake.
+- Rooms are per process: broadcast across instances through `@znight/messaging`.
+- No HTTP/2 or HTTP/3 WebSockets, no Socket.IO protocol.

package/dist/bun.d.mts

@@ -0,0 +1,4 @@
+import { o as WebSocketTransport } from "./transport-xnJqvB93.mjs";
+/** The Bun transport: completes the `bun` upgrades of `Bun.serve()`. */
+export declare function bunTransport(): WebSocketTransport;
+//# sourceMappingURL=bun.d.mts.map

package/dist/bun.mjs

@@ -0,0 +1,112 @@
+import { ErrorCode, ZnightError } from "@znight/core";
+// src/transports/bun.ts
+/** One Bun connection; bound before `server.upgrade()`, since `open` may run inside it. */
+var BunTransportSocket = class {
+	#events;
+	#registry;
+	#ws;
+	#closed = false;
+	constructor(events, registry) {
+		this.#events = events;
+		this.#registry = registry;
+	}
+	get bufferedAmount() {
+		return this.#ws?.getBufferedAmount() ?? 0;
+	}
+	get extensions() {
+		return this.#ws?.extensions ?? "";
+	}
+	send(frame, _binary) {
+		if (this.#ws === void 0 || this.#closed) return "dropped";
+		const result = this.#ws.send(frame);
+		if (result > 0) return "sent";
+		return result === -1 ? "queued" : "dropped";
+	}
+	ping() {
+		this.#ws?.ping();
+	}
+	pause() {
+		if (this.#ws?.pause === void 0) return false;
+		this.#ws.pause();
+		return true;
+	}
+	resume() {
+		this.#ws?.resume?.();
+	}
+	close(code, reason) {
+		this.#ws?.close(code, reason);
+	}
+	terminate() {
+		this.#ws?.terminate();
+	}
+	onOpen(ws) {
+		this.#ws = ws;
+		this.#registry.add(this);
+	}
+	onMessage(message) {
+		this.#events.message(message, typeof message !== "string");
+	}
+	onClose(code, reason) {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#registry.delete(this);
+		this.#events.close(code, reason);
+	}
+	onDrain() {
+		this.#events.drain();
+	}
+	onPong() {
+		this.#events.pong();
+	}
+};
+/** The Bun transport: completes the `bun` upgrades of `Bun.serve()`. */
+function bunTransport() {
+	let settings = {
+		maxPayload: 1048576,
+		backpressureLimit: 1048576,
+		heartbeatMs: 0
+	};
+	const sockets = /* @__PURE__ */ new Set();
+	return {
+		name: "bun",
+		accepts: "bun",
+		configure(next) {
+			settings = next;
+		},
+		bunWebSocket() {
+			return {
+				maxPayloadLength: settings.maxPayload,
+				backpressureLimit: settings.backpressureLimit,
+				closeOnBackpressureLimit: false,
+				sendPings: settings.heartbeatMs > 0,
+				idleTimeout: settings.heartbeatMs > 0 ? Math.min(960, Math.ceil(settings.heartbeatMs * 2 / 1e3)) : 0
+			};
+		},
+		accept(native, init, events) {
+			if (native.kind !== "bun") throw new ZnightError(ErrorCode.WebSocketTransportUnavailable, `bunTransport() completes Bun.serve() upgrades, not ${native.kind} upgrades`, { hints: ["Use wsTransport() with the node:http adapters"] });
+			const socket = new BunTransportSocket(events, sockets);
+			const handlers = {
+				open: (ws) => socket.onOpen(ws),
+				message: (_ws, message) => socket.onMessage(message),
+				close: (_ws, code, reason) => socket.onClose(code, reason),
+				drain: () => socket.onDrain(),
+				pong: () => socket.onPong()
+			};
+			const headers = {};
+			for (const [name, value] of Object.entries(init.headers)) headers[name] = typeof value === "string" ? value : value.join(", ");
+			if (init.protocol !== "") headers["sec-websocket-protocol"] = init.protocol;
+			if (!native.server.upgrade(native.request, {
+				data: handlers,
+				headers
+			})) throw new Error("Bun.serve() refused the WebSocket upgrade");
+			return socket;
+		},
+		close() {
+			for (const socket of [...sockets]) socket.terminate();
+			return Promise.resolve();
+		}
+	};
+}
+export { bunTransport };
+
+//# sourceMappingURL=bun.mjs.map

package/dist/bun.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun.mjs","names":[],"sources":["../src/transports/bun.ts"],"sourcesContent":["/**\n * The Bun transport (RFC 0003 §8.3): completes the upgrades of `Bun.serve()` (`honoAdapter()` on\n * Bun) with Bun's built-in WebSocket server. No import: it only uses the server it is given.\n *\n * ```ts\n * import { bunTransport } from '@znight/websocket/bun'\n * ```\n */\nimport type { BunSocketHandlers, BunUpgrade, MemoryUpgrade, NodeUpgrade } from '@znight/http'\nimport type {\n  AcceptInit,\n  SendStatus,\n  SocketEvents,\n  TransportSettings,\n  TransportSocket,\n  WebSocketTransport,\n} from '../transport.ts'\n\nimport { ErrorCode, ZnightError } from '@znight/core'\n\n/** The part of Bun's `ServerWebSocket` the transport uses. */\ninterface BunSocket {\n  send(data: string | Uint8Array): number\n  getBufferedAmount(): number\n  readonly extensions?: string\n  ping(): void\n  pause?(): void\n  resume?(): void\n  close(code: number, reason: string): void\n  terminate(): void\n}\n\n/** The part of Bun's `Server` the transport uses. */\ninterface BunServer {\n  upgrade(request: Request, options: { data: BunSocketHandlers; headers?: Record<string, string> }): boolean\n}\n\n/** One Bun connection; bound before `server.upgrade()`, since `open` may run inside it. */\nclass BunTransportSocket implements TransportSocket {\n  readonly #events: SocketEvents\n  readonly #registry: Set<BunTransportSocket>\n  #ws: BunSocket | undefined\n  #closed = false\n\n  constructor(events: SocketEvents, registry: Set<BunTransportSocket>) {\n    this.#events = events\n    this.#registry = registry\n  }\n\n  get bufferedAmount(): number {\n    return this.#ws?.getBufferedAmount() ?? 0\n  }\n\n  get extensions(): string {\n    return this.#ws?.extensions ?? ''\n  }\n\n  send(frame: string | Uint8Array, _binary: boolean): SendStatus {\n    if (this.#ws === undefined || this.#closed) return 'dropped'\n    const result = this.#ws.send(frame)\n    if (result > 0) return 'sent'\n    return result === -1 ? 'queued' : 'dropped'\n  }\n\n  ping(): void {\n    this.#ws?.ping()\n  }\n\n  pause(): boolean {\n    if (this.#ws?.pause === undefined) return false\n    this.#ws.pause()\n    return true\n  }\n\n  resume(): void {\n    this.#ws?.resume?.()\n  }\n\n  close(code: number, reason: string): void {\n    this.#ws?.close(code, reason)\n  }\n\n  terminate(): void {\n    this.#ws?.terminate()\n  }\n\n  onOpen(ws: unknown): void {\n    this.#ws = ws as BunSocket\n    this.#registry.add(this)\n  }\n\n  onMessage(message: string | Uint8Array): void {\n    this.#events.message(message, typeof message !== 'string')\n  }\n\n  onClose(code: number, reason: string): void {\n    if (this.#closed) return\n    this.#closed = true\n    this.#registry.delete(this)\n    this.#events.close(code, reason)\n  }\n\n  onDrain(): void {\n    this.#events.drain()\n  }\n\n  onPong(): void {\n    this.#events.pong()\n  }\n}\n\n/** The Bun transport: completes the `bun` upgrades of `Bun.serve()`. */\nexport function bunTransport(): WebSocketTransport {\n  let settings: TransportSettings = { maxPayload: 1024 * 1024, backpressureLimit: 1024 * 1024, heartbeatMs: 0 }\n  const sockets = new Set<BunTransportSocket>()\n  return {\n    name: 'bun',\n    accepts: 'bun',\n    configure(next: TransportSettings): void {\n      settings = next\n    },\n    bunWebSocket(): Readonly<Record<string, unknown>> {\n      return {\n        maxPayloadLength: settings.maxPayload,\n        backpressureLimit: settings.backpressureLimit,\n        closeOnBackpressureLimit: false,\n        sendPings: settings.heartbeatMs > 0,\n        idleTimeout: settings.heartbeatMs > 0 ? Math.min(960, Math.ceil((settings.heartbeatMs * 2) / 1000)) : 0,\n      }\n    },\n    accept(native: NodeUpgrade | BunUpgrade | MemoryUpgrade, init: AcceptInit, events: SocketEvents): TransportSocket {\n      if (native.kind !== 'bun') {\n        throw new ZnightError(\n          ErrorCode.WebSocketTransportUnavailable,\n          `bunTransport() completes Bun.serve() upgrades, not ${native.kind} upgrades`,\n          { hints: ['Use wsTransport() with the node:http adapters'] },\n        )\n      }\n      const socket = new BunTransportSocket(events, sockets)\n      const handlers: BunSocketHandlers = {\n        open: ws => socket.onOpen(ws),\n        message: (_ws, message) => socket.onMessage(message),\n        close: (_ws, code, reason) => socket.onClose(code, reason),\n        drain: () => socket.onDrain(),\n        pong: () => socket.onPong(),\n      }\n      const headers: Record<string, string> = {}\n      for (const [name, value] of Object.entries(init.headers)) {\n        headers[name] = typeof value === 'string' ? value : value.join(', ')\n      }\n      if (init.protocol !== '') headers['sec-websocket-protocol'] = init.protocol\n      const server = native.server as BunServer\n      if (!server.upgrade(native.request, { data: handlers, headers })) {\n        throw new Error('Bun.serve() refused the WebSocket upgrade')\n      }\n      return socket\n    },\n    close(): Promise<void> {\n      for (const socket of [...sockets]) socket.terminate()\n      return Promise.resolve()\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/compiler.d.mts

@@ -0,0 +1,90 @@
+import { Token } from "@znight/core";
+import { MetaEntry } from "@znight/http/compiler";
+import { ClassRef, CompilerExtension, Location, ValueRef } from "@znight/compiler";
+/** A parameter of a handler, as the generated `invoke` passes it. */
+type WsParamData = {
+  readonly kind: "payload";
+} | {
+  readonly kind: "validated";
+  readonly schema: ValueRef;
+} | {
+  readonly kind: "connection";
+} | {
+  readonly kind: "context";
+} | {
+  readonly kind: "undefined";
+  readonly optional: boolean;
+};
+/** `@OnConnect` or `@OnDisconnect`. */
+interface LifecycleData {
+  readonly method: string;
+  readonly params: readonly WsParamData[];
+  readonly declaredBy: string;
+  readonly location: Location;
+}
+/** One `@OnMessage` handler (a method decorated several times gives one entry per event). */
+interface HandlerData {
+  readonly method: string;
+  /** `undefined`: the default handler. */
+  readonly event: string | undefined;
+  /** Route decorators of the method. */
+  readonly meta: readonly MetaEntry[];
+  /** `@UseMessageGuard` of the method. */
+  readonly guards: readonly ClassRef[];
+  readonly params: readonly WsParamData[];
+  readonly declaredBy: string;
+  readonly location: Location;
+}
+/** Static options of `@Gateway`. */
+interface GatewayOptionsData {
+  readonly protocol: "events" | "raw";
+  readonly protocols?: readonly string[];
+  readonly maxPayload?: number;
+  readonly concurrency?: number;
+  readonly rateLimit?: {
+    readonly messages: number;
+    readonly intervalMs: number;
+    readonly onLimit: "reject" | "close";
+  };
+  readonly backpressure?: {
+    readonly limit?: number;
+    readonly onLimit?: "close" | "drop";
+  };
+}
+/** A `@Gateway` class. */
+interface GatewayData {
+  readonly kind: "gateway";
+  readonly token: Token;
+  readonly identity: string;
+  readonly displayName: string;
+  /** Normalised path; `undefined` when invalid (reported). */
+  readonly path: string | undefined;
+  readonly options: GatewayOptionsData;
+  /** Route decorators of the class. */
+  readonly meta: readonly MetaEntry[];
+  readonly handshakeGuards: readonly ClassRef[];
+  readonly messageGuards: readonly ClassRef[];
+  readonly onConnect: LifecycleData | undefined;
+  readonly onDisconnect: LifecycleData | undefined;
+  readonly handlers: readonly HandlerData[];
+  /** Identities of the class and its analysable bases (nearest first). */
+  readonly chain: readonly string[];
+  readonly location: Location;
+}
+/** A class carrying websocket decorators without `@Gateway` (a base class, or a mistake). */
+interface MemberClassData {
+  readonly kind: "members";
+  readonly identity: string;
+  readonly displayName: string;
+  readonly abstract: boolean;
+  readonly decorators: readonly {
+    readonly name: string;
+    readonly location: Location;
+  }[];
+}
+/** Everything the extension stores. */
+type WebSocketData = GatewayData | MemberClassData;
+/** The `@znight/websocket` compiler extension. */
+export declare const webSocketCompilerExtension: CompilerExtension<WebSocketData>;
+export { type GatewayData, type GatewayOptionsData, type HandlerData, type LifecycleData, type MemberClassData, type WebSocketData, type WsParamData, webSocketCompilerExtension as default };
+//# sourceMappingURL=compiler.d.mts.map