@nmtjs/ws-transport 0.15.0-beta.3 → 0.15.0-beta.4

package/package.json

@@ -12,20 +12,20 @@
   },
   "devDependencies": {
     "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.56.0",
-    "@nmtjs/client": "0.15.0-beta.3",
-    "@nmtjs/common": "0.15.0-beta.3",
-    "@nmtjs/gateway": "0.15.0-beta.3",
-    "@nmtjs/protocol": "0.15.0-beta.3"
+    "@nmtjs/client": "0.15.0-beta.4",
+    "@nmtjs/common": "0.15.0-beta.4",
+    "@nmtjs/protocol": "0.15.0-beta.4",
+    "@nmtjs/gateway": "0.15.0-beta.4"
   },
   "peerDependencies": {
     "@types/bun": "^1.3.0",
     "@types/deno": "^2.3.0",
     "@types/node": "^24",
     "uWebSockets.js": "^20.56.0",
-    "@nmtjs/common": "0.15.0-beta.3",
-    "@nmtjs/core": "0.15.0-beta.3",
-    "@nmtjs/gateway": "0.15.0-beta.3",
-    "@nmtjs/protocol": "0.15.0-beta.3"
+    "@nmtjs/core": "0.15.0-beta.4",
+    "@nmtjs/gateway": "0.15.0-beta.4",
+    "@nmtjs/common": "0.15.0-beta.4",
+    "@nmtjs/protocol": "0.15.0-beta.4"
   },
   "peerDependenciesMeta": {
     "@types/bun": {
@@ -48,10 +48,11 @@
   },
   "files": [
     "dist",
+    "src",
     "LICENSE.md",
     "README.md"
   ],
-  "version": "0.15.0-beta.3",
+  "version": "0.15.0-beta.4",
   "scripts": {
     "clean-build": "rm -rf ./dist",
     "build": "tsc --declaration --sourcemap",

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './injectables.ts'
+export * from './server.ts'
+export * from './types.ts'
+export * from './utils.ts'

package/src/injectables.ts

@@ -0,0 +1,6 @@
+import { connectionData as connectionDataInjectable } from '@nmtjs/gateway'
+
+import type { WsTransportServerRequest } from './types.ts'
+
+export const connectionData =
+  connectionDataInjectable.$withType<WsTransportServerRequest>()

package/src/runtimes/bun.ts

@@ -0,0 +1,82 @@
+import type { Transport } from '@nmtjs/gateway'
+import type { ConnectionType } from '@nmtjs/protocol'
+import { ProxyableTransportType } from '@nmtjs/gateway'
+import createAdapter from 'crossws/adapters/bun'
+
+import type {
+  WsAdapterParams,
+  WsAdapterServer,
+  WsTransportOptions,
+} from '../types.ts'
+import * as injectables from '../injectables.ts'
+import { createWSTransportWorker } from '../server.ts'
+import {
+  InternalServerErrorHttpResponse,
+  NotFoundHttpResponse,
+  StatusResponse,
+} from '../utils.ts'
+
+function adapterFactory(params: WsAdapterParams<'bun'>): WsAdapterServer {
+  const adapter = createAdapter({ hooks: params.wsHooks })
+
+  let server: Bun.Server<any> | null = null
+
+  function createServer() {
+    return globalThis.Bun.serve(
+      // @ts-expect-error ts bs
+      {
+        ...params.runtime?.server,
+        unix: params.listen.unix,
+        port: params.listen.port,
+        hostname: params.listen.hostname,
+        reusePort: params.listen.reusePort,
+        tls: params.tls
+          ? {
+              cert: params.tls.cert,
+              key: params.tls.key,
+              passphrase: params.tls.passphrase,
+            }
+          : undefined,
+        websocket: { ...params.runtime?.ws, ...adapter.websocket },
+        routes: { '/healthy': StatusResponse() },
+        async fetch(request, server) {
+          try {
+            if (request.headers.get('upgrade') === 'websocket') {
+              return await adapter.handleUpgrade(request, server)
+            }
+          } catch (err) {
+            console.error('Error in WebSocket fetch handler', err)
+            return InternalServerErrorHttpResponse()
+          }
+          return NotFoundHttpResponse()
+        },
+      },
+    )
+  }
+
+  return {
+    start: async () => {
+      server = createServer()
+      return server!.url.href
+    },
+    stop: async () => {
+      if (server) {
+        await server.stop()
+        server = null
+      }
+    },
+  }
+}
+
+export const WsTransport: Transport<
+  ConnectionType.Bidirectional,
+  WsTransportOptions<'bun'>,
+  typeof injectables,
+  ProxyableTransportType.WebSocket
+> = {
+  proxyable: ProxyableTransportType.WebSocket,
+  injectables,
+  factory(options) {
+    return createWSTransportWorker(adapterFactory, options)
+  },
+}

package/src/runtimes/deno.ts

@@ -0,0 +1,125 @@
+import type { Transport } from '@nmtjs/gateway'
+import type { ConnectionType } from '@nmtjs/protocol'
+import { ProxyableTransportType } from '@nmtjs/gateway'
+import createAdapter from 'crossws/adapters/deno'
+
+import type {
+  WsAdapterParams,
+  WsAdapterServer,
+  WsTransportOptions,
+} from '../types.ts'
+import * as injectables from '../injectables.ts'
+import { createWSTransportWorker } from '../server.ts'
+import {
+  InternalServerErrorHttpResponse,
+  NotFoundHttpResponse,
+  StatusResponse,
+} from '../utils.ts'
+
+type DenoServer = ReturnType<typeof globalThis.Deno.serve>
+interface DenoNetAddr {
+  transport: 'tcp' | 'udp'
+  hostname: string
+  port: number
+}
+
+interface DenoUnixAddr {
+  transport: 'unix' | 'unixpacket'
+  path: string
+}
+
+interface DenoVsockAddr {
+  transport: 'vsock'
+  cid: number
+  port: number
+}
+
+type DenoAddr = DenoNetAddr | DenoUnixAddr | DenoVsockAddr
+
+function adapterFactory(params: WsAdapterParams<'deno'>): WsAdapterServer {
+  const adapter = createAdapter({ hooks: params.wsHooks })
+
+  let server: DenoServer | null = null
+
+  function createServer() {
+    const listenOptions = params.listen.unix
+      ? { path: params.listen.unix }
+      : {
+          port: params.listen.port,
+          hostname: params.listen.hostname,
+          reusePort: params.listen.reusePort,
+        }
+    const options = {
+      ...listenOptions,
+      tls: params.tls
+        ? {
+            cert: params.tls.cert,
+            key: params.tls.key,
+            passphrase: params.tls.passphrase,
+          }
+        : undefined,
+    }
+
+    return new Promise<{ server: DenoServer; addr: DenoAddr }>((resolve) => {
+      const server = globalThis.Deno.serve({
+        ...params.runtime?.server,
+        ...options,
+        handler: async (request: Request, info: any) => {
+          const url = new URL(request.url)
+          if (url.pathname === '/healthy') return StatusResponse()
+          try {
+            if (request.headers.get('upgrade') === 'websocket') {
+              return await adapter.handleUpgrade(request, info as any)
+            }
+          } catch (err) {
+            console.error('Error in WebSocket fetch handler', err)
+            return InternalServerErrorHttpResponse()
+          }
+          return NotFoundHttpResponse()
+        },
+        onListen(addr: DenoAddr) {
+          setTimeout(() => {
+            resolve({ server, addr })
+          }, 1)
+        },
+      })
+    })
+  }
+
+  return {
+    start: async () => {
+      const { server: _server, addr } = await createServer()
+      server = _server
+      const proto = params.tls ? 'https' : 'http'
+
+      switch (addr.transport) {
+        case 'unix':
+          return `${proto}+unix://${addr.path}`
+        case 'tcp': {
+          return `${proto}://${addr.hostname}:${addr.port}`
+        }
+        default:
+          throw new Error(`Unsupported address transport`)
+      }
+    },
+    stop: async () => {
+      if (server) {
+        await server.shutdown()
+        server = null
+      }
+    },
+  }
+}
+
+export const WsTransport: Transport<
+  ConnectionType.Bidirectional,
+  WsTransportOptions<'deno'>,
+  typeof injectables,
+  ProxyableTransportType.WebSocket
+> = {
+  proxyable: ProxyableTransportType.WebSocket,
+  injectables,
+  factory(options) {
+    return createWSTransportWorker(adapterFactory, options)
+  },
+}

package/src/runtimes/node.ts

@@ -0,0 +1,83 @@
+import type { Transport } from '@nmtjs/gateway'
+import type { ConnectionType } from '@nmtjs/protocol'
+import { ProxyableTransportType } from '@nmtjs/gateway'
+import createAdapter from 'crossws/adapters/uws'
+
+import type {
+  WsAdapterParams,
+  WsAdapterServer,
+  WsTransportOptions,
+} from '../types.ts'
+import * as injectables from '../injectables.ts'
+import { createWSTransportWorker } from '../server.ts'
+import { StatusResponse } from '../utils.ts'
+
+import { App, SSLApp, us_socket_local_port } from 'uWebSockets.js'
+
+const statusResponse = StatusResponse()
+const statusResponseBuffer = await statusResponse.arrayBuffer()
+
+function adapterFactory(params: WsAdapterParams<'node'>): WsAdapterServer {
+  const adapter = createAdapter({ hooks: params.wsHooks })
+
+  const server = params.tls
+    ? SSLApp({
+        passphrase: params.tls.passphrase,
+        key_file_name: params.tls.key,
+        cert_file_name: params.tls.cert,
+      })
+    : App()
+
+  server
+    .ws('/*', { ...params.runtime?.ws, ...adapter.websocket })
+    .get('/healthy', (res) => {
+      res.cork(() => {
+        res
+          .writeStatus(`${statusResponse.status} ${statusResponse.statusText}`)
+          .end(statusResponseBuffer)
+      })
+    })
+
+  return {
+    start: () =>
+      new Promise<string>((resolve, reject) => {
+        const proto = params.tls ? 'https' : 'http'
+        if (params.listen.unix) {
+          server.listen_unix((socket) => {
+            if (socket) {
+              resolve(`${proto}+unix://` + params.listen.unix)
+            } else {
+              reject(new Error('Failed to start WebSockets server'))
+            }
+          }, params.listen.unix)
+        } else if (typeof params.listen.port === 'number') {
+          const hostname = params.listen.hostname || '127.0.0.1'
+          server.listen(hostname, params.listen.port, (socket) => {
+            if (socket) {
+              resolve(`${proto}://${hostname}:${us_socket_local_port(socket)}`)
+            } else {
+              reject(new Error('Failed to start WebSockets server'))
+            }
+          })
+        } else {
+          reject(new Error('Invalid listen parameters'))
+        }
+      }),
+    stop: () => {
+      server.close()
+    },
+  }
+}
+
+export const WsTransport: Transport<
+  ConnectionType.Bidirectional,
+  WsTransportOptions<'node'>,
+  typeof injectables,
+  ProxyableTransportType.WebSocket
+> = {
+  proxyable: ProxyableTransportType.WebSocket,
+  injectables,
+  factory(options) {
+    return createWSTransportWorker(adapterFactory, options)
+  },
+}

package/src/server.ts

@@ -0,0 +1,161 @@
+import type { TransportWorker, TransportWorkerParams } from '@nmtjs/gateway'
+import type { Hooks, Peer } from 'crossws'
+import { ConnectionType, ProtocolVersion } from '@nmtjs/protocol'
+import { defineHooks } from 'crossws'
+
+import type {
+  WsAdapterParams,
+  WsAdapterServer,
+  WsAdapterServerFactory,
+  WsTransportOptions,
+  WsTransportServerRequest,
+} from './types.ts'
+import {
+  InternalServerErrorHttpResponse,
+  NotFoundHttpResponse,
+} from './utils.ts'
+
+export function createWSTransportWorker(
+  adapterFactory: WsAdapterServerFactory<any>,
+  options: WsTransportOptions,
+): TransportWorker<ConnectionType.Bidirectional> {
+  return new WsTransportServer(adapterFactory, options)
+}
+
+export class WsTransportServer
+  implements TransportWorker<ConnectionType.Bidirectional>
+{
+  #server: WsAdapterServer
+  params!: TransportWorkerParams<ConnectionType.Bidirectional>
+  clients = new Map<string, Peer>()
+
+  constructor(
+    protected readonly adapterFactory: WsAdapterServerFactory<any>,
+    protected readonly options: WsTransportOptions,
+  ) {
+    this.#server = this.createServer()
+  }
+
+  async start(
+    hooks: TransportWorkerParams<ConnectionType.Bidirectional>,
+  ): Promise<string> {
+    this.params = hooks
+    return await this.#server.start()
+  }
+
+  async stop(): Promise<void> {
+    for (const peer of this.clients.values()) {
+      try {
+        peer.close(1001, 'Transport stopped')
+      } catch (error) {
+        console.error(
+          `Failed to close WebSocket connection ${peer.context.connectionId}`,
+          error,
+        )
+      }
+    }
+    this.clients.clear()
+    await this.#server.stop()
+  }
+
+  send(connectionId: string, buffer: ArrayBufferView) {
+    const peer = this.clients.get(connectionId)
+    if (!peer) return false
+
+    try {
+      const result = peer.send(buffer)
+      if (typeof result === 'boolean') return result
+      if (typeof result === 'number') return result > 0
+      return true
+    } catch (error) {
+      console.error(
+        `Failed to send data over WebSocket connection ${connectionId}`,
+        error,
+      )
+      this.clients.delete(connectionId)
+      return false
+    }
+  }
+
+  private createWsHooks(): Hooks {
+    return defineHooks({
+      upgrade: async (req) => {
+        const url = new URL(req.url)
+
+        if (url.pathname !== '/') {
+          return NotFoundHttpResponse()
+        }
+
+        const request: WsTransportServerRequest = {
+          url,
+          headers: req.headers,
+          method: req.method,
+        }
+
+        const accept =
+          url.searchParams.get('accept') ?? req.headers.get('accept')
+        const contentType =
+          url.searchParams.get('content-type') ??
+          req.headers.get('content-type')
+
+        try {
+          const connection = await this.params.onConnect({
+            type: ConnectionType.Bidirectional,
+            protocolVersion: ProtocolVersion.v1,
+            accept,
+            contentType,
+            data: request,
+          })
+
+          return { context: { connectionId: connection.id } }
+        } catch (error) {
+          console.error('Failed to upgrade WebSocket connection', error)
+          return InternalServerErrorHttpResponse()
+        }
+      },
+      open: (peer) => {
+        const { connectionId } = peer.context
+        this.clients.set(connectionId, peer)
+      },
+      message: async (peer, message) => {
+        const data = message.arrayBuffer() as ArrayBuffer
+        try {
+          await this.params.onMessage({
+            connectionId: peer.context.connectionId,
+            data,
+          })
+        } catch (error) {
+          console.error(
+            `Error while processing message from ${peer.context.connectionId}`,
+            error,
+          )
+          this.clients.delete(peer.context.connectionId)
+          peer.close(1011, 'Internal error')
+        }
+      },
+      error: (peer, error) => {
+        console.error(
+          `WebSocket error on connection ${peer.context.connectionId}`,
+          error,
+        )
+      },
+      close: async (peer) => {
+        this.clients.delete(peer.context.connectionId)
+        try {
+          await this.params.onDisconnect(peer.context.connectionId)
+        } catch (error) {
+          console.error(
+            `Failed to dispose WebSocket connection ${peer.context.connectionId}`,
+            error,
+          )
+        }
+      },
+    }) as Hooks
+  }
+
+  private createServer() {
+    const hooks = this.createWsHooks()
+    const opts: WsAdapterParams = { ...this.options, wsHooks: hooks }
+    return this.adapterFactory(opts)
+  }
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+import type { Async, OneOf } from '@nmtjs/common'
+import type { Hooks } from 'crossws'
+
+export type WsTransportServerRequest = {
+  url: URL
+  method: string
+  headers: Headers
+}
+
+export type WsTransportPeerContext = { connectionId: string }
+
+declare module 'crossws' {
+  interface PeerContext extends WsTransportPeerContext {}
+}
+
+export type WsTransportOptions<
+  R extends keyof WsTransportRuntimes = keyof WsTransportRuntimes,
+> = {
+  listen: WsTransportListenOptions
+  cors?: WsTransportCorsOptions
+  tls?: WsTransportTlsOptions
+  runtime?: WsTransportRuntimes[R]
+}
+
+export type WsTransportCorsCustomParams = {
+  allowMethods?: string[]
+  allowHeaders?: string[]
+  allowCredentials?: string
+  maxAge?: string
+  exposeHeaders?: string[]
+  requestHeaders?: string[]
+  requestMethod?: string
+}
+
+export type WsTransportCorsOptions =
+  | true
+  | string[]
+  | WsTransportCorsCustomParams
+  | ((
+      origin: string,
+      request: WsTransportServerRequest,
+    ) => boolean | WsTransportCorsCustomParams)
+
+export type WsTransportListenOptions = OneOf<
+  [{ port: number; hostname?: string; reusePort?: boolean }, { unix: string }]
+>
+
+export type WsTransportRuntimeBun = {
+  ws?: Partial<
+    Pick<
+      import('bun').WebSocketHandler<import('crossws').PeerContext>,
+      | 'backpressureLimit'
+      | 'maxPayloadLength'
+      | 'closeOnBackpressureLimit'
+      | 'idleTimeout'
+      | 'perMessageDeflate'
+      | 'sendPings'
+    >
+  >
+  server?: Partial<
+    Pick<
+      import('bun').ServeOptions,
+      'development' | 'id' | 'maxRequestBodySize' | 'idleTimeout' | 'ipv6Only'
+    >
+  >
+}
+
+export type WsTransportRuntimeNode = {
+  ws?: Partial<
+    Pick<
+      import('uWebSockets.js').WebSocketBehavior<import('crossws').PeerContext>,
+      | 'maxBackpressure'
+      | 'maxPayloadLength'
+      | 'maxLifetime'
+      | 'closeOnBackpressureLimit'
+      | 'idleTimeout'
+      | 'compression'
+      | 'sendPingsAutomatically'
+    >
+  >
+}
+
+export type WsTransportRuntimeDeno = { server?: {} }
+
+export type WsTransportRuntimes = {
+  bun: WsTransportRuntimeBun
+  node: WsTransportRuntimeNode
+  deno: WsTransportRuntimeDeno
+}
+
+export type WsTransportTlsOptions = {
+  /**
+   * File path or inlined TLS certificate in PEM format (required).
+   */
+  cert?: string
+  /**
+   * File path or inlined TLS private key in PEM format (required).
+   */
+  key?: string
+  /**
+   * Passphrase for the private key (optional).
+   */
+  passphrase?: string
+}
+
+export type WsAdapterParams<
+  R extends keyof WsTransportRuntimes = keyof WsTransportRuntimes,
+> = {
+  listen: WsTransportListenOptions
+  wsHooks: Hooks
+  cors?: WsTransportCorsOptions
+  tls?: WsTransportTlsOptions
+  runtime?: WsTransportRuntimes[R]
+}
+
+export interface WsAdapterServer {
+  stop: () => Async<any>
+  start: () => Async<string>
+}
+
+export type WsAdapterServerFactory<
+  R extends keyof WsTransportRuntimes = keyof WsTransportRuntimes,
+> = (params: WsAdapterParams<R>) => WsAdapterServer

package/src/utils.ts

@@ -0,0 +1,28 @@
+import { ErrorCode } from '@nmtjs/protocol'
+import { ProtocolError } from '@nmtjs/protocol/server'
+
+export const InternalError = (message = 'Internal Server Error') =>
+  new ProtocolError(ErrorCode.InternalServerError, message)
+
+export const NotFoundError = (message = 'Not Found') =>
+  new ProtocolError(ErrorCode.NotFound, message)
+
+export const ForbiddenError = (message = 'Forbidden') =>
+  new ProtocolError(ErrorCode.Forbidden, message)
+
+export const RequestTimeoutError = (message = 'Request Timeout') =>
+  new ProtocolError(ErrorCode.RequestTimeout, message)
+
+export const NotFoundHttpResponse = () =>
+  new Response('Not Found', {
+    status: 404,
+    headers: { 'Content-Type': 'text/plain' },
+  })
+
+export const InternalServerErrorHttpResponse = () =>
+  new Response('Internal Server Error', {
+    status: 500,
+    headers: { 'Content-Type': 'text/plain' },
+  })
+
+export const StatusResponse = () => new Response('OK', { status: 200 })