Source: docs/connector-sharding.md
Use both dedicated vCPUs. Run multiple connector processes, each owning a disjoint subset of channels, so Baileys' per-channel Signal crypto can finally spread across more than one event loop.
N=1 changes nothing
Motivation
The reconnect and history-decrypt storms that spike CPU are Baileys' per-channel Signal crypto running on the one event loop. They cannot be cleanly offloaded to a worker thread. The only way to parallelize them is multiple processes, each owning a disjoint subset of channels.
Default N=1 reproduces today's behavior exactly; nothing changes until opted in.
Why not the alternatives
Doesn't help. One Node process can't exceed ~1 core no matter how many vCPUs are allocated. Observed: CPU peaks ~55% of 2 vCPUs, about 1.1 cores. The ~0.1 over one core is libuv threadpool / GC spillover, not the event loop.
worker_threads crypto poolOnly offloads the pure media AES (session/media_crypto.ts). The dominant spike is Signal crypto welded to each socket's session state inside Baileys, which is not offloadable. It would smooth a smaller, different peak, not the real one.
Breaks channel affinity. Instance A holds channel X's live socket, but a send job for X could be picked by instance B (no socket), giving "channel not active". This requires deterministic sharding so each channel's jobs and socket live in the same process.
Core contract
A channel's shard is derived from its UUID, computed identically in Python (producer) and TypeScript (connector): first 8 hex chars of the UUID as a 32-bit int, mod N.
Chosen over string-hashing because both languages produce bit-identical results with no shared library. This parity is the single most important invariant. A checked-in test fixture (a handful of UUIDs to expected shard) guards it in both codebases.
int(str(channel_id).replace("-", "")[:8], 16) % shard_count
parseInt(channelId.replace(/-/g, "").slice(0, 8), 16) % shardCount
Queue naming
There are three connector queues today: whatsapp (sends + control), whatsapp_media (inbound media downloads) and whatsapp_avatars (profile pictures). Each shards independently.
Changes: API
apps/apiAdd setting WHATSAPP_SHARD_COUNT (default 1).
def _shard_for(channel_id: UUID) -> int:
n = get_settings().WHATSAPP_SHARD_COUNT
return 0 if n <= 1 else int(str(channel_id).replace("-", "")[:8], 16) % n
def queue_for_channel(base: str, channel_id: UUID) -> str:
n = get_settings().WHATSAPP_SHARD_COUNT
return base if n <= 1 else f"{base}-{_shard_for(channel_id)}"All connector-bound jobs carry a channel_id, so each enqueue(WHATSAPP_QUEUE, …) becomes enqueue(queue_for_channel(WHATSAPP_QUEUE, channel_id), …).
enqueue_connect
enqueue_disconnect
enqueue_send
enqueue_send_media
enqueue_send_location
enqueue_send_reaction
enqueue_mark_read
enqueue_resync_history
enqueue_group_*
enqueue_revoke
enqueue_download_media routes via queue_for_channel(WHATSAPP_MEDIA_QUEUE, …)
enqueue_fetch_avatar routes via queue_for_channel(WHATSAPP_AVATAR_QUEUE, …)
Untouched (consumed by Python workers in the API, not the connector): SCHEDULED, FLOW_RUNS, CHANNEL_PURGE, ORG_PURGE, CHANNEL_REPARENT.
Changes: Connector
apps/baileys-connectorSHARD_COUNT: z.coerce.number().int().positive().default(1),
SHARD_INDEX: z.coerce.number().int().nonnegative().default(0),Validate SHARD_INDEX < SHARD_COUNT at parse time.
shardForChannel(channelId, shardCount) matching the Python contract, plus its parity test.
createWorkers() computes queue names from the shardwhatsapp + whatsapp_media + whatsapp_avatars (as today).
N > 1: consume all three with the -{SHARD_INDEX} suffix.
Drain path: shard 0 additionally consumes the legacy bare whatsapp / whatsapp_media / whatsapp_avatars queues so any jobs enqueued before the cutover deploy still get processed. Same spirit as the existing "main worker still accepts fetch_avatar" straggler-drain.
reconcileActiveChannels to this shardids = ids.filter(
(id) => shardForChannel(id, config.SHARD_COUNT) === config.SHARD_INDEX,
);getActiveChannels() (the GET /internal/v1/channels/active call) stays unchanged. Filtering is local, so the API endpoint needs no shard awareness.
The per-channel cross-process lock (entry.lock) already guards against two processes owning the same channel during a rebalance. No change needed; it is the safety net.
src/index.ts: deploy shape
Keeps the current $78 / 4 GB / 2-vCPU box. If SHARD_COUNT > 1 and running as a single component, the primary cluster.fork()s SHARD_COUNT workers; each worker derives SHARD_INDEX = cluster.worker.id - 1. Node's cluster auto-shares the health port.
Each fork keeps its own in-memory active / LRU / locks, which is the isolation we want. The 4 GB is split across the two forks (~2 GB each effective), fine since each handles half the channels/backfills.
Run two components, each with static SHARD_INDEX=0/1 + SHARD_COUNT=2 in env, cluster disabled. Same sharding code.
Cost at 2 × (2 GB / 1 vCPU) is about the same as one 4 GB / 2-vCPU box.
The one hard invariant
WHATSAPP_SHARD_COUNT must equal connector SHARD_COUNTIf they disagree, some jobs land on a queue no one consumes.
Set it once at the app-platform level and reference the same var in both components.
Shard-0's legacy-queue drain catches the N-mismatch-to-1 direction.
Log the effective shard config loudly on boot in both apps.
Rollout
N = 1 everywhere
Queue names unchanged, so provably no behavior change. Exercises the new code paths in prod at zero risk.
Set API WHATSAPP_SHARD_COUNT=2 and connector SHARD_COUNT=2 (cluster ×2) in one coordinated release. Shard-0 drains any legacy stragglers. Watch both cores light up.
Set both back to 1 and redeploy; the legacy queue resumes.
reconcileActiveChannels filters correctly (extend the existing fakes in src/whatsapp/reconcile-workers.test.ts).
Producer routes to whatsapp-{i} when N > 1, bare whatsapp when N = 1.
app/queue/producer.py, app/config.py.
Connector (6): src/config.ts, src/queue/worker.ts, src/whatsapp/manager.ts, src/index.ts, new src/whatsapp/shard.ts + test.
No DB migration, no API endpoint changes, no schema changes.
Main risks
N changesSessions are durable in S3, the cross-process lock handles handoff, and BullMQ retries any send that races the handoff. Acceptable and self-healing.
Notes / open questions
entry.lock Redis-backed?Confirm it is cross-process, not in-memory, before relying on it as the rebalance safety net. Referenced in manager.ts as entry.lock.release().
Cluster keeps the current single box and billing; separate components give hard memory isolation. The code should support both via the SHARD_INDEX-from-env path so the choice is deployment-only.
send-guard Redis keysgetCachedProviderId / markSent are keyed by messageId and shared across processes. Safe under sharding, no change.