DEV Community: Daniel Kalevski

Building Real-Time Apps in Node.js with Rivalis: WebSockets, Rooms, Actors, and a Binary Wire

Daniel Kalevski — Fri, 22 May 2026 12:10:25 +0000

If you have ever tried to build a multiplayer game, a collaborative editor, or a chat server in Node.js, you have probably written the same boilerplate twice: a ws server, a map of socket → user, a map of room → users, an auth handshake, a heartbeat, a rate limiter, a reconnect loop on the client, and a bespoke binary or JSON protocol gluing it all together.

Rivalis is the framework I wish I had the first time I wrote that boilerplate. It splits into two packages:

@rivalis/core — the Node.js server. Rooms, actors, auth middleware, pluggable transports, and a binary wire format.
@rivalis/browser — a small typed browser client with reconnect, token-refresh, and Sec-WebSocket-Protocol ticket delivery.

Both are MIT licensed, TypeScript-first, and at v6 on npm. Let's walk through the design and then build a small example.

A small note before we dive in

I want to be honest about what this project is, because I think it matters.

Rivalis is my pet project. I have been working on it since 2022, on and off, in evenings and weekends and the quiet stretches between deadlines. It started because I kept making the same mistakes every time I built a multiplayer backend — the same race conditions, the same auth handshake bugs, the same "why is this socket leaking memory at 3 AM" moments. After the third or fourth time, I realized the lesson was not "be more careful next time." The lesson was "stop rewriting this from scratch."

So the goal of Rivalis is simple: take everything I have learned about building real-time multiplayer servers — the close-code conventions, the timing-safe comparisons, the heartbeat tuning, the way you should never trust the client's clock, the difference between rate limiting at the socket layer and at the room layer — and bundle it into something other people can use without paying the same tuition I did. If it saves even one person a weekend of debugging, that is the project earning its keep.

It is also not just a hobby anymore. The framework has been quietly battle-tested in a handful of companies over the past couple of years, running multiplayer game servers and real-time collaboration backends in production, and the results have been honestly better than I expected. Long-uptime, low-incident, the kind of boring stability you actually want from a real-time layer. That feedback loop — seeing it survive contact with real users — is what pushed me to keep polishing the API and finally write this article.

If you find rough edges, please tell me. The whole point is that you should not have to learn them the hard way.

The mental model

Rivalis gives you four primitives:

Primitive	What it is
Rivalis	The server entrypoint. Holds your transports, auth, rate limiter, and room manager.
Room	A named space you subclass. Binds inbound topics to handlers; broadcasts to its members.
Actor	A per-connection handle inside a room. Carries `data` returned by auth, plus `id`, `send`, `kick`.
AuthMiddleware	One method — `authenticate(ticket)` — returns `{ data, roomId }` or `null`.

The data flow on every connection:

client.connect(ticket)
        │
        ▼
  AuthMiddleware.authenticate(ticket)
        │
   ┌────┴────┐
   │         │
  null    { data, roomId }
   │         │
  close   join room → Actor
4001       (onJoin fires)

That is the whole shape. Everything else — heartbeats, rate limiting, presence, reconnects — is configured, not coded.

Hello world: an echo chat server

The server, in full:

import http from 'http'
import {
    Rivalis, Transports, Room, AuthMiddleware,
    type AuthResult, type Actor
} from '@rivalis/core'

type ActorData = { name: string }

class ChatRoom extends Room<ActorData> {
    protected override presence = true   // auto __presence:join / __presence:leave

    protected override onCreate() {
        this.bind('chat', this.onChat)
    }

    protected override onJoin(actor: Actor<ActorData>) {
        actor.send('welcome', JSON.stringify({ youAre: actor.data?.name ?? '' }))
    }

    private onChat(actor: Actor<ActorData>, payload: Uint8Array) {
        this.broadcast('chat', payload)
    }
}

class Auth extends AuthMiddleware<ActorData> {
    override async authenticate(ticket: string): Promise<AuthResult<ActorData> | null> {
        const name = ticket.trim()
        if (!name || name.length > 20) return null
        return { data: { name }, roomId: 'global' }
    }
}

const server = http.createServer()
const rivalis = new Rivalis<ActorData>({
    transports: [new Transports.WSTransport({ server })],
    authMiddleware: new Auth()
})
rivalis.rooms.define('chat', ChatRoom)
rivalis.rooms.create('chat', 'global')
server.listen(8080, () => console.log('ws://localhost:8080'))

process.on('SIGINT', async () => { await rivalis.shutdown(); process.exit(0) })

The browser side is just as small:

import { WSClient } from '@rivalis/browser'

const ws = new WSClient<'chat' | 'welcome'>('ws://localhost:8080')
const enc = new TextEncoder()
const dec = new TextDecoder()

