WebSocket

SpaceNode includes a built-in WebSocket server (RFC 6455) with zero external dependencies. Supports fragment assembly, ping/pong heartbeat, and backpressure.

Basic Usage

import { createApp } from 'SpaceNode'

const app = await createApp()

app.ws('/chat', (socket, req, services) => {
  console.log('Client connected')

  socket.on('message', (msg) => {
    console.log('Received:', msg)
    socket.send(`Echo: ${msg}`)
  })

  socket.on('close', () => {
    console.log('Client disconnected')
  })
})

app.listen(3000)

Socket API

Backpressure

socket.send() returns a boolean — false means the socket buffer is full. Use pause() / resume() to manage flow control:

const ok = socket.send('hello')
if (!ok) {
  socket.pause()  // pause reading until drain
}

Origin Validation

Restrict which origins can establish WebSocket connections:

const app = await createApp({
  wsOrigins: ['https://mysite.com', 'https://admin.mysite.com'],
})

Fragment Assembly

Large messages may arrive as multiple WebSocket frames (fragments). SpaceNode automatically reassembles fragments into complete messages before emitting the 'message' event.

Ping/Pong Heartbeat

SpaceNode automatically sends ping frames every 30 seconds to keep connections alive. Clients that don't respond with a pong within 60 seconds are disconnected.

Multiple Endpoints

app
  .ws('/chat', chatHandler)
  .ws('/notifications', notifyHandler)
  .ws('/live-data', dataHandler)

Broadcasting

const clients = new Set()

app.ws('/chat', (socket) => {
  clients.add(socket)

  socket.on('message', (msg) => {
    // Broadcast to all connected clients
    for (const client of clients) {
      if (client !== socket && client.readyState === 1) {
        client.send(msg)
      }
    }
  })

  socket.on('close', () => clients.delete(socket))
})

Client-Side

// Browser JavaScript
const ws = new WebSocket('ws://localhost:3000/chat')

ws.onopen = () => ws.send('Hello!')
ws.onmessage = (e) => console.log('Server says:', e.data)