ArctonArcton
Enrutamiento

WebSockets

Registrar rutas WebSocket con app.ws(), los callbacks del handler, y cómo se combinan los sockets con los módulos.

app.ws() registra una ruta WebSocket en el mismo servidor que tus rutas HTTP:

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 })

Un cliente que se conecta a ws://localhost:3000/chat recibe el upgrade automáticamente. Todo lo demás en el servidor sigue funcionando sobre HTTP.

El handler

message es el único callback requerido. open, close y drain son opcionales:

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()
CallbackSe llama cuando
message(ws, message)llega un frame — string para texto, ArrayBuffer para binario
open(ws)la conexión quedó establecida
close(ws, code, reason)la conexión se cerró
drain(ws)un socket con backpressure puede aceptar más datos

Cada callback puede ser async.

El socket

El valor ws que se pasa a cada callback ofrece dos métodos:

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() acepta un string, un ArrayBuffer o un typed array. close() toma un código y una razón opcionales.

Frames de texto y binarios

message es un string para frames de texto y un ArrayBuffer para binarios, así que haz el narrowing antes de usarlo:

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 en módulos

Una ruta WebSocket registrada adentro de un módulo recibe los prefixes cuando se monta:

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()

El socket se sirve en /api/chat/room.

Soporte de runtime

Las rutas WebSocket necesitan un adapter que las soporte; tanto el de Bun como el de Node.js lo hacen. La verificación ocurre cuando llamas a listen(), no cuando registras la ruta — montar un módulo todavía puede agregar rutas WebSocket después de una llamada a ws(), así que listen() es el primer momento en que se conoce el conjunto completo.

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 })

En qué se diferencian las rutas ws de las rutas HTTP

Las rutas WebSocket se matchean por path exacto — los segmentos :param y *wildcard pertenecen a las rutas HTTP. También las sirve directamente el adapter en vez del pipeline HTTP, así que una conexión de socket no corre middleware, providers ni validation, y los callbacks reciben el socket en vez de un context.

Para controlar el acceso a una conexión, verifica adentro de open y cierra el socket cuando la verificación falle:

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()

Conectarse desde un cliente

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

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

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

En esta página