WebSockets

Talos models WebSockets as ordinary routes. On the server, @talosjs/socket lets you declare a socket endpoint with the @Route.socket(path, config) decorator and implement a controller whose index(context) runs on connect, with a typed context.channel for subscribing, publishing, and sending. On the client, @talosjs/socket-client ships a typed Socket<SendData, Response> class that auto-detects the protocol, serializes JSON, queues messages until the connection opens, and dispatches typed events. The two ends share the same request/response shapes, so a real-time feature stays type-safe across the wire.

How sockets fit the framework

A socket endpoint is declared with the same decorator family as HTTP routes (@Route.socket) and resolves a container-managed controller, so the routing, validation, roles, and middleware you already use carry over. context.channel exposes subscribe, unsubscribe, publish, send, and close with the response type carried through, so broadcasts and direct replies are checked at compile time. subscribe() joins a channel and publish() fans a message out to every subscriber, which gives you room broadcasting without a separate message bus. The client mirrors the server. Socket<SendData, Response> is parameterized by the same request and response types, so the payload you send and the message you receive are the same shapes on both ends. For auth and guards, ISocketMiddleware runs the same pipeline as HTTP middleware against the socket context before the controller’s index runs.

How it works

A socket route is registered just like an HTTP route, but flagged as a socket and pinned to GET. When a client opens the connection, the matched controller’s index(context) runs once. From there, everything happens through context.channel.

Stage	What happens
Declaration	`@Route.socket(path, config)` registers the controller as a socket route (`isSocket: true`, method `GET`).
Connection	A client connects; socket middleware runs, then the controller’s `index(context)` executes once.
Subscribe	`context.channel.subscribe()` joins the channel so this connection receives published messages.
Broadcast	`context.channel.publish(response)` sends a message to every subscriber of the channel.
Direct reply	`context.channel.send(response)` sends a message back to the connected client only.
Close	`context.channel.close(code?, reason?)` ends the connection with a WebSocket close code.

Unlike an HTTP controller, a socket index returns nothing. It performs side effects on the channel. The IController contract is:

interface IController<T extends ContextConfigType = ContextConfigType> {
  index: (context: ContextType<T>) => Promise<void> | void;
}

See Routing for the decorator family and Controllers for how controllers are resolved.

Server: defining a socket controller

@Route.socket takes the path as its first argument and a config object as its second, the same signature as @Route.get, @Route.post, and the rest. Implement IController from @talosjs/socket and do your work in index using context.channel.

import { Route } from "@talosjs/routing";
import type { ContextType, IController } from "@talosjs/socket";

@Route.socket("/ws/chat", {
  name: "api.chat.connect",
  description: "Connect to the chat socket",
})
export class ChatController implements IController {
  public async index(context: ContextType): Promise<void> {
    // Join the channel so this connection receives published messages
    await context.channel.subscribe();

    // Greet the connecting client directly
    await context.channel.send(
      context.response.json({ event: "welcome", message: "Connected to chat" }),
    );
  }
}

The channel API

context.channel is the typed surface for everything a socket controller does. Every payload is built with context.response (the same response builder as HTTP controllers), so the response type flows through publish and send.

Method	Returns	Description
`subscribe()`	`Promise<void>`	Join the channel so this connection receives published messages.
`isSubscribed()`	`boolean`	Whether this connection is currently subscribed.
`unsubscribe()`	`Promise<void>`	Leave the channel; published messages no longer reach this connection.
`publish(response)`	`Promise<void>`	Broadcast a response to every subscriber of the channel.
`send(response)`	`Promise<void>`	Send a response to the connected client only.
`close(code?, reason?)`	`void`	Close the connection with an optional WebSocket close code and reason.

The full context type extends the HTTP controller context with this channel:

type ContextType<T extends ContextConfigType = ContextConfigType> =
  ControllerContextType<T> & {
    channel: {
      ws: ServerWebSocket<T["response"]>;
      send: (response: IResponse<T["response"]>) => Promise<void>;
      close(code?: number, reason?: string): void;
      subscribe: () => Promise<void>;
      isSubscribed(): boolean;
      unsubscribe: () => Promise<void>;
      publish: (response: IResponse<T["response"]>) => Promise<void>;
    };
  };

Because it extends the controller context, you also get context.params, context.payload, context.queries, context.user, and context.response, the same members you use in HTTP controllers.

A chat room with pub/sub

A realistic room controller uses a path parameter for the room, subscribes the connection, replies directly to the joiner, and publishes a join event to everyone else in the room. Type the context for end-to-end safety.

import { Route } from "@talosjs/routing";
import { type } from "@talosjs/validation";
import type { ContextConfigType, ContextType, IController } from "@talosjs/socket";

interface ChatRoomConfig extends ContextConfigType {
  params: { roomId: string };
  payload: { message: string };
  response: { event: string; roomId: string; message?: string; userId?: string };
}

@Route.socket("/ws/rooms/:roomId", {
  name: "api.rooms.join",
  description: "Join a chat room and broadcast messages",
  params: { roomId: type("string") },
  payload: type({ message: "string" }),
})
export class ChatRoomController implements IController<ChatRoomConfig> {
  public async index(context: ContextType<ChatRoomConfig>): Promise<void> {
    const { roomId } = context.params;
    const { message } = context.payload;

    // Join the room channel
    await context.channel.subscribe();

    // Confirm the join to this client only
    await context.channel.send(
      context.response.json({ event: "joined", roomId }),
    );

    // Broadcast the message to everyone subscribed to the room
    await context.channel.publish(
      context.response.json({
        event: "message",
        roomId,
        message,
        userId: context.user?.id,
      }),
    );
  }
}

