Ir al contenido
Español

Chat sample

Esta página aún no está disponible en tu idioma.

The chat sample is a complete demo app showing how the framework’s pieces compose:

  • TCP cluster of 3 Bun processes, joined via gossip.
  • Sharded chat-room actors — one ChatRoomActor per room, spread across the cluster as 16 shards.
  • DistributedPubSub for cross-node chat-room broadcasts.
  • PersistentActor for chat-room history (SQLite journal + snapshots).
  • DistributedData for presence, the runtime room directory, and read receipts.
  • ClusterSingleton HTTP front door — one node binds :8080; a survivor re-binds it on failover.
  • WebSocket-only client protocol — a single /ws endpoint carries login, rooms, history, presence, and messages.

Find it under examples/chat/ in the repo.

:8080

3-node cluster (Bun)

join / send

persist + publish

deliver

presence / receipts

converged state

HTTP ingress
ClusterSingleton — binds :8080
serves static + /ws upgrade

UserSession actors
one per WS connection
holds their socket + state

ChatRoom actors (sharded PersistentActor)
one per room, 16 shards
persists message history

DistributedPubSub
per-room topic
rooms publish; sessions subscribe

DistributedData
ORSet presence + room directory
LWWMap read receipts

WebSocket clients
(6 frontends)

The full path of a “user sends message” flow:

1. The WS client sends a "send" frame over /ws to the ingress singleton.
2. The ingress routes it to that connection's UserSession actor (one per socket).
3. UserSession tells the relevant ChatRoom entity (sharded by room name).
4. ChatRoom persists the message via PersistentActor.persist().
5. ChatRoom publishes to DistributedPubSub on the room's topic.
6. Every UserSession subscribed to that topic receives the message.
7. Each UserSession pushes it to its own WS client.

Cluster + persistence + pubsub + websocket — all working together.

Terminal window
# Clone the repo and install dev deps:
git clone https://github.com/pathosDev/actor-ts.git
cd actor-ts
bun install
# Accept the demo session-token secret for a local run (see below):
export CHAT_ALLOW_DEMO_SECRET=1
# Start a 3-node cluster — three terminals, same command, no flags:
bun examples/chat/backend/main.ts
bun examples/chat/backend/main.ts
bun examples/chat/backend/main.ts
# Open the chat UI (one URL, whichever node holds the singleton):
open http://localhost:8080/

The one variable is deliberate. Session tokens are HMAC-signed and self-validating, so the signing secret is the only thing between a stranger and an arbitrary identity — and a sample that filled an absent secret with a constant published in its own source would come up looking healthy while anyone who had read the repository could mint a token for any user. So the store throws instead, and CHAT_ALLOW_DEMO_SECRET=1 is how a local demo says it accepts that constant knowingly. Anything past a laptop exports CHAT_TOKEN_SECRET instead — the same strong random value on every node, or resume breaks across a fail-over.

Each node runs the same binary. They discover each other by scanning the cluster-port range from 2551, so the three terminals settle on 2551 / 2552 / 2553 with no seeds to configure. The cluster then elects one node to run the HTTP-ingress ClusterSingleton, which binds :8080 and serves the frontend selector plus the /ws endpoint. Persistence is a local SQLite journal + snapshot store under ./data/ — no external database. Kill the node holding the singleton and a survivor re-binds :8080 within a few seconds; the persisted history survives.

smoke-test.ts logs Alice in, sends three messages, waits for the broadcast echoes, then logs Bob in on a fresh connection and checks that he sees Alice’s history — plus direct messages, typing indicators, read receipts and the auth hardening.

Terminal window
# Against the cluster you already have up:
bun examples/chat/smoke-test.ts
# Or let it bring its own node up, on ports of its own —
# that node needs a token secret like any other:
CHAT_ALLOW_DEMO_SECRET=1 bun examples/chat/smoke-test.ts --spawn-backend

--spawn-backend starts a single node on :8090 (cluster :2590) against a scratch journal, and stops it afterwards. Those ports sit outside the backend’s auto-discovery window, so a self-spawned run neither joins nor collides with a cluster you already have running.