ws.on('client:connect', () => console.log('connected'))
ws.on('welcome', (p) => console.log('welcome:', dec.decode(p)))
ws.on('chat', (p) => console.log('chat:', dec.decode(p)))

ws.connect('alice')
ws.send('chat', enc.encode('hello world'))

That is a complete real-time chat. No express, no socket.io, no Redis. Run it.

Rooms are where the logic lives

A Room is a class you subclass. It has lifecycle hooks (onCreate, onJoin, onLeave, onDestroy) and a small API surface:

Method	Purpose
`bind(topic, listener)`	Register inbound topic handler.
`bindAny(listener)`	Wildcard fallback for unbound topics.
`send(actor, topic, payload)`	Unicast.
`broadcast(topic, payload)`	Fan-out.
`each(fn)`	Iterate room actors.
`kick(actor, payload?)`	Disconnect with a reason.
`destroy()`	Tear down the room.

A few details worth knowing:

maxActors and joinable are simple instance fields. Set maxActors = 4 and the fifth joiner gets closed with room_full.
presence = true auto-broadcasts __presence:join and __presence:leave with a JSON payload describing the joining/leaving actor. You can override presencePayload(actor) to scrub server-only fields out before the broadcast.
Reserved topics. The __ prefix is reserved for framework events. bind/unbind throw if you try to claim one.
unknownTopicPolicy defaults to 'kick' — an actor sending a topic nobody bound is treated as misbehaving. Switch to 'drop' for permissive apps.

The Room API is deliberately small. Game state, lobbies, turn logic — that is all just code you write inside your subclass.

Actors carry your auth payload

Whatever your AuthMiddleware.authenticate returns in data is stamped on the Actor for the lifetime of the connection. That means after auth, the room never needs to look up "who is this user" — the data is already on the actor:

class JWTAuth extends AuthMiddleware<{ userId: string; tier: 'free' | 'pro' }> {
    override async authenticate(ticket: string) {
        const claims = await verifyJwt(ticket)
        if (!claims) return null
        return {
            data: { userId: claims.sub, tier: claims.tier },
            roomId: claims.room
        }
    }
}

Inside the room:

private onChat(actor: Actor<{ userId: string; tier: 'free' | 'pro' }>, payload: Uint8Array) {
    if (actor.data?.tier !== 'pro' && payload.byteLength > 256) return
    this.broadcast('chat', payload)
}

Actor also has save<T>(key, value) and get<T>(key) for per-actor scratch state — handy for in-room counters, last-seen timestamps, anti-spam buckets.

One security note from the docs that is worth repeating. Any secret comparison inside authenticate — HMACs, signatures, session tokens — must use crypto.timingSafeEqual or an equivalent constant-time comparator. === and Buffer.compare short-circuit on first mismatch and leak the prefix length under enough samples. The framework cannot enforce this for you; if you compare a signature with ===, you have built a timing oracle.

The wire is binary, but opaque

Every frame on the wire is { topic: string, payload: bytes }. The framework does not inspect payload. You encode it however you want — JSON, protobuf, msgpack, raw bytes, a hand-rolled struct.

For a chat app, JSON over TextEncoder is fine:

const enc = new TextEncoder()
const dec = new TextDecoder()

export const encode = <T>(v: T): Uint8Array => enc.encode(JSON.stringify(v))
export const decode = <T>(p: Uint8Array): T => JSON.parse(dec.decode(p)) as T

For a 60 Hz multiplayer game, swap in @bufbuild/protobuf or msgpackr. The wire layer does not care. It does enforce one thing: frames are binary. Send a text frame and the server closes the connection with INVALID_FRAME (4002).

Security defaults that exist on purpose

A lot of WebSocket tutorials end at "and now you have real-time!" without ever mentioning that you have also just opened a fresh attack surface. Rivalis ships defaults for the boring stuff:

Token-bucket rate limiting, on by default — 30 tokens, 30/sec refill. Subclass RateLimiter to swap it out, pass null to opt out.
Heartbeats — 30-second ping with a 2-miss kick. Configurable on WSTransport.
Frame and topic size caps — maxPayload (64 KiB default) and maxTopicLength (256 default). Anything bigger gets dropped at the transport.
Backpressure handling — a per-socket outbound buffer cap (1 MiB default); the onBackpressureDrop hook fires on every dropped frame so you can escalate (e.g. kick the slow actor).
Origin allow-list — pass allowedOrigins to WSTransport and any other Origin header is rejected before auth runs. Required for CSWSH protection if you ever decide tickets ride on cookies.
Pre-handshake connection limiting — subclass ConnectionLimiter to cap how many sockets a single IP can open per second. Rejected with RATE_LIMITED (4005) before any auth code runs.
Ticket via subprotocol — set ticketSource: 'protocol' on both the server and browser client, and the ticket rides on Sec-WebSocket-Protocol instead of ?ticket=. Keeps credentials out of URL access logs and browser history.
Tickets are never logged in plaintext — only an 8-char SHA-256 fingerprint, so a leaked log file does not become a session-takeover.

