ShardBus
ShardBus (from @lunibee/sharding) passes messages between shards. Each shard (or each process standing in for one) creates a bus with its shard ID and a channel name shared by the whole bot, then:
- sends a message to one shard, or broadcasts to every other shard;
- asks one shard a question and waits for its answer (
request/respond); - asks every shard and collects the answers (
broadcastRequest).
It never evaluates code it receives: a request names a handler type, and only handlers you registered with respond() answer.
The transport is chosen for you: a BroadcastChannel inside one process, IPC inside a worker forked by ClusterManager, relayed by the parent to the other clusters. See Sharding for the overall picture and ShardManager for running the shards.
import { ShardBus, BroadcastChannelTransport, IpcTransport } from "@lunibee/sharding";// also re-exported:import { ShardBus } from "lunibee";import { ShardBus, BroadcastChannelTransport, IpcTransport } from "@lunibee/sharding";// also re-exported:import { ShardBus } from "lunibee";The types ShardMessage, ShardReply, ShardMessageHandler, ShardBusErrorHandler, ShardBusOptions, ShardBusTransport and IpcEndpoint are exported from both packages too.
The examples below are TypeScript; the JavaScript is the same without type annotations.
Quick start
Section titled âQuick startâimport { ShardBus } from "lunibee";
const bus = new ShardBus(shardId, "my-bot");
// Fire and forget.bus.on<{ section: string }>("reload", (message) => reloadConfig(message.data.section));bus.broadcast("reload", { section: "commands" });
// Request and reply.bus.respond("guildCount", () => guildCache.size);const onShard1 = await bus.request<number>(1, "guildCount", null);const others = await bus.broadcastRequest<number>("guildCount", null, { expected: totalShards - 1,});const total = guildCache.size + others.reduce((sum, reply) => sum + (reply.result ?? 0), 0);
// Handler failures.bus.onError((error, message) => console.error(`handler for ${message.type} failed`, error));
// When the shard stops.bus.close();Constructor
Section titled âConstructorânew ShardBus(shardId: number, channelName: string, options?: ShardBusOptions)| Parameter | Type | Description |
|---|---|---|
shardId |
number |
The shard this bus speaks for. Messages addressed to it are delivered here; its own messages are never delivered back to it. A non-negative integer. |
channelName |
string |
A name shared by every bus of the bot, such as the botâs name. Trimmed. Buses with different names do not hear each other on a BroadcastChannel. |
options.transport |
ShardBusTransport |
How messages travel. Default: IpcTransport inside a worker forked by ClusterManager, else BroadcastChannelTransport(channelName). See Transports. |
options.maxPending |
number |
Most requests (request and broadcastRequest together) waiting for replies at once. Default 10000. Further ones reject at once. |
The constructor throws RangeError if shardId is not a non-negative integer and TypeError if channelName is empty or blank.
Properties
Section titled âPropertiesâ| Property | Type | Description |
|---|---|---|
channelName |
string |
The trimmed channel name. Message IDs are channelName:shardId:counter. |
Methods
Section titled âMethodsâsend(target, type, data)
Section titled âsend(target, type, data)âSends data to shard target under type. Returns the message ID. Nothing confirms delivery; a message to a shard that does not exist or has no handler for type is dropped.
bus.send(3, "invalidate", { guildId });Throws RangeError if target is not a non-negative integer, TypeError if type is blank, and Error("ShardBus is closed.") after close().
broadcast(type, data)
Section titled âbroadcast(type, data)âSends data to every other shard. Returns the message ID. Same errors as send (without the target check).
bus.broadcast("reload", { section: "commands" });on(type, handler), off(type, handler)
Section titled âon(type, handler), off(type, handler)âAdd or remove a handler for messages of type. A handler receives the whole ShardMessage. Several handlers per type are allowed; each runs once per message. Both return the bus. on throws TypeError for a blank type or a handler that is not a function.
const onReload = (message: ShardMessage<{ section: string }>) => reloadConfig(message.data.section);bus.on("reload", onReload);bus.off("reload", onReload);A handler may be async. If it throws or its promise rejects, the error goes to the error listeners; later handlers and messages are not affected.
respond(type, handler)
Section titled ârespond(type, handler)âRegisters a handler that answers requests of type. It receives the payload and the message, and its return value (awaited) is sent back to the requesting shard; a thrown error is sent back as its message. Returns the bus.
bus.respond<{ guildId: string }, boolean>("hasGuild", ({ guildId }) => guildCache.has(guildId));It only answers messages sent with request() or broadcastRequest() (or by ClusterManager.request() / broadcast()); a plain send() or broadcast() of the same type does not trigger a reply. off(type, handler) with the same handler removes a respond() handler.
request(target, type, data, timeoutMs?)
Section titled ârequest(target, type, data, timeoutMs?)âSends a request to one shard and resolves with its handlerâs result.
const count = await bus.request<number>(1, "guildCount", null, 2000);| Parameter | Default | Description |
|---|---|---|
target |
â | The shard to ask. A non-negative integer. |
type |
â | The handler type registered with respond() on that shard. |
data |
â | The payload. |
timeoutMs |
5000 |
How long to wait for the reply. |
It rejects with:
| Error | When |
|---|---|
RangeError |
target is not a non-negative integer. |
Error(<handler's message>) |
The handler on that shard threw. |
Error('Shard N did not reply to "type" within Tms.') |
No reply in time: no such shard, no handler, a slow handler, or a dropped message. |
Error("Shard N went away before it replied.") |
The transport reported that shard gone (its cluster died, or the parent could not reach it). |
Error("Too many shard requests waiting for a reply (maxPending).") |
maxPending requests are already waiting. |
Error("ShardBus is closed.") |
The bus was closed before or while waiting. |
broadcastRequest(type, data, options?)
Section titled âbroadcastRequest(type, data, options?)âSends a request to every other shard and collects the replies. It resolves when expected replies have arrived or timeoutMs has passed, with whatever arrived. A shard that is down, slow or has no handler is simply missing from the list.
| Option | Default | Description |
|---|---|---|
timeoutMs |
5000 |
How long to collect. |
expected |
Infinity |
Resolve as soon as this many replies arrived. Without it the call always waits the full timeoutMs. |
const replies = await bus.broadcastRequest<number>("guildCount", null, { timeoutMs: 3000, expected: totalShards - 1, // every shard but this one});for (const reply of replies) { if (reply.error !== undefined) console.warn(`shard ${reply.shardId}: ${reply.error}`);}It does not reject for a timeout or a shard going away, and close() resolves it with the replies collected so far. It rejects only when the bus is already closed, when maxPending requests are waiting, or for a blank type.
The requesting shard is not asked, so add its own answer yourself if you need a total.
onError(handler), offError(handler)
Section titled âonError(handler), offError(handler)âAdd or remove a listener for errors thrown or rejected by on handlers. Return the bus. onError throws TypeError if handler is not a function. See Error handling.
close()
Section titled âclose()âCloses the bus: pending request()s reject with "ShardBus is closed.", pending broadcastRequest()s resolve with what they have, the transport is closed, and every handler and error listener is removed. Calling it again does nothing. After it, send and broadcast throw and request and broadcastRequest reject.
Message shapes
Section titled âMessage shapesâShardMessage
Section titled âShardMessageâWhat handlers receive, and what transports carry.
interface ShardMessage<T = unknown> { source: number; // sending shard ID (-1 for the ClusterManager parent) target: number | null; // target shard ID, or null for a broadcast type: string; // the message type data: T; // the payload id: string; // unique message ID, "channelName:shardId:counter" expectsReply?: boolean; // set on requests}ShardReply
Section titled âShardReplyâOne entry of a broadcastRequest() result.
interface ShardReply<R = unknown> { shardId: number; // the shard that answered result?: R; // the handler's result, when it succeeded error?: string; // the handler's error message, when it threw}Handler types
Section titled âHandler typesâtype ShardMessageHandler<T = unknown> = (message: ShardMessage<T>) => unknown;type ShardBusErrorHandler = (error: unknown, message: ShardMessage) => void;Payloads
Section titled âPayloadsâdata must survive the transport. A BroadcastChannel uses the structured clone algorithm (plain objects, arrays, Map, Date, typed arrays; no functions or class instances with methods). IPC between forked clusters sends JSON, so across clusters data should be JSON-safe: a Map arrives as {}, a Date as a string, undefined fields disappear, and a bigint cannot be sent. Send plain data such as IDs and counts, not structures like Guild or Collection.
Replies use the reserved type "__lunibee:reply"; do not use it for your own messages.
Envelope validation
Section titled âEnvelope validationâEvery message arriving from a transport is untrusted input. A bus drops, without calling any handler, a message that is not an object or whose:
typeis not a string of 1 to 256 characters;idis not a string of at most 256 characters;sourceis not an integer of at least-1;targetis neithernullnor an integer of at least-1.
It also ignores its own messages (source equal to its shard ID) and messages addressed to another shard. A reply is dropped unless its payload is an object with a string requestId.
Replies and request safety
Section titled âReplies and request safetyâ- Only the asked shard can answer a
request(). A reply counts only if itssourceis the shard the request was sent to; nobody can settle a request by guessing its ID. - A shard counts once in a
broadcastRequest(), however many replies it sends. - Late, unknown and duplicate replies are dropped. Once a request has settled or timed out, its ID is forgotten.
- Requests are bounded by
maxPending, and each one is released when it settles. - A dead shard fails fast. When the transport reports shards gone (
onPeerDown), onlyrequest()s addressed to them reject, once each, instead of waiting for their timeout. - Handlers never see code to run. Only types registered with
respond()answer.
Between clusters, the ClusterManager drops a message whose source is not one of the sending clusterâs own shards, so a worker cannot speak for another clusterâs shard. Within one process, or over a BroadcastChannel, the bus cannot prove who wrote a message, so it is a channel between parts of your own bot, not a boundary against code you do not trust.
Error handling
Section titled âError handlingâErrors thrown synchronously by an on handler, and rejections of an async one, are caught per handler and passed to every onError listener with the message being handled. A listener that throws is ignored. With no listener, the error is raised as a process warning with code LUNIBEE_SHARD_BUS_ERROR (visible with process.on("warning")), never dropped silently.
bus.onError((error, message) => { logger.error({ type: message.type, from: message.source, error }, "shard bus handler failed");});Errors thrown by a respond handler are not reported here: they are sent back to the requester, where request() rejects with the message and broadcastRequest() lists it as error.
Transports
Section titled âTransportsâA transport carries ShardMessages between buses:
interface ShardBusTransport { post(message: ShardMessage): void; // send to the other buses onMessage(listener: (message: ShardMessage) => void): void; // receive from them onPeerDown?(listener: (shardIds: readonly number[]) => void): void; // optional: shards that died close(): void; // stop and release}post does not need to deliver a message back to the bus that sent it. onPeerDown is optional; without it a request to a dead shard waits for its timeout.
Default selection
Section titled âDefault selectionânew ShardBus(id, name) without transport uses:
IpcTransportwhenLUNIBEE_SHARD_BUSis"ipc"and the process has an IPC channel (process.send).ClusterManagersets this variable in every worker it forks.BroadcastChannelTransport(channelName)otherwise.
BroadcastChannelTransport
Section titled âBroadcastChannelTransportânew BroadcastChannelTransport(name: string)A named BroadcastChannel. Buses in the same process, or in worker threads of it, with the same channelName hear each other. It does not cross fork()ed processes and does not report peers going away.
IpcTransport
Section titled âIpcTransportânew IpcTransport(endpoint?: IpcEndpoint)Sends each message to the parent process over IPC, wrapped in a { __lunibeeBus: message } frame so it cannot be confused with the botâs own process.send() traffic, and receives the frames the parent relays. It also handles the parentâs notice that a clusterâs shards are gone (onPeerDown). Other IPC messages are ignored.
endpoint defaults to process. It throws Error if the endpoint has no send function (the process was not forked with an IPC channel). close() removes its message listener.
interface IpcEndpoint { send?(message: unknown): unknown; on(event: "message", listener: (message: unknown) => void): unknown; off(event: "message", listener: (message: unknown) => void): unknown;}A custom transport
Section titled âA custom transportâImplement ShardBusTransport to carry messages over something else, such as Redis pub/sub or NATS between machines, or an in-memory hub in tests:
import { ShardBus, type ShardBusTransport, type ShardMessage } from "lunibee";
class RedisTransport implements ShardBusTransport { #listener?: (message: ShardMessage) => void;
constructor(private readonly pub: RedisClient, private readonly sub: RedisClient, private readonly channel: string) { sub.subscribe(channel, (raw) => this.#listener?.(JSON.parse(raw))); } post(message: ShardMessage): void { void this.pub.publish(this.channel, JSON.stringify(message)); } onMessage(listener: (message: ShardMessage) => void): void { this.#listener = listener; } close(): void { void this.sub.unsubscribe(this.channel); }}
const bus = new ShardBus(shardId, "my-bot", { transport: new RedisTransport(pub, sub, "my-bot:bus") });(RedisClient stands for whichever client you use.) A bus validates every incoming envelope and ignores its own messages, so a transport may deliver everything to everyone. Parse incoming data defensively; a transport that throws in post makes send and broadcast throw and request and broadcastRequest reject.
Across clusters
Section titled âAcross clustersâInside workers forked by ClusterManager, every bus uses IpcTransport and the parent routes the frames:
- A message to a shard goes only to the cluster that owns that shard.
- A broadcast goes to every other cluster.
- If the owning cluster is down or cannot be reached, the parent tells the sender that the shard is gone, so a
request()to it rejects at once ("went away before it replied"). - When a cluster exits, the parent tells every other cluster that its shards are gone, so pending
request()s to them reject. - A message to a shard that is not part of the deployment is dropped (a request to it times out).
- The parent relays only the documented envelope fields (
source,target,type,data,id,expectsReply), and drops an envelope whosetypeoridis not a string of the allowed length or whosesourceortargetis not an integer (or anulltarget). It also drops a message whosesourceis not a shard of the cluster that sent it. - A message whose
datais larger thanmaxMessageBytes(8 MiB by default, in UTF-8 bytes: a string as it is, anything else as its JSON text) is not relayed; the parent emitserror, and a request waiting for it times out.
The parent only relays to other clusters. Buses in the same worker process reach each other directly: every IpcTransport on one process endpoint delivers its messages to the others locally (a copy, on a microtask), and each bus drops what is not addressed to it. So send(), broadcast() and request() work the same whether the target shard is in this worker or another.
ClusterManager can also ask shards itself: request(shardId, type, data) and broadcast(type, data) in the parent reach the same respond() handlers, with source set to -1. Its broadcast() expects one answer per shard of the deployment, so register the handler on a bus for every shard the worker owns:
// In the worker scriptconst manager = new ShardManager({ token: process.env.DISCORD_TOKEN!, intents });for (const id of manager.shardIds) new ShardBus(id, "my-bot").respond("guildCount", () => countGuildsOn(id));await manager.connect();
// In the parentconst { replies, missing } = await clusters.broadcast<number>("guildCount", null);Its answers are accepted only from the cluster that owns the shard. See ClusterManager for request(), broadcast(), requestCluster(), requestTimeout, maxPendingRequests and maxMessageBytes.
Testing
Section titled âTestingâPass an in-memory transport to run several buses in one test without channels or processes:
class Hub { readonly members = new Set<MemberTransport>(); deliver(from: MemberTransport, message: ShardMessage) { for (const member of this.members) if (member !== from) queueMicrotask(() => member.listener?.(message)); }}class MemberTransport implements ShardBusTransport { listener?: (message: ShardMessage) => void; constructor(private readonly hub: Hub) { hub.members.add(this); } post(message: ShardMessage) { this.hub.deliver(this, message); } onMessage(listener: (message: ShardMessage) => void) { this.listener = listener; } close() { this.hub.members.delete(this); }}
const hub = new Hub();const a = new ShardBus(0, "test", { transport: new MemberTransport(hub) });const b = new ShardBus(1, "test", { transport: new MemberTransport(hub) });b.respond("ping", () => "pong");expect(await a.request(1, "ping", null)).toBe("pong");