ArctonArcton
Routing

WebSockets

Registering WebSocket routes with app.ws(), the handler callbacks, and how sockets combine with modules.

app.ws() registers a WebSocket route on the same server as your HTTP routes:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/', () => ({ ok: true }))

app.ws('/chat', {
  message(ws, message) {
    ws.send(`echo: ${message}`)
  }
})

app.listen({ port: 3000 })

A client connecting to ws://localhost:3000/chat is upgraded automatically. Everything else on the server keeps working over HTTP.

The handler

message is the only required callback. open, close and drain are optional:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.ws('/chat', {
  open(ws) {
    ws.send('connected')
  },
  message(ws, message) {
    ws.send(`echo: ${message}`)
  },
  close(ws, code, reason) {
    console.log('closed', code, reason)
  },
  drain(ws) {
    console.log('socket ready for more data')
  }
})

app.listen()
CallbackCalled when
message(ws, message)a frame arrives — string for text, ArrayBuffer for binary
open(ws)the connection has been established
close(ws, code, reason)the connection closed
drain(ws)a backpressured socket can accept more data

Each callback may be async.

The socket

The ws value passed to every callback offers two methods:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.ws('/chat', {
  message(ws, message) {
    if (message === 'bye') {
      ws.close(1000, 'client said bye')
      return
    }

    ws.send(`echo: ${message}`)
  }
})

app.listen()

send() accepts a string, an ArrayBuffer or a typed array. close() takes an optional code and reason.

Text and binary frames

message is a string for text frames and an ArrayBuffer for binary ones, so narrow before using it:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.ws('/upload', {
  message(ws, message) {
    if (typeof message === 'string') {
      ws.send(`text of length ${message.length}`)
      return
    }

    ws.send(`binary of ${message.byteLength} bytes`)
  }
})

app.listen()

Sockets in modules

A WebSocket route registered inside a module picks up the prefixes when it is mounted:

import { Arcton } from '@arcton/core'

const chat = Arcton({ prefix: '/chat' })

chat.ws('/room', {
  message(ws, message) {
    ws.send(`echo: ${message}`)
  }
})

const app = Arcton({ prefix: '/api' })

app.use(chat)

app.listen()

The socket is served at /api/chat/room.

Runtime support

WebSocket routes need an adapter that supports them; both the Bun and the Node.js adapters do. The check happens when you call listen(), not when you register the route — mounting a module can still add WebSocket routes after a ws() call, so listen() is the first moment the complete set is known.

import { nodeAdapter } from '@arcton/adapter-node'
import { Arcton } from '@arcton/core'

const app = Arcton()

app.ws('/chat', {
  message(ws, message) {
    ws.send(`echo: ${message}`)
  }
})

app.listen({ adapter: nodeAdapter })

How ws routes differ from HTTP routes

WebSocket routes are matched by exact path — :param and *wildcard segments belong to HTTP routes. They are also served directly by the adapter rather than through the HTTP pipeline, so a socket connection does not run middleware, providers or validation, and the callbacks receive the socket rather than a context.

To gate a connection, check inside open and close the socket when the check fails:

import { Arcton } from '@arcton/core'

const rooms = new Set(['general', 'random'])

const app = Arcton()

app.ws('/room', {
  open(ws) {
    ws.send('joined')
  },
  message(ws, message) {
    const room = String(message)

    if (!rooms.has(room)) {
      ws.close(1008, 'unknown room')
      return
    }

    ws.send(`welcome to ${room}`)
  }
})

app.listen()

Connecting from a client

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

socket.addEventListener('open', () => {
  socket.send('hello')
})

socket.addEventListener('message', event => {
  console.log(event.data)
})

On this page