@znight/websocket 0.0.0 → 0.6.0

package/src/transport.ts

@@ -0,0 +1,72 @@
+/** The transport contract (RFC 0003 §8.3): what completes a handshake and carries the frames. */
+import type { BunUpgrade, HeaderValue, MemoryUpgrade, NodeUpgrade } from '@znight/http'
+
+/** Server-wide settings given once at bootstrap. */
+export interface TransportSettings {
+  /** The largest inbound message any gateway accepts, in bytes. */
+  readonly maxPayload: number
+  /** The largest outbound buffer any gateway tolerates, in bytes. */
+  readonly backpressureLimit: number
+  /** Heartbeat interval in ms, `0` when disabled. */
+  readonly heartbeatMs: number
+}
+
+/** What {@link WebSocketTransport.accept} receives besides the native upgrade. */
+export interface AcceptInit {
+  /** The selected subprotocol, `''` when none. */
+  readonly protocol: string
+  /** Extra headers of the `101` response. */
+  readonly headers: Readonly<Record<string, HeaderValue>>
+  /** The largest inbound message of the gateway, in bytes. */
+  readonly maxPayload: number
+}
+
+/** The socket events of one connection, given to the transport by the plugin. */
+export interface SocketEvents {
+  message(frame: string | Uint8Array, binary: boolean): void
+  pong(): void
+  /**
+   * The outbound buffer may have shrunk (after a write, or Bun's `drain`): the connection compares it
+   * with its own threshold, and polls the buffer while `conn.drained()` waits.
+   */
+  drain(): void
+  close(code: number, reason: string): void
+}
+
+/** The result of {@link TransportSocket.send}. */
+export type SendStatus = 'sent' | 'queued' | 'dropped'
+
+/** One accepted connection, the only object holding native handles. */
+export interface TransportSocket {
+  send(frame: string | Uint8Array, binary: boolean): SendStatus
+  readonly bufferedAmount: number
+  ping(): void
+  /** Stops reading; `false` when the transport cannot pause. */
+  pause(): boolean
+  resume(): void
+  close(code: number, reason: string): void
+  terminate(): void
+  /** Negotiated extensions (`permessage-deflate`...), `''` when none. */
+  readonly extensions: string
+}
+
+/** A transport: `ws` on `node:http` servers, Bun's built-in WebSocket on `Bun.serve()`, or memory. */
+export interface WebSocketTransport {
+  readonly name: string
+  /** Which native upgrade it completes. */
+  readonly accepts: 'node' | 'bun' | 'memory'
+  configure(settings: TransportSettings): void
+  accept(
+    native: NodeUpgrade | BunUpgrade | MemoryUpgrade,
+    init: AcceptInit,
+    events: SocketEvents,
+  ): TransportSocket | Promise<TransportSocket>
+  /**
+   * Loads what the transport needs before the server listens (the `ws` package), so that a missing
+   * dependency fails the startup (ZNIGHT051) rather than the first handshake.
+   */
+  ready?(): Promise<void>
+  /** `Bun.serve()` transports only: the settings of its `websocket` option. */
+  bunWebSocket?(): Readonly<Record<string, unknown>>
+  close(): Promise<void>
+}

package/src/transports/bun.ts

