@znight/websocket 0.0.0-stage → 0.6.0

package/src/dispatcher.ts

@@ -0,0 +1,343 @@
+/**
+ * The gateway semantics of a connection (RFC 0003 §8.4 step 3, §5.8): decoding, `$ping`, handler
+ * selection, message guards, `invoke` bounded by the handler timeout, replies and error mapping.
+ * The plugin builds one {@link GatewayDispatcher} per gateway and gives it to its connections.
+ */
+import type { Hooks, WebSocketMessageEvent, WebSocketMessageOutcome } from '@znight/core'
+import type { ConnectionDriver, WsCloseInfo, WsConnectionImpl } from './connection.ts'
+import type { WsExceptionMapper, WsGuard, WsMessageContext } from './context.ts'
+import type { MessageId, WireError, WsCodec } from './envelope.ts'
+import type { GatewayDefinition, WsHandlerDefinition } from './metadata.ts'
+
+import { HttpException } from '@znight/http'
+
+import { isFailure, jsonCodec } from './envelope.ts'
+import { codeOfStatus, WsCloseCode, WsErrorCode, WsException, WsValidationException } from './exceptions.ts'
+
+/** A handler with its resolved guards and effective metadata. */
+export interface HandlerPlan {
+  readonly definition: WsHandlerDefinition
+  /** Plugin, gateway, then method guards. */
+  readonly guards: readonly WsGuard[]
+  /** Gateway meta merged with the method's (nearest wins). */
+  readonly meta: Readonly<Record<string, unknown>>
+}
+
+/** What a dispatcher needs from the plugin. */
+export interface DispatcherOptions {
+  readonly definition: GatewayDefinition
+  /** Gateway path, prefix included. */
+  readonly path: string
+  readonly handlers: readonly HandlerPlan[]
+  /** The gateway instance of a connection (singleton, or the request-scoped one of its handshake). */
+  readonly instance: (conn: WsConnectionImpl) => object | Promise<object>
+  readonly handlerTimeoutMs: number
+  readonly exposeErrors: boolean
+  /** Logs an unexpected error (handler, guard, lifecycle). */
+  readonly logError: (message: string, error: unknown, conn: WsConnectionImpl) => void
+  /** Once a connection is fully closed. */
+  readonly closed: (conn: WsConnectionImpl, info: WsCloseInfo) => void
+  /** The `websocket:message` hook: run when it has wrappers, emitted when it has listeners. */
+  readonly hooks?: Hooks
+  /** Display name of the gateway (hook events). */
+  readonly name?: string
+  /** Plugin `exceptionMappers`, in order. */
+  readonly mappers?: readonly WsExceptionMapper[]
+  /** The codec of `events` gateways. Default: {@link jsonCodec}. */
+  readonly codec?: WsCodec
+  /**
+   * Development aid: called once per handler whose result was ignored (a message without `id`
+   * answered by a value). Omitted in production.
+   */
+  readonly ignoredResult?: (handler: string, event: string | undefined) => void
+}
+
+const MESSAGE_HOOK = 'websocket:message'
+
+/** How a message ended (the `websocket:message` outcome and error). */
+interface Settled {
+  readonly outcome: WebSocketMessageOutcome
+  readonly error?: unknown
+}
+
+const OK: Settled = Object.freeze({ outcome: 'ok' })
+
+class TimeoutError extends Error {}
+
+/** Converts what a handler or a guard threw to a wire error. */
+export function toWireError(error: unknown, exposeErrors: boolean): WireError {
+  if (error instanceof WsException) {
+    return {
+      code: error.code,
+      message: error.message,
+      ...(error.details === undefined ? {} : { details: error.details }),
+    }
+  }
+  if (error instanceof HttpException) {
+    const code = codeOfStatus(error.status)
+    const message = code === WsErrorCode.Internal && !exposeErrors ? 'Internal error' : error.message
+    return { code, message, ...(error.details === undefined ? {} : { details: error.details }) }
+  }
+  if (error instanceof TimeoutError) return { code: WsErrorCode.Timeout, message: 'The handler timed out' }
+  const message = exposeErrors && error instanceof Error ? error.message : 'Internal error'
+  return { code: WsErrorCode.Internal, message }
+}
+
+function isForbidden(error: unknown): boolean {
+  if (error instanceof WsException)
+    return error.code === WsErrorCode.Forbidden || error.code === WsErrorCode.Unauthorized
+  return error instanceof HttpException && (error.status === 401 || error.status === 403)
+}
+
+function isExpected(error: unknown): boolean {
+  if (error instanceof WsException || error instanceof TimeoutError) return true
+  return error instanceof HttpException && error.status < 500
+}
+
+/** The close code of an `@OnConnect` failure (§5.8). */
+export function connectFailureCode(error: unknown): { readonly code: number; readonly reason: string } {
+  if (error instanceof WsValidationException) return { code: 4400, reason: error.message }
+  if (error instanceof WsException) return { code: error.close ?? WsCloseCode.PolicyViolation, reason: error.message }
+  if (error instanceof HttpException) return { code: 4000 + error.status, reason: error.message }
+  return { code: WsCloseCode.InternalError, reason: 'Internal error' }
+}
+
+/** One gateway's message pipeline, shared by its connections. */
+export class GatewayDispatcher implements ConnectionDriver {
+  readonly #options: DispatcherOptions
+  readonly #byEvent = new Map<string, HandlerPlan>()
+  readonly #fallback: HandlerPlan | undefined
+  readonly #codec: WsCodec
+  readonly #ignored = new Set<string>()
+
+  constructor(options: DispatcherOptions) {
+    this.#options = options
+    this.#codec = options.codec ?? jsonCodec
+    let fallback: HandlerPlan | undefined
+    for (const plan of options.handlers) {
+      if (plan.definition.event === undefined) fallback = plan
+      else this.#byEvent.set(plan.definition.event, plan)
+    }
+    this.#fallback = fallback
+  }
+
+  get raw(): boolean {
+    return this.#options.definition.protocol === 'raw'
+  }
+
+  async connect(conn: WsConnectionImpl): Promise<void> {
+    const lifecycle = this.#options.definition.onConnect
+    if (lifecycle === undefined) return
+    const gateway = await this.#options.instance(conn)
+    await this.#bounded(Promise.resolve(lifecycle.invoke(gateway, conn)), undefined)
+  }
+
+  connectFailure(error: unknown): { readonly code: number; readonly reason: string } {
+    return connectFailureCode(error)
+  }
+
+  async disconnect(conn: WsConnectionImpl): Promise<void> {
+    const lifecycle = this.#options.definition.onDisconnect
+    if (lifecycle === undefined) return
+    try {
+      await lifecycle.invoke(await this.#options.instance(conn), conn)
+    } catch (error) {
+      this.#options.logError(`@OnDisconnect ${lifecycle.method} failed`, error, conn)
+    }
+  }
+
+  closed(conn: WsConnectionImpl, info: WsCloseInfo): void {
+    this.#options.closed(conn, info)
+  }
+
+  rateLimited(conn: WsConnectionImpl, frame: string | Uint8Array, binary: boolean): void {
+    if (this.raw) return
+    const decoded = this.#codec.decode(frame, binary)
+    const id = decoded.id
+    const event = isFailure(decoded) ? undefined : decoded.event
+    this.#fail(conn, id, event, { code: WsErrorCode.RateLimited, message: 'Too many messages' })
+  }
+
+  async dispatch(conn: WsConnectionImpl, frame: string | Uint8Array, binary: boolean): Promise<void> {
+    const receivedAt = performance.now()
+    let event: string | undefined
+    let id: MessageId | undefined
+    let data: unknown = frame
+    let failure: WireError | undefined
+    if (!this.raw) {
+      const decoded = this.#codec.decode(frame, binary)
+      if (isFailure(decoded)) {
+        id = decoded.id
+        failure = { code: decoded.error, message: decoded.message }
+      } else {
+        ;({ event, id, data } = decoded)
+        if (event === '$ping') {
+          if (id !== undefined) conn.sendFrame(this.#codec.encode({ kind: 'reply', id, data: { t: Date.now() } }))
+          return
+        }
+      }
+    }
+    const plan =
+      failure === undefined
+        ? ((event === undefined ? undefined : this.#byEvent.get(event)) ?? this.#fallback)
+        : undefined
+    const abort = new AbortController()
+    const onClose = () => abort.abort(conn.signal.reason)
+    conn.signal.addEventListener('abort', onClose, { once: true })
+    const ctx: WsMessageContext = {
+      connection: conn,
+      event,
+      id,
+      data,
+      binary,
+      bytes: typeof frame === 'string' ? frame.length : frame.byteLength,
+      receivedAt,
+      signal: abort.signal,
+      state: new Map(),
+      route: {
+        path: this.#options.path,
+        gateway: this.#options.definition.token,
+        handler: plan?.definition.method,
+        event,
+        meta: plan?.meta ?? this.#options.definition.meta,
+      },
+    }
+    try {
+      const hooks = this.#options.hooks
+      if (hooks === undefined || (!hooks.hasWrappers(MESSAGE_HOOK) && !hooks.hasListeners(MESSAGE_HOOK))) {
+        await this.#handle(plan, conn, ctx, failure, abort)
+        return
+      }
+      const hookEvent: WebSocketMessageEvent = {
+        gateway: this.#options.name ?? String(this.#options.definition.token),
+        path: this.#options.path,
+        event,
+        handler: plan?.definition.method,
+        connectionId: conn.id,
+        requestId: conn.requestId,
+        bytes: ctx.bytes,
+        context: ctx,
+        startTime: receivedAt,
+      }
+      try {
+        await hooks.run(MESSAGE_HOOK, hookEvent, async () => {
+          const settled = await this.#handle(plan, conn, ctx, failure, abort)
+          hookEvent.outcome = settled.outcome
+          if (settled.error !== undefined) hookEvent.error = settled.error
+        })
+      } catch (error) {
+        this.#options.logError('A "websocket:message" hook wrapper failed', error, conn)
+      }
+      if (hooks.hasListeners(MESSAGE_HOOK)) hooks.emit(MESSAGE_HOOK, hookEvent)
+    } finally {
+      conn.signal.removeEventListener('abort', onClose)
+    }
+  }
+
+  /** Guards, handler, reply and error mapping of one message. Never rejects. */
+  async #handle(
+    plan: HandlerPlan | undefined,
+    conn: WsConnectionImpl,
+    ctx: WsMessageContext,
+    failure: WireError | undefined,
+    abort: AbortController,
+  ): Promise<Settled> {
+    if (failure !== undefined) {
+      this.#fail(conn, ctx.id, undefined, failure)
+      return { outcome: 'error', error: new WsException(failure.code, failure.message) }
+    }
+    if (plan === undefined) {
+      this.#fail(conn, ctx.id, ctx.event, {
+        code: WsErrorCode.UnknownEvent,
+        message: `Unknown event "${ctx.event}"`,
+      })
+      return { outcome: 'unhandled' }
+    }
+    let rejected = false
+    try {
+      const result = await this.#bounded(
+        this.#run(plan, conn, ctx, () => {
+          rejected = true
+        }),
+        abort,
+      )
+      if (ctx.id !== undefined && conn.readyState === 'open') {
+        conn.sendFrame(this.#codec.encode({ kind: 'reply', id: ctx.id, data: result }))
+      } else if (ctx.id === undefined && result !== undefined && !this.raw) {
+        this.#ignoredResult(plan.definition.method, ctx.event)
+      }
+      return OK
+    } catch (thrown) {
+      const error = await this.#map(thrown, ctx, conn)
+      if (!isExpected(error)) this.#options.logError(`Handler ${plan.definition.method} failed`, error, conn)
+      if (!this.raw) this.#fail(conn, ctx.id, ctx.event, toWireError(error, this.#options.exposeErrors))
+      if (error instanceof WsException && error.close !== undefined) conn.close(error.close, error.message)
+      let outcome: WebSocketMessageOutcome = 'error'
+      if (thrown instanceof TimeoutError) outcome = 'timeout'
+      else if (rejected && isForbidden(error)) outcome = 'rejected'
+      return { outcome, error: thrown }
+    }
+  }
+
+  #ignoredResult(method: string, event: string | undefined): void {
+    const report = this.#options.ignoredResult
+    if (report === undefined || this.#ignored.has(method)) return
+    this.#ignored.add(method)
+    report(method, event)
+  }
+
+  /** Runs the plugin exception mappers, in order: the first `WsException` wins. */
+  async #map(error: unknown, ctx: WsMessageContext, conn: WsConnectionImpl): Promise<unknown> {
+    const mappers = this.#options.mappers
+    if (mappers === undefined || mappers.length === 0 || error instanceof TimeoutError) return error
+    for (const mapper of mappers) {
+      try {
+        const mapped = await mapper.map(error, ctx)
+        if (mapped !== undefined) return mapped
+      } catch (failure) {
+        this.#options.logError('A WebSocket exception mapper failed', failure, conn)
+        return failure
+      }
+    }
+    return error
+  }
+
+  async #run(plan: HandlerPlan, conn: WsConnectionImpl, ctx: WsMessageContext, refused: () => void): Promise<unknown> {
+    for (const guard of plan.guards) {
+      let allowed: boolean
+      try {
+        allowed = (await guard.canHandle(ctx)) === true
+      } catch (error) {
+        refused()
+        throw error
+      }
+      if (!allowed) {
+        refused()
+        throw new WsException(WsErrorCode.Forbidden, 'Forbidden')
+      }
+    }
+    const gateway = await this.#options.instance(conn)
+    return await plan.definition.invoke(gateway, ctx)
+  }
+
+  /** Races a task with the handler timeout; aborts `abort` on timeout. */
+  #bounded<T>(task: Promise<T>, abort: AbortController | undefined): Promise<T> {
+    const ms = this.#options.handlerTimeoutMs
+    if (!Number.isFinite(ms)) return task
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        const error = new TimeoutError('The handler timed out')
+        abort?.abort(error)
+        reject(error)
+      }, ms)
+    })
+    task.catch(() => undefined)
+    return Promise.race([task, timeout]).finally(() => clearTimeout(timer))
+  }
+
+  #fail(conn: WsConnectionImpl, id: MessageId | undefined, event: string | undefined, error: WireError): void {
+    if (this.raw || conn.readyState !== 'open') return
+    conn.sendFrame(this.#codec.encode({ kind: 'error', id, event, error }))
+  }
+}

