WebSocket

Katman's default transport is HTTP — every procedure call is a separate request/response. WebSocket gives you a persistent connection instead. Messages skip the TCP handshake, which makes repeated calls faster and enables real-time server-to-client streaming.

When to use WebSocket

For most APIs, HTTP is the right choice. WebSocket adds value when you need persistent connections or when you're making many calls per second and want to skip the per-request overhead.

Enable with serve()

If you're using serve(), add ws: true:

import { katman } from "katman"

const k = katman({ context: (req) => ({}) })
const { query, subscription, router } = k

const appRouter = router({
  health: query(() => ({ status: "ok" })),
  countdown: subscription(async function* () {
    for (let i = 5; i > 0; i--) {
      yield { count: i }
      await new Promise((r) => setTimeout(r, 1000))
    }
  }),
})

k.serve(appRouter, {
  port: 3000,
  ws: true,
})

HTTP and WebSocket share the same port. The server detects WebSocket upgrade requests and routes them to the WebSocket handler. Powered by crossws.

Standalone setup

If you have your own HTTP server (or an existing Fastify/Express app), attach WebSocket separately:

import { createServer } from "node:http"
import { attachWebSocket } from "katman/ws"

const server = createServer(yourHttpHandler)
attachWebSocket(server, appRouter)
server.listen(3000)

attachWebSocket listens for the upgrade event on the HTTP server and handles WebSocket connections.

Message protocol

Every WebSocket message is a JSON object. The id field links requests to responses, so the client can send multiple requests concurrently and match them up.

Request and response

The client sends a request with a path and optional input:

{ "id": "1", "path": "users/list", "input": { "limit": 10 } }

The server responds with the result:

{ "id": "1", "result": [{ "id": 1, "name": "Alice" }] }

Errors

If the procedure fails, the server sends an error:

{ "id": "2", "error": { "code": "NOT_FOUND", "status": 404, "message": "Procedure not found" } }

Streaming (subscriptions)

For procedures defined with k.subscription(), the server sends multiple data messages followed by a done signal:

{ "id": "3", "data": { "count": 5 } }
{ "id": "3", "data": { "count": 4 } }
{ "id": "3", "data": { "count": 3 } }
{ "id": "3", "data": { "count": 2 } }
{ "id": "3", "data": { "count": 1 } }
{ "id": "3", "data": null, "done": true }

The done: true message signals that the stream has ended.

Client example

Here's a basic client using the native WebSocket API:

const ws = new WebSocket("ws://localhost:3000")

// Track pending requests by ID
const pending = new Map<string, (msg: any) => void>()
let nextId = 1

function call(path: string, input?: unknown): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const id = String(nextId++)
    pending.set(id, (msg) => {
      pending.delete(id)
      if (msg.error) reject(msg.error)
      else resolve(msg.result)
    })
    ws.send(JSON.stringify({ id, path, input }))
  })
}

ws.onopen = async () => {
  const users = await call("users/list", { limit: 10 })
  console.log("Users:", users)
}

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data)
  const handler = pending.get(msg.id)
  if (handler) handler(msg)
}

Receiving streams

For subscriptions, you'll receive multiple messages with the same id:

ws.onmessage = ({ data }) => {
  const msg = JSON.parse(data)

  if (msg.done) {
    console.log("Stream ended for", msg.id)
  } else if (msg.data !== undefined) {
    console.log("Stream data:", msg.data)
  } else if (msg.error) {
    console.error("Error:", msg.error)
  } else {
    console.log("Result:", msg.result)
  }
}

Binary WebSocket

Combine WebSocket with MessagePack for smaller messages. Pass binary: true when attaching:

import { attachWebSocket } from "katman/ws"

attachWebSocket(server, appRouter, { binary: true })

With binary mode, messages are sent as MessagePack-encoded binary frames instead of JSON text. On the client side, you'd use msgpack to encode/decode instead of JSON.parse/JSON.stringify.

What's next?

• MessagePack — binary encoding for smaller payloads
• devalue — rich type serialization for Date, Map, Set
• Server — serve() options and lifecycle hooks
• Procedures — defining subscriptions with k.subscription()