@@ -0,0 +1,163 @@
+/**
+ * The Bun transport (RFC 0003 §8.3): completes the upgrades of `Bun.serve()` (`honoAdapter()` on
+ * Bun) with Bun's built-in WebSocket server. No import: it only uses the server it is given.
+ *
+ * ```ts
+ * import { bunTransport } from '@znight/websocket/bun'
+ * ```
+ */
+import type { BunSocketHandlers, BunUpgrade, MemoryUpgrade, NodeUpgrade } from '@znight/http'
+import type {
+  AcceptInit,
+  SendStatus,
+  SocketEvents,
+  TransportSettings,
+  TransportSocket,
+  WebSocketTransport,
+} from '../transport.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+
+/** The part of Bun's `ServerWebSocket` the transport uses. */
+interface BunSocket {
+  send(data: string | Uint8Array): number
+  getBufferedAmount(): number
+  readonly extensions?: string
+  ping(): void
+  pause?(): void
+  resume?(): void
+  close(code: number, reason: string): void
+  terminate(): void
+}
+
+/** The part of Bun's `Server` the transport uses. */
+interface BunServer {
+  upgrade(request: Request, options: { data: BunSocketHandlers; headers?: Record<string, string> }): boolean
+}
+
+/** One Bun connection; bound before `server.upgrade()`, since `open` may run inside it. */
+class BunTransportSocket implements TransportSocket {
+  readonly #events: SocketEvents
+  readonly #registry: Set<BunTransportSocket>
+  #ws: BunSocket | undefined
+  #closed = false
+
+  constructor(events: SocketEvents, registry: Set<BunTransportSocket>) {
+    this.#events = events
+    this.#registry = registry
+  }
+
+  get bufferedAmount(): number {
+    return this.#ws?.getBufferedAmount() ?? 0
+  }
+
+  get extensions(): string {
+    return this.#ws?.extensions ?? ''
+  }
+
+  send(frame: string | Uint8Array, _binary: boolean): SendStatus {
+    if (this.#ws === undefined || this.#closed) return 'dropped'
+    const result = this.#ws.send(frame)
+    if (result > 0) return 'sent'
+    return result === -1 ? 'queued' : 'dropped'
+  }
+
+  ping(): void {
+    this.#ws?.ping()
+  }
+
+  pause(): boolean {
+    if (this.#ws?.pause === undefined) return false
+    this.#ws.pause()
+    return true
+  }
+
+  resume(): void {
+    this.#ws?.resume?.()
+  }
+
+  close(code: number, reason: string): void {
+    this.#ws?.close(code, reason)
+  }
+
+  terminate(): void {
+    this.#ws?.terminate()
+  }
+
+  onOpen(ws: unknown): void {
+    this.#ws = ws as BunSocket
+    this.#registry.add(this)
+  }
+
+  onMessage(message: string | Uint8Array): void {
+    this.#events.message(message, typeof message !== 'string')
+  }
+
+  onClose(code: number, reason: string): void {
+    if (this.#closed) return
+    this.#closed = true
+    this.#registry.delete(this)
+    this.#events.close(code, reason)
+  }
+
+  onDrain(): void {
+    this.#events.drain()
+  }
+
+  onPong(): void {
+    this.#events.pong()
+  }
+}
+
+/** The Bun transport: completes the `bun` upgrades of `Bun.serve()`. */
+export function bunTransport(): WebSocketTransport {
+  let settings: TransportSettings = { maxPayload: 1024 * 1024, backpressureLimit: 1024 * 1024, heartbeatMs: 0 }
+  const sockets = new Set<BunTransportSocket>()
+  return {
+    name: 'bun',
+    accepts: 'bun',
+    configure(next: TransportSettings): void {
+      settings = next
+    },
+    bunWebSocket(): Readonly<Record<string, unknown>> {
+      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) / 1000)) : 0,
+      }
+    },
+    accept(native: NodeUpgrade | BunUpgrade | MemoryUpgrade, init: AcceptInit, events: SocketEvents): TransportSocket {
+      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: BunSocketHandlers = {
+        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: Record<string, string> = {}
+      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
+      const server = native.server as BunServer
+      if (!server.upgrade(native.request, { data: handlers, headers })) {
+        throw new Error('Bun.serve() refused the WebSocket upgrade')
+      }
+      return socket
+    },
+    close(): Promise<void> {
+      for (const socket of [...sockets]) socket.terminate()
+      return Promise.resolve()
+    },
+  }
+}

package/src/transports/memory.ts