package/src/envelope.ts

@@ -0,0 +1,136 @@
+/** The envelope of `events` gateways (RFC 0003 §5.3): decoding inbound frames, encoding outbound ones. */
+import { WsErrorCode } from './exceptions.ts'
+
+/** Event names: `^[A-Za-z][\w.:/-]{0,127}$`; names starting with `$` are reserved. */
+export const EVENT_NAME: RegExp = /^[A-Za-z][\w.:/-]{0,127}$/
+
+/** A message id: a string of at most 64 characters or a safe integer, chosen by the client. */
+export type MessageId = string | number
+
+/** A decoded inbound message. */
+export interface InboundMessage {
+  readonly event: string
+  readonly data: unknown
+  /** Present when the client expects exactly one reply. */
+  readonly id: MessageId | undefined
+}
+
+/** A frame that could not be decoded: answered with `$error` (or a reply when the id was readable). */
+export interface InboundFailure {
+  readonly error: string
+  readonly message: string
+  readonly id: MessageId | undefined
+}
+
+/** The wire error of a reply or of an `$error` event. */
+export interface WireError {
+  readonly code: string
+  readonly message: string
+  readonly details?: unknown
+}
+
+/** Whether `value` is a valid message id. */
+export function isMessageId(value: unknown): value is MessageId {
+  return (typeof value === 'string' && value.length <= 64) || Number.isSafeInteger(value)
+}
+
+/**
+ * Decodes an inbound frame of an `events` gateway with the JSON codec: a binary frame is
+ * `UNSUPPORTED_FRAME`, anything but a JSON object with a string `event` is `BAD_FRAME`. Unknown
+ * fields are ignored.
+ */
+export function decodeFrame(frame: string | Uint8Array): InboundMessage | InboundFailure {
+  if (typeof frame !== 'string') {
+    return { error: WsErrorCode.UnsupportedFrame, message: 'Binary frames are not supported', id: undefined }
+  }
+  let value: unknown
+  try {
+    value = JSON.parse(frame)
+  } catch {
+    return { error: WsErrorCode.BadFrame, message: 'The frame is not valid JSON', id: undefined }
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return { error: WsErrorCode.BadFrame, message: 'The frame must be a JSON object', id: undefined }
+  }
+  const record = value as Record<string, unknown>
+  const rawId = record['id']
+  const id = isMessageId(rawId) ? rawId : undefined
+  if (rawId !== undefined && id === undefined) {
+    return { error: WsErrorCode.BadFrame, message: 'Invalid message id', id: undefined }
+  }
+  const event = record['event']
+  if (typeof event !== 'string') return { error: WsErrorCode.BadFrame, message: 'Missing event name', id }
+  return { event, data: record['data'], id }
+}
+
+/** Whether a decoded frame is a failure. */
+export function isFailure(decoded: InboundMessage | InboundFailure): decoded is InboundFailure {
+  return 'error' in decoded
+}
+
+/** A success reply: `{ id, data }`, `data` omitted when `undefined`. */
+export function encodeReply(id: MessageId, data: unknown): string {
+  return data === undefined ? JSON.stringify({ id }) : JSON.stringify({ id, data })
+}
+
+/** A failure reply: `{ id, error }`. */
+export function encodeErrorReply(id: MessageId, error: WireError): string {
+  return JSON.stringify({ id, error: wireError(error) })
+}
+
+/** A server event: `{ event, data }`. */
+export function encodeEvent(event: string, data: unknown): string {
+  return data === undefined ? JSON.stringify({ event }) : JSON.stringify({ event, data })
+}
+
+/** The failure of a message without id: `{ event: '$error', data: { event, code, message, details? } }`. */
+export function encodeErrorEvent(event: string | undefined, error: WireError): string {
+  return JSON.stringify({ event: '$error', data: { ...(event === undefined ? {} : { event }), ...wireError(error) } })
+}
+
+function wireError(error: WireError): WireError {
+  return error.details === undefined
+    ? { code: error.code, message: error.message }
+    : { code: error.code, message: error.message, details: error.details }
+}
+
+/** An outbound frame of an `events` gateway, before encoding. */
+export type OutboundMessage =
+  | { readonly kind: 'event'; readonly event: string; readonly data: unknown }
+  | { readonly kind: 'reply'; readonly id: MessageId; readonly data: unknown }
+  /** A failure: a reply when `id` is set, an `$error` event otherwise (`event`: the failed message's). */
+  | {
+      readonly kind: 'error'
+      readonly id: MessageId | undefined
+      readonly event: string | undefined
+      readonly error: WireError
+    }
+
+/**
+ * The codec of `events` gateways (`WebSocketPlugin` option `codec`): how frames are decoded into
+ * `{ event, data, id }` and how outbound messages are encoded. The default is {@link jsonCodec};
+ * a custom codec may carry MessagePack over binary frames, for instance.
+ */
+export interface WsCodec {
+  /** Decodes an inbound frame; a failure is answered with its code (`BAD_FRAME`...). */
+  decode(frame: string | Uint8Array, binary: boolean): InboundMessage | InboundFailure
+  /** Encodes an outbound message: a string is a text frame, bytes a binary frame. */
+  encode(message: OutboundMessage): string | Uint8Array
+}
+
+/** The default codec: UTF-8 JSON text frames (RFC 0003 §5.3); binary frames are `UNSUPPORTED_FRAME`. */
+export const jsonCodec: WsCodec = Object.freeze({
+  decode: (frame: string | Uint8Array): InboundMessage | InboundFailure => decodeFrame(frame),
+  encode(message: OutboundMessage): string {
+    switch (message.kind) {
+      case 'event':
+        return encodeEvent(message.event, message.data)
+      case 'reply':
+        return encodeReply(message.id, message.data)
+      case 'error':
+        return message.id === undefined
+          ? encodeErrorEvent(message.event, message.error)
+          : encodeErrorReply(message.id, message.error)
+    }
+  },
+})