None of those need code from you on the happy path. The defaults are sane; the knobs exist when you need them.

The browser client is small on purpose

@rivalis/browser has five methods: connect, disconnect, send, on/once/off. Everything else is a configuration choice.

Typed events

The client:* events have typed payloads, and you can constrain user topics through a generic:

type Topics = 'lobby:state' | 'chat' | 'game:tick'

const ws = new WSClient<Topics>('wss://example.com/ws')

ws.on('chat', (p) => { /* p: Uint8Array */ })
ws.on('typo:state', (p) => { ... })            // type error
ws.on('client:kicked', ({ code, reason }) => { ... })

Reconnection done right

const ws = new WSClient(url, {
    reconnect: { maxAttempts: 8, baseDelayMs: 250, maxDelayMs: 5000 }
})

Exponential backoff with jitter. Importantly, reconnect skips terminal close codes. If the server kicked you with INVALID_TICKET, KICKED, or ROOM_REJECTED, the client treats that as a final answer and does not retry. Those mean "the server does not want you back" — silently looping is just noise.

Refreshing short-lived tickets

If your tickets are short-lived JWTs, the getTicket hook is called before every reconnect attempt:

const ws = new WSClient(url, {
    reconnect: true,
    getTicket: async () => {
        const res = await fetch('/api/realtime-token', { credentials: 'include' })
        if (!res.ok) throw new Error('token endpoint failed')
        return await res.text()
    }
})

ws.connect(initialTicket)   // first call still uses its argument verbatim

If getTicket throws, the loop terminates with client:reconnect_failed. You cannot reconnect without a ticket, so there is nowhere to retry to.

Close codes you will actually see

Knowing the close codes is the difference between a useful error UI and "connection lost":

Code	Meaning
`4001`	`INVALID_TICKET` — bad/missing ticket; auth rejected
`4002`	`INVALID_FRAME` — non-binary frame received
`4003`	`KICKED` — server-initiated kick (reason in payload)
`4004`	`ROOM_REJECTED` — `room_full` or `room_not_joinable`
`4005`	`RATE_LIMITED` — pre-handshake connection limiter

The browser client emits client:kicked with { code, reason } parsed for you, so you can route each case to the right UI without peeking into the close payload yourself.

Graceful shutdown

A real deployment needs a clean SIGTERM path. rivalis.shutdown() destroys every room (firing onDestroy and kicking remaining actors with room_destroyed), then disposes every transport (closing live sockets with KICKED + 'server_shutdown'):

process.on('SIGINT',  async () => { await rivalis.shutdown({ timeoutMs: 5000 }); process.exit(0) })
process.on('SIGTERM', async () => { await rivalis.shutdown({ timeoutMs: 5000 }); process.exit(0) })

The timeoutMs is the upper bound for transport disposal. Sockets that have not closed by then get torn down.

When to reach for Rivalis

It is a good fit for:

Multiplayer games — turn-based or real-time, where you want a GameRoom subclass holding authoritative state and broadcasting deltas.
Chat / presence / collaborative cursors — presence: true and a couple of bound topics get you most of the way.
Collaborative editors — the binary-frame primitive plays well with CRDT payloads. Just plumb Yjs or Automerge updates into a topic.
Live dashboards with per-tenant rooms — roomId from your auth payload routes each tenant to their own room.

It is not a queue, an SFU, or a Pub/Sub between Node instances. If you need horizontal fan-out, you compose it — one Redis stream feeding many Rivalis nodes, each broadcasting to its locally-joined actors. The framework deliberately stays inside one process; that is what makes the room/actor model cheap.

A 60-second tasting menu of the surface area

// Server
const rivalis = new Rivalis({ transports: [...], authMiddleware: new MyAuth() })
rivalis.rooms.define('chat', ChatRoom)
rivalis.rooms.create('chat', 'global')
rivalis.connections                       // joined actors
rivalis.sockets                           // open sockets (incl. pre-handshake)
rivalis.logging.level = 'debug'           // built-in logger
await rivalis.shutdown({ timeoutMs: 5000 })

// Room
class GameRoom extends Room<MyData> {
    override maxActors = 4
    override joinable = true
    protected override presence = true
    protected override unknownTopicPolicy = 'drop'
    protected override onCreate() { this.bind('move', this.onMove) }
    protected override onJoin(actor) { actor.send('state', JSON.stringify(state)) }
    protected override onLeave(actor) { /* cleanup */ }
    private onMove(actor, payload) { this.broadcast('state', nextState) }
}