To leave a room or end the connection, unsubscribe and optionally close with a WebSocket close code:

if (context.channel.isSubscribed()) {
  await context.channel.unsubscribe();
}

context.channel.close(1000, "Left the room");

Socket middleware

Connection-time interception uses ISocketMiddleware, which mirrors the HTTP IMiddleware shape against the socket context: same decorator, same handler(context) contract, same short-circuiting. Use it for auth and guards before index runs.

import type { ContextType } from "@talosjs/socket";
import { decorator, type ISocketMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class SocketAuthMiddleware implements ISocketMiddleware {
  public async handler(context: ContextType): Promise<ContextType> {
    return context;
  }
}

See Middleware for the full pipeline, ordering, and short-circuit rules.

Client: connecting with @talosjs/socket-client

Socket<SendData, Response> is a thin, typed wrapper over the browser WebSocket. The constructor takes a single URL and auto-detects the protocol: http:// becomes ws://, https:// becomes wss://, and a bare host (no scheme) is upgraded to wss://. Outgoing data is JSON-serialized for you, and incoming messages are parsed back into the typed Response.

import { Socket } from "@talosjs/socket-client";

// http:// -> ws://, https:// -> wss://, bare host -> wss://
const socket = new Socket("https://api.example.com/ws/chat");

socket.onOpen(() => console.log("connected"));
socket.onMessage((response) => console.log("received", response));
socket.onClose((event) => console.log("closed", event.code, event.reason));
socket.onError((event, response) => console.error("error", event, response));

Client methods

The two generic parameters tie the client to the server: SendData (extending RequestDataType) is what you send, and Response is the message shape you receive (wrapped as ResponseDataType<Response>).

Method	Returns	Description
`send(data)`	`void`	JSON-serialize and send `data`; queued if the connection is not yet open.
`onMessage(handler)`	`void`	Register a handler for incoming, successfully-parsed messages.
`onOpen(handler)`	`void`	Register a handler that runs when the connection opens.
`onClose(handler)`	`void`	Register a handler for connection close, receiving the `CloseEvent`.
`onError(handler)`	`void`	Register a handler for errors; also called for messages flagged unsuccessful.
`close(code?, reason?)`	`void`	Close the connection with an optional code and reason.

A few behaviors are worth knowing:

Message queuing. Calling send before the socket is open pushes the message onto an internal queue. The queue is flushed in order as soon as onopen fires, so you never have to wait for the connection by hand.
JSON in and out. send runs JSON.stringify on your data, and incoming frames are JSON.parsed into ResponseDataType<Response> before reaching onMessage.
Success and done flags. A parsed message with success true reaches onMessage. An unsuccessful one is routed to the onError handler with the parsed body instead. If a message carries done, the client closes the connection.
Locale support. RequestDataType includes an optional lang field, so you can attach locale information to any message you send.

Typed client usage

Mirror the server’s request and response shapes for a fully typed exchange. The payload you send matches the controller’s expected payload, and the message you receive matches the controller’s response.

import { Socket, type RequestDataType } from "@talosjs/socket-client";

interface ChatRequest extends RequestDataType {
  payload: { message: string };
  queries?: { roomId: string };
}

interface ChatResponse {
  event: string;
  roomId: string;
  message?: string;
  userId?: string;
}

const socket = new Socket<ChatRequest, ChatResponse>(
  "https://api.example.com/ws/rooms/general",
);

socket.onMessage((response) => {
  // response is typed as ResponseDataType<ChatResponse>
  if (response.data.event === "message") {
    console.log(`${response.data.userId}: ${response.data.message}`);
  }
});

// Safe to call immediately: this is queued until the socket opens
socket.send({
  payload: { message: "Hello, room!" },
  queries: { roomId: "general" },
  lang: { locale: "en" },
});

// Later, close cleanly
socket.close(1000, "User left");

Practical guidance

Call @Route.socket(path, config) with the path as the first argument and the config object second; the config never contains path. Join the channel with subscribe() before you publish(), so the connection receives the broadcasts it triggers, and check isSubscribed() before unsubscribing. Reach for send to reply to the connected client alone and publish to fan a message out to every subscriber. Type both ends. A ContextConfigType on the server and matching SendData/Response generics on the client keep payloads and messages checked across the wire. Put auth and rate limits in ISocketMiddleware so unauthorized connections are rejected before index runs. When you close, pass a standard WebSocket close code (1000 for normal closure, 1008 for policy violations) and a human-readable reason so clients can react. And don’t wait on onOpen to start sending: the client flushes queued messages on open, so calling send as soon as you have data is fine.

Getting Started

AI

Framework

Command Line

How sockets fit the framework

How it works

Server: defining a socket controller

The channel API

A chat room with pub/sub

Socket middleware

Client: connecting with @talosjs/socket-client

Client methods

Typed client usage

Practical guidance

​How sockets fit the framework

​How it works

​Server: defining a socket controller

​The channel API

​A chat room with pub/sub

​Socket middleware

​Client: connecting with @talosjs/socket-client

​Client methods

​Typed client usage

​Practical guidance

How sockets fit the framework

How it works

Server: defining a socket controller

The channel API

A chat room with pub/sub

Socket middleware

Client: connecting with @talosjs/socket-client

Client methods

Typed client usage

Practical guidance