package/src/exceptions.ts

@@ -0,0 +1,91 @@
+/** Exceptions of WebSocket handlers and their wire codes (RFC 0003 §5.3, §5.8). */
+
+/** Built-in error codes of the wire protocol. */
+export const WsErrorCode = {
+  BadFrame: 'BAD_FRAME',
+  UnsupportedFrame: 'UNSUPPORTED_FRAME',
+  BadRequest: 'BAD_REQUEST',
+  Unauthorized: 'UNAUTHORIZED',
+  Forbidden: 'FORBIDDEN',
+  NotFound: 'NOT_FOUND',
+  Conflict: 'CONFLICT',
+  Unprocessable: 'UNPROCESSABLE',
+  RateLimited: 'RATE_LIMITED',
+  UnknownEvent: 'UNKNOWN_EVENT',
+  Timeout: 'TIMEOUT',
+  Internal: 'INTERNAL',
+} as const
+
+/** Close codes used by the runtime (RFC 0003 §5.8, normative). */
+export const WsCloseCode = {
+  Normal: 1000,
+  GoingAway: 1001,
+  PolicyViolation: 1008,
+  MessageTooBig: 1009,
+  InternalError: 1011,
+  TryAgainLater: 1013,
+} as const
+
+/** Options of {@link WsException}. */
+export interface WsExceptionOptions {
+  /** Close the connection with this code after replying. */
+  readonly close?: number
+  readonly cause?: unknown
+}
+
+/**
+ * An error a handler or a message guard throws to answer the client: a reply with an `id`, an
+ * `$error` event otherwise, then a close when `close` is set.
+ *
+ * ```ts
+ * throw new WsException('FORBIDDEN', 'Join the room first')
+ * ```
+ */
+export class WsException extends Error {
+  readonly code: string
+  readonly details: unknown
+  readonly close: number | undefined
+
+  constructor(code: string, message?: string, details?: unknown, options: WsExceptionOptions = {}) {
+    super(message ?? code, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'WsException'
+    this.code = code
+    this.details = details
+    this.close = options.close
+  }
+}
+
+/** One issue of a {@link WsValidationException}. */
+export interface WsValidationIssue {
+  readonly path: string
+  readonly message: string
+}
+
+/** A payload failed its schema: `BAD_REQUEST` with `details: [{ path, message }]`. */
+export class WsValidationException extends WsException {
+  readonly issues: readonly WsValidationIssue[]
+
+  constructor(issues: readonly WsValidationIssue[], message = 'Invalid payload') {
+    super(WsErrorCode.BadRequest, message, issues)
+    this.name = 'WsValidationException'
+    this.issues = issues
+  }
+}
+
+const BY_STATUS: Readonly<Record<number, string>> = {
+  400: WsErrorCode.BadRequest,
+  401: WsErrorCode.Unauthorized,
+  403: WsErrorCode.Forbidden,
+  404: WsErrorCode.NotFound,
+  409: WsErrorCode.Conflict,
+  422: WsErrorCode.Unprocessable,
+  429: WsErrorCode.RateLimited,
+}
+
+/**
+ * The wire code of an HTTP status thrown by a service (`HttpException`): the table of RFC 0003
+ * §5.8, `INTERNAL` for 5xx and unknown statuses.
+ */
+export function codeOfStatus(status: number): string {
+  return BY_STATUS[status] ?? (status >= 400 && status < 500 ? WsErrorCode.BadRequest : WsErrorCode.Internal)
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * `@znight/websocket` (RFC 0003): WebSocket gateways served by the
+ * `HttpPlugin` server. This entry holds the marker decorators, `WebSocketPlugin`, `WsServer`, the
+ * exceptions, the envelope of the wire protocol and the helpers of the generated code.
+ */
+
+export type { WsConnectOptions, WsWaitOptions } from './client.ts'
+export type { WsExceptionMapper, WsGuard, WsMessageContext } from './context.ts'
+export type {
+  GatewayDefinition,
+  WebSocketMetadata,
+  WsHandlerDefinition,
+  WsLifecycleDefinition,
+  WsParamDefinition,
+} from './metadata.ts'
+export type {
+  BackpressureOptions,
+  GatewayOptions,
+  RateLimitOptions,
+  WebSocketPluginOptions,
+  WsOrigins,
+  WsProviderRef,
+} from './options.ts'
+export type {
+  AcceptInit,
+  SendStatus,
+  SocketEvents,
+  TransportSettings,
+  TransportSocket,
+  WebSocketTransport,
+} from './transport.ts'
+
+export { WsClient, WsHandshakeError, WsRequestError } from './client.ts'
+export {
+  WsClosedError,
+  type WsCloseInfo,
+  type WsCloseInitiator,
+  type WsConnection,
+  type WsSendResult,
+  type WsStats,
+} from './connection.ts'
+export {
+  Conn,
+  Ctx,
+  Gateway,
+  type GatewayClassMarker,
+  type GatewayClassOrMethodMarker,
+  type GatewayMethodMarker,
+  type GatewayParameterMarker,
+  OnConnect,
+  OnDisconnect,
+  OnMessage,
+  Payload,
+  UseHandshakeGuard,
+  UseMessageGuard,
+} from './decorators.ts'
+export {
+  decodeFrame,
+  EVENT_NAME,
+  encodeErrorEvent,
+  encodeErrorReply,
+  encodeEvent,
+  encodeReply,
+  type InboundFailure,
+  type InboundMessage,
+  isFailure,
+  isMessageId,
+  jsonCodec,
+  type MessageId,
+  type OutboundMessage,
+  type WireError,
+  type WsCodec,
+} from './envelope.ts'
+export {
+  codeOfStatus,
+  WsCloseCode,
+  WsErrorCode,
+  WsException,
+  type WsExceptionOptions,
+  WsValidationException,
+  type WsValidationIssue,
+} from './exceptions.ts'
+export { WebSocketPlugin, type WsGatewaySummary } from './plugin.ts'
+export { TokenBucket } from './rate-limit.ts'
+export { type Broadcast, type ChannelMember, type MemberRef, RoomRegistry } from './rooms.ts'
+export { type GatewayChannel, type GatewayRef, type ServedGateway, WsServer } from './server.ts'
+export { WsTokens } from './tokens.ts'
+export { MemoryClient, type MemoryCloseInfo, memoryTransport } from './transports/memory.ts'
+export { validatePayload } from './validate.ts'