@@ -0,0 +1,174 @@
+/**
+ * The in-memory transport (RFC 0003 §8.3): an in-process pair used by `WebSocketPlugin.connect()`
+ * and the tests. Frames are delivered synchronously, nothing is buffered, reading pauses with a
+ * queue, and there is no heartbeat.
+ */
+import type { BunUpgrade, MemoryUpgrade, NodeUpgrade } from '@znight/http'
+import type { AcceptInit, SendStatus, SocketEvents, TransportSocket, WebSocketTransport } from '../transport.ts'
+
+/** How a memory connection closed. */
+export interface MemoryCloseInfo {
+  readonly code: number
+  readonly reason: string
+}
+
+/**
+ * The client side of an in-memory connection: pass it as the `peer` of a memory upgrade
+ * (`{ kind: 'memory', peer: client }`), then read `received` and send frames.
+ */
+export class MemoryClient {
+  /** Frames received from the server, in order. */
+  readonly received: (string | Uint8Array)[] = []
+  /** Called for each frame received from the server. */
+  onmessage: ((frame: string | Uint8Array) => void) | undefined
+  /** Called once when the connection closes. */
+  onclose: ((info: MemoryCloseInfo) => void) | undefined
+  #protocol = ''
+  #closed: MemoryCloseInfo | undefined
+  #server: MemorySocket | undefined
+
+  /** The subprotocol the server selected, `''` when none. */
+  get protocol(): string {
+    return this.#protocol
+  }
+
+  /** How the connection closed, `undefined` while open. */
+  get closed(): MemoryCloseInfo | undefined {
+    return this.#closed
+  }
+
+  /** Whether the server accepted the connection. */
+  get open(): boolean {
+    return this.#server !== undefined && this.#closed === undefined
+  }
+
+  /** Sends a frame to the server (a string is a text frame). */
+  send(frame: string | Uint8Array): void {
+    if (this.#server === undefined || this.#closed !== undefined) throw new Error('The connection is not open')
+    this.#server.receive(frame)
+  }
+
+  /** Closes the connection from the client side. */
+  close(code = 1000, reason = ''): void {
+    if (this.#server === undefined || this.#closed !== undefined) return
+    this.#server.closeFromPeer(code, reason)
+  }
+
+  /** @internal Bound by the memory transport. */
+  attach(server: MemorySocket, protocol: string): void {
+    if (this.#server !== undefined) throw new Error('This MemoryClient is already connected')
+    this.#server = server
+    this.#protocol = protocol
+  }
+
+  /** @internal */
+  deliver(frame: string | Uint8Array): void {
+    this.received.push(frame)
+    this.onmessage?.(frame)
+  }
+
+  /** @internal */
+  closedWith(info: MemoryCloseInfo): void {
+    if (this.#closed !== undefined) return
+    this.#closed = info
+    this.onclose?.(info)
+  }
+}
+
+/** The server side of an in-memory connection. */
+class MemorySocket implements TransportSocket {
+  readonly bufferedAmount = 0
+  readonly extensions = ''
+  readonly #client: MemoryClient
+  readonly #events: SocketEvents
+  readonly #queue: (string | Uint8Array)[] = []
+  #paused = false
+  #closed = false
+
+  constructor(client: MemoryClient, events: SocketEvents) {
+    this.#client = client
+    this.#events = events
+  }
+
+  send(frame: string | Uint8Array, _binary: boolean): SendStatus {
+    if (this.#closed) return 'dropped'
+    this.#client.deliver(frame)
+    return 'sent'
+  }
+
+  ping(): void {
+    if (!this.#closed) this.#events.pong()
+  }
+
+  pause(): boolean {
+    this.#paused = true
+    return true
+  }
+
+  resume(): void {
+    this.#paused = false
+    while (!this.#paused && !this.#closed && this.#queue.length > 0) this.#dispatch(this.#queue.shift() as string)
+  }
+
+  close(code: number, reason: string): void {
+    this.#finish(code, reason)
+  }
+
+  terminate(): void {
+    this.#finish(1006, '')
+  }
+
+  receive(frame: string | Uint8Array): void {
+    if (this.#closed) return
+    if (this.#paused) this.#queue.push(frame)
+    else this.#dispatch(frame)
+  }
+
+  closeFromPeer(code: number, reason: string): void {
+    this.#finish(code, reason)
+  }
+
+  #dispatch(frame: string | Uint8Array): void {
+    this.#events.message(frame, typeof frame !== 'string')
+  }
+
+  #finish(code: number, reason: string): void {
+    if (this.#closed) return
+    this.#closed = true
+    this.#queue.length = 0
+    this.#client.closedWith({ code, reason })
+    this.#events.close(code, reason)
+  }
+}
+
+/** The in-memory transport: completes `{ kind: 'memory', peer }` upgrades whose peer is a {@link MemoryClient}. */
+export function memoryTransport(): WebSocketTransport {
+  const sockets = new Set<MemorySocket>()
+  return {
+    name: 'memory',
+    accepts: 'memory',
+    configure: () => undefined,
+    accept(native: NodeUpgrade | BunUpgrade | MemoryUpgrade, init: AcceptInit, events: SocketEvents): TransportSocket {
+      if (native.kind !== 'memory' || !(native.peer instanceof MemoryClient)) {
+        throw new Error('The memory transport only completes memory upgrades whose peer is a MemoryClient')
+      }
+      const tracked: SocketEvents = {
+        message: (frame, binary) => events.message(frame, binary),
+        pong: () => events.pong(),
+        drain: () => events.drain(),
+        close: (code, reason) => {
+          sockets.delete(socket)
+          events.close(code, reason)
+        },
+      }
+      const socket = new MemorySocket(native.peer, tracked)
+      sockets.add(socket)
+      native.peer.attach(socket, init.protocol)
+      return socket
+    },
+    close(): Promise<void> {
+      for (const socket of [...sockets]) socket.terminate()
+      return Promise.resolve()
+    },
+  }
+}

package/src/transports/ws.ts

@@ -0,0 +1,237 @@
+/**
+ * The `ws` transport (RFC 0003 §8.3): completes the upgrades of every `node:http` adapter, on
+ * Node.js and on Bun. `ws` is an optional peer dependency, loaded lazily on the first connection.
+ *
+ * ```ts
+ * import { wsTransport } from '@znight/websocket/ws'
+ * ```
+ */
+import type { BunUpgrade, HeaderValue, MemoryUpgrade, NodeUpgrade } from '@znight/http'
+import type {
+  AcceptInit,
+  SendStatus,
+  SocketEvents,
+  TransportSettings,
+  TransportSocket,
+  WebSocketTransport,
+} from '../transport.ts'
+
+import { ErrorCode, ZnightError } from '@znight/core'
+import { HttpException } from '@znight/http'
+
+/** The part of a `ws` `WebSocket` the transport uses (no `@types/ws`). */
+interface WsSocket {
+  /** `1` while open. */
+  readonly readyState: number
+  readonly bufferedAmount: number
+  readonly extensions: string
+  send(data: string | Uint8Array, options: { binary: boolean }, callback: (error?: Error) => void): void
+  ping(): void
+  pause(): void
+  resume(): void
+  close(code: number, reason: string): void
+  terminate(): void
+  on(event: 'message', listener: (data: Buffer | ArrayBuffer | Buffer[], binary: boolean) => void): void
+  on(event: 'pong', listener: () => void): void
+  on(event: 'close', listener: (code: number, reason: Buffer) => void): void
+  on(event: 'error', listener: (error: Error) => void): void
+}
+
+/** The part of a `ws` `WebSocketServer` the transport uses. */
+interface WsServer {
+  handleUpgrade(request: unknown, socket: unknown, head: Uint8Array, callback: (ws: WsSocket) => void): void
+  on(event: 'headers', listener: (headers: string[], request: unknown) => void): void
+  close(): void
+}
+
+/** The part of the handshake's `net.Socket` the transport watches. */
+interface NodeSocket {
+  readonly destroyed: boolean
+  readonly writable: boolean
+  once(event: 'close', listener: () => void): void
+  removeListener(event: 'close', listener: () => void): void
+}
+
+/** The part of the handshake's `IncomingMessage` the transport rewrites. */
+interface NodeRequest {
+  znightProtocol?: string
+  readonly headers: Record<string, string | string[] | undefined>
+}
+
+interface WsModule {
+  readonly WebSocketServer: new (options: Record<string, unknown>) => WsServer
+}
+
+/** Options of {@link wsTransport}. */
+export interface WsTransportOptions {
+  /** `permessage-deflate` (`ws` option). Default: `false`. */
+  readonly perMessageDeflate?: boolean | Record<string, unknown>
+}
+
+let loading: Promise<WsModule> | undefined
+
+function loadWs(): Promise<WsModule> {
+  const name = 'ws'
+  loading ??= (import(name) as Promise<WsModule & { default?: WsModule }>).then(
+    module => (module.WebSocketServer === undefined && module.default !== undefined ? module.default : module),
+    (cause: unknown) => {
+      loading = undefined
+      throw new ZnightError(
+        ErrorCode.WebSocketTransportUnavailable,
+        'The "ws" package is required to serve WebSocket gateways on Node.js',
+        { hints: ['Install it: npm install ws'], cause },
+      )
+    },
+  )
+  return loading
+}
+
+function toFrame(data: Buffer | ArrayBuffer | Buffer[], binary: boolean): string | Uint8Array {
+  let bytes: Uint8Array
+  if (Array.isArray(data)) bytes = Buffer.concat(data)
+  else if (data instanceof ArrayBuffer) bytes = new Uint8Array(data)
+  else bytes = data
+  return binary ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength) : Buffer.from(bytes).toString('utf8')
+}
+
+/** One `ws` connection. */
+class WsTransportSocket implements TransportSocket {
+  readonly #ws: WsSocket
+  readonly #limit: number
+  /** `drain` after every write: the connection compares the buffer with its own threshold. */
+  readonly #events: SocketEvents
+
+  constructor(ws: WsSocket, limit: number, events: SocketEvents) {
+    this.#ws = ws
+    this.#limit = limit
+    this.#events = events
+  }
+
+  get bufferedAmount(): number {
+    return this.#ws.bufferedAmount
+  }
+
+  get extensions(): string {
+    return this.#ws.extensions
+  }
+
+  send(frame: string | Uint8Array, binary: boolean): SendStatus {
+    if (this.#ws.readyState !== 1) return 'dropped'
+    this.#ws.send(frame, { binary }, () => this.#events.drain())
+    return this.#ws.bufferedAmount <= this.#limit ? 'sent' : 'queued'
+  }
+
+  ping(): void {
+    this.#ws.ping()
+  }
+
+  pause(): boolean {
+    this.#ws.pause()
+    return true
+  }
+
+  resume(): void {
+    this.#ws.resume()
+  }
+
+  close(code: number, reason: string): void {
+    this.#ws.close(code, reason)
+  }
+
+  terminate(): void {
+    this.#ws.terminate()
+  }
+}
+
+/** The `ws` transport: completes the `node` upgrades of `node:http` servers. */
+export function wsTransport(options: WsTransportOptions = {}): WebSocketTransport {
+  let settings: TransportSettings = { maxPayload: 1024 * 1024, backpressureLimit: 1024 * 1024, heartbeatMs: 0 }
+  let server: WsServer | undefined
+  const pendingHeaders = new WeakMap<object, Readonly<Record<string, HeaderValue>>>()
+  const sockets = new Set<WsSocket>()
+
+  async function serverOf(): Promise<WsServer> {
+    if (server !== undefined) return server
+    const { WebSocketServer } = await loadWs()
+    server ??= new WebSocketServer({
+      noServer: true,
+      maxPayload: settings.maxPayload,
+      perMessageDeflate: options.perMessageDeflate ?? false,
+      clientTracking: false,
+      handleProtocols: (protocols: Set<string>, request: object) => {
+        const selected = (request as { znightProtocol?: string }).znightProtocol ?? ''
+        return selected !== '' && protocols.has(selected) ? selected : false
+      },
+    })
+    server.on('headers', (lines, request) => {
+      const extra = pendingHeaders.get(request as object)
+      if (extra === undefined) return
+      for (const [name, value] of Object.entries(extra)) {
+        for (const item of typeof value === 'string' ? [value] : value) lines.push(`${name}: ${item}`)
+      }
+    })
+    return server
+  }
+
+  return {
+    name: 'ws',
+    accepts: 'node',
+    configure(next: TransportSettings): void {
+      settings = next
+    },
+    async ready(): Promise<void> {
+      await serverOf()
+    },
+    async accept(
+      native: NodeUpgrade | BunUpgrade | MemoryUpgrade,
+      init: AcceptInit,
+      events: SocketEvents,
+    ): Promise<TransportSocket> {
+      if (native.kind !== 'node') {
+        throw new ZnightError(
+          ErrorCode.WebSocketTransportUnavailable,
+          `wsTransport() completes node:http upgrades, not ${native.kind} upgrades`,
+          { hints: ['Use bunTransport() with honoAdapter() on Bun'] },
+        )
+      }
+      const wss = await serverOf()
+      const request = native.request as NodeRequest
+      const raw = native.socket as NodeSocket
+      // the plugin selected the subprotocol: ws would abort (400, no callback) on a header it cannot parse
+      if (init.protocol === '') delete request.headers['sec-websocket-protocol']
+      else request.headers['sec-websocket-protocol'] = init.protocol
+      request.znightProtocol = init.protocol
+      pendingHeaders.set(request, init.headers)
+      // ws destroys the socket without calling back when the client left or a header is malformed
+      const ws = await new Promise<WsSocket>((resolve, reject) => {
+        const aborted = (): void => reject(new HttpException(400, 'The WebSocket handshake was aborted'))
+        if (raw.destroyed || !raw.writable) {
+          aborted()
+          return
+        }
+        raw.once('close', aborted)
+        wss.handleUpgrade(request, raw, native.head, accepted => {
+          raw.removeListener('close', aborted)
+          resolve(accepted)
+        })
+      }).finally(() => pendingHeaders.delete(request))
+      sockets.add(ws)
+      const socket = new WsTransportSocket(ws, settings.backpressureLimit, events)
+      ws.on('error', () => undefined) // reported through 'close'; an unhandled 'error' would kill the process
+      ws.on('message', (data, binary) => events.message(toFrame(data, binary), binary))
+      ws.on('pong', () => events.pong())
+      ws.on('close', (code, reason) => {
+        sockets.delete(ws)
+        events.close(code, reason.toString('utf8'))
+      })
+      return socket
+    },
+    close(): Promise<void> {
+      for (const ws of sockets) ws.terminate()
+      sockets.clear()
+      server?.close()
+      server = undefined
+      return Promise.resolve()
+    },
+  }
+}

package/src/validate.ts

@@ -0,0 +1,31 @@
+/** Payload validation called by the generated `invoke` functions (RFC 0003 §7.3, "Compiler contract"). */
+import type { InferSchemaOutput, StandardSchemaV1 } from '@znight/http'
+
+import { ValidationException, validate } from '@znight/http'
+
+import { WsValidationException } from './exceptions.ts'
+
+/**
+ * Validates a message payload with a Standard Schema and returns the schema output, synchronously
+ * when the schema is synchronous.
+ *
+ * @throws WsValidationException (`BAD_REQUEST`, `details: [{ path, message }]`) when the payload is invalid.
+ */
+export function validatePayload<S extends StandardSchemaV1>(
+  schema: S,
+  value: unknown,
+): InferSchemaOutput<S> | Promise<InferSchemaOutput<S>> {
+  try {
+    const result = validate(schema, value, 'payload')
+    return result instanceof Promise ? result.catch(rethrow) : result
+  } catch (error) {
+    return rethrow(error)
+  }
+}
+
+function rethrow(error: unknown): never {
+  if (error instanceof ValidationException) {
+    throw new WsValidationException(error.details as readonly { path: string; message: string }[])
+  }
+  throw error
+}