That flag is what lets CI run this file unattended: it is part of the example gate, so a framework change that breaks the chat protocol round-trip shows up as a red check.

failover-test.ts, the sibling that kills the singleton holder and waits for a survivor to re-bind :8080, stays a manual step — two of its three backends were seen outliving a clean exit and holding their cluster ports against whatever ran next.

const chatRoomRegion = cluster.sharding.start('ChatRoom', ChatRoomActor,
StartShardingOptions.create<ChatRoomCommand>()
.withExtractEntityId((message) => message.room)
.withNumShards(16));

One ChatRoomActor per room, spread across the cluster as 16 shards — kill any node and the survivors take over its rooms. Direct-message channels use the same pattern in a separate region, keyed on the canonical DM pair-id.

class ChatRoomActor extends PersistentActor<ChatRoomCommand, ChatEvent, ChatState> {
readonly persistenceId = `room-${this.roomName}`;
// ... onCommand persists; onEvent updates state ...
}

Each room actor records every message; recovery replays.

// ChatRoom publishes after persisting:
ps.mediator.tell(new Publish(`room.${roomId}`, message));
// UserSession subscribes when user joins a room:
ps.mediator.tell(new Subscribe(`room.${roomId}`, this.self));

Sessions on any node receive room messages regardless of which node’s ChatRoom is publishing.

class UserSessionActor extends Actor<SessionMessage> {
private ws: WebSocket | null = null;
override onReceive(message: SessionMessage): void {
match(message)
.with({ kind: 'connect-ws' }, (m) => this.onConnectWs(m))
.with({ kind: 'inbound' }, (m) => this.onInbound(m))
.exhaustive();
}
private onConnectWs(message: ConnectWsMessage): void {
this.ws = message.socket;
}
private onInbound(message: InboundMessage): void {
this.ws?.send(JSON.stringify(message.payload));
}
}

Each session holds its user’s WebSocket; sends pushes straight to the client.

  • Sharded daemon processes — the chat sample doesn’t need fixed background workers.
  • Replicated event sourcing — single-writer per room is sufficient.

For those, see the stand-alone snippets or the voice sample.

examples/chat/
├── README.md
├── application.conf # HOCON: log level, gossip cadence
├── data/ # SQLite journal + snapshots (gitignored)
├── backend/
│ ├── main.ts # entry: wiring only (cluster, persistence, sharding, singleton)
│ ├── config.ts # CLI-argument parsing
│ ├── routes.ts # HTTP-DSL route (frontend selector)
│ ├── auth/ # scrypt password verify + HMAC session tokens
│ ├── discovery/ # same-host port-scan seed provider
│ └── actors/
│ ├── ChatRoomActor.ts # sharded PersistentActor (per room)
│ ├── ChatRoomDirectoryActor.ts # DistributedData ORSet (runtime rooms)
│ ├── DirectMessageChannelActor.ts # sharded PersistentActor (per DM pair)
│ ├── UserSessionActor.ts # per-WS-connection session
│ ├── OnlineUsersActor.ts # DistributedData ORSet (presence)
│ ├── ReadReceiptsActor.ts # DistributedData LWWMap (read pointers)
│ ├── HttpIngressActor.ts # ClusterSingleton: owns the :8080 bind
│ └── WebsocketIngressActor.ts # per-connection WS plumbing
├── shared/
│ ├── protocol.ts # shared WS message types
│ ├── rooms.ts # default room list
│ ├── users.ts # test credentials
│ └── directMessage.ts # DM pair-id canonicalization
├── static/ # built frontend assets (@fastify/static)
├── frontend-{plain,angular,react,next,svelte,lit}/ # six UI variants
├── smoke-test.ts # single-node messaging round-trip
└── failover-test.ts # HTTP-singleton fail-over

Every actor lives in its own file under backend/actors/; main.ts is pure wiring. Six frontends share one WebSocket protocol, so you can compare them side-by-side.