// Browser
const ws = new WSClient<MyTopics>(url, {
    reconnect: { maxAttempts: 8 },
    ticketSource: 'protocol',
    getTicket: refreshJwt
})
ws.on('client:connect', ...)
ws.on('client:kicked', ({ code, reason }) => ...)
ws.connect(jwt)
ws.send('move', encode({ dx: 1 }))

Install and play

npm install @rivalis/core ws @toolcase/base @toolcase/logging @toolcase/serializer
npm install @rivalis/browser

Both packages declare their @toolcase/* and ws dependencies as peers, so you control the versions in your app.

Source: https://github.com/kalevski/rivalis
@rivalis/core on npm: https://www.npmjs.com/package/@rivalis/core
@rivalis/browser on npm: https://www.npmjs.com/package/@rivalis/browser

If you build something on top of it — a game, a tutorial, a CRDT bridge — please open an issue or a PR. Feedback on the security defaults and the binary-frame design is especially welcome.

Happy broadcasting.

Tutorial - Optimizing Memory Consumption in HTML5 Games

Daniel Kalevski — Thu, 12 Jan 2023 01:35:16 +0000

Welcome to my blog post about improving game performance through the use of Object pools.

As a game developer, it's likely that you've had to deal with the problem of instantiating a large number of objects for a specific class, such as particles with a short lifetime that need to be destroyed. One of the challenges of this type of game logic is that JavaScript's model is based on the garbage collection pattern, which means that developers do not have direct control over allocated memory.

Problem

When memory locations (variables) are marked as null, they are collected by the garbage collector and removed from memory. However, when the garbage collector needs to dispose of a lot of objects, it takes a lot of processing time, which can negatively impact the performance of the game.

In that case, if you profile the memory, you will see something like what is shown in the picture below

Solution

But there's a solution to this problem, and it's called the Object pools pattern.

The Object pools pattern is an implementation that helps to reuse disposed objects instead of creating new ones. By reusing objects, we can reduce the number of objects that need to be created and collected by the garbage collector, which in turn improves the performance of the game.

After using Object pools, you will get results like this

Phaser Plus Object Pools

class CreateGameObjects extends Scene {

    onCreate() {
        this.pool.register('myObject', MyObject)

        // create object using pool
        let turtle = this.pool.obtain('myObject')
        this.add.existing(turtle)

        // remove object from scene and retreive back to the pool
        this.children.remove(turtle)
        this.pool.release(turtle)
    }

}

Phaser+ Tutorials: Create new Phaser project in less than a minute

Daniel Kalevski — Tue, 10 Jan 2023 22:00:04 +0000

Hi,

this is my first Phaser tutorial, so I hope it will be useful for all those who plan to start a new project using Phaser.

As part of a phaser-plus project I started recently, there is @phaser-plus/cli - a command line tool for creating and developing Phaser projects.

What is Phaser?

Phaser. is a free and open source software developed and owned by Richard Davey. You can visit their funding page and help them to make Phaser even better.

How do I make a project?

Before you start creating a project, you need to have NodeJS 16+ installed on your machine. If you already have NodeJS 16+ installed, you can create a project by executing:

npx @phaser-plus/cli init --template=phaser my-phaser-game

CLI Features

Simple setup
Hot module reload
Optimized production build
Support for Web workers

Setting up a project to build Air Console game using PhaserJS

Daniel Kalevski — Fri, 04 Mar 2022 14:43:22 +0000

A few months ago, I started my journey developing a game for “AirConsole” using PhaserJS. At the beginning I spent a lot of time setting up my project. That inspired me to develop a command line interface (CLI) tool for simplifying the development environment for Air Console games using web technologies.

What is Air Console ?

Air console is a platform focused on delivering local multiplayer experience using your TV or PC as a game console and your smartphones as controllers / gamepads. Actually the development of the game is divided in two parts, the first part is developing the actual game for the main screen and as a second part is developing the application used by gamepads (smartphones) to interact with the game.

Prerequisites

JavaScript knowledge
NodeJS (v14.0 or higher) installed on your local machine
Code Editor

Project setup

As a first step we need to install the tool that I’ve created for this purpose. The tool is a npm executable published to npmjs.org.

npm install -g airconsole-cli

After successful installation, you can create your project by executing:

airconsole init my-airconsole-game

The previous command should create a directory named my-airconsole-game.

Next steps are installing the dependencies using,

npm install  // (inside project directory "my-airconsole-game")

command inside the “my-airconsole-game” directory and running the project by executing:

npm start

I hope this is helpful.

JavaScript Decorators

Daniel Kalevski — Sun, 18 Feb 2018 02:02:51 +0000

JavaScript developers. Are you using JS Decorators in your projects ? Today I write simple wrapper for better experience with decorators. Important to me is your opinion about this helper library.

Thanks

https://www.npmjs.com/package/decorator-wrapper