Multi-session deployments

zapo is designed so a single process can drive many accounts off one shared store. Each account lives behind a stable sessionId; everything that’s safe to share (the backend connection pool, the WebSocket factory, the logger) is shared, and everything that’s account-specific (Signal sessions, identities, app-state, mailbox) is partitioned by sessionId.

The pattern

import { createStore, WaClient, createPinoLogger } from 'zapo-js'
import { createPostgresStore } from '@zapo-js/store-postgres'

const store = createStore({
  backends: { postgres: createPostgresStore({ pool: { connectionString: process.env.DATABASE_URL } }) },
  providers: {
    auth: 'postgres', signal: 'postgres', preKey: 'postgres',
    session: 'postgres', identity: 'postgres', senderKey: 'postgres',
    appState: 'postgres', privacyToken: 'postgres',
    messages: 'postgres', threads: 'postgres', contacts: 'postgres'
  }
})

const logger = await createPinoLogger({ level: 'info' })

const clients = ['account-a', 'account-b', 'account-c'].map(
  (id) => new WaClient({ store, sessionId: id }, logger)
)

await Promise.all(clients.map((c) => c.connect()))

sessionId is the durable key for an account — same id across restarts resumes the same paired device. Changing it orphans the previous credentials.

What’s per-session vs shared

Layer	Scope
Backend connection pool / file handle	Shared across all sessions
Per-domain stores (`auth` / `signal` / `preKey` / `session` / `identity` / `senderKey` / `appState` / `privacyToken` / `messages` / `threads` / `contacts`)	Per `sessionId`
Cache domains (`retry` / `groupMetadata` / `deviceList` / `messageSecret`)	Per `sessionId`
L1 `cacheLayer` (when enabled)	Per `sessionId`, per process
`memory.limits` caps	Applied per session (multiply by N for total RAM)
`WaClient` state (handlers, retry queue, coordinators)	Per `WaClient` instance

Switching to a multi-tenant setup is a matter of (1) instantiating N WaClients on the same store, and (2) sizing your backend pool + memory budget for N concurrent sessions.

Session lifecycle

store.session(sessionId) is memoized. The first call materializes the per-domain bundle (per-session locks, optional cache wrappers, …) and caches it inside the store; later calls with the same id return the same bundle.

const a1 = store.session('account-a')
const a2 = store.session('account-a')
a1 === a2 // true

WaClient calls store.session(sessionId) on demand; you do not usually call it yourself.

Adding tenants on the fly

There is no preregistration step — just construct a new WaClient with a new sessionId:

function spawn(sessionId: string): WaClient {
  const client = new WaClient({ store, sessionId }, logger)
  // hook your event listeners, then connect()
  return client
}

Removing tenants

For long-running multi-tenant processes, three options — each with a different scope:

await client.logout() — logical removal. Wipes the persistent state for that sessionId (subject to logoutStoreClear) and unlinks the device server-side. The bundle stays in the in-store map until you destroy it or the process ends; a subsequent WaClient({ store, sessionId }) on the same id reuses the same bundle.
await storeSession.destroy() — mid-process reclaim. Tears down the session’s per-domain stores and evicts the bundle from the in-store map (the sessionId is released as destruction starts), so a concurrent or later store.session(id) builds a fresh bundle. The teardown is idempotent — repeat calls await the same in-flight promise — and teardown failures are logged, never thrown.
await store.destroy() — process shutdown. Tears down every live session and the registered backends. store.session() throws afterwards; the store is single-shot.

For a bounded reset that keeps the session alive, await storeSession.destroyCaches() swaps the cache domains (retry / groupMetadata / deviceList / messageSecret) for freshly-built instances instead of closing them — useful when you want to drop stale entries from a persistent cache backend without losing the session. Concurrent resets are serialized and cache references captured before the call reject afterwards, so recreate the client to pick up the fresh cache stores.

session(id) returns the same bundle instance while it’s alive — so a WaClient holding a stale reference before you destroyed the session keeps hitting the closed bundle. In practice: destroy the client’s connection first (client.disconnect()), then session.destroy(), then build a new client if you want the same sessionId back.

Process ownership

In multi-process deployments, decide how sessionIds map to processes:

One process per sessionId via consistent hashing / sticky routing on the load balancer or queue (simplest).
Leader election before opening the client (a Postgres advisory lock, Redis SET NX, etcd lease) — useful for HA failover.

The opt-in cacheLayer tightens this: its L1 has no cross-process invalidation channel, so a sessionId’s backend rows should be owned by one process across its lifecycle. A takeover process’s L1 starts cold and may serve stale reads before catching up to writes the previous owner made. WaMediaProcessor is a stateless wrapper around your media binaries (sharp, ffmpeg/ffprobe, file-type). The same instance can serve every WaClient — there is no per-session state inside the processor, so reusing it avoids paying the binary-lookup / lazy-import cost N times.

import { createMediaProcessor } from '@zapo-js/media-utils'

const processor = createMediaProcessor()

const clients = tenants.map((id) => new WaClient(
  { store, sessionId: id, media: { processor } }, // same instance, every session
  logger
))

Each processor method receives an optional ctx: WaMediaProcessorCallContext argument carrying that call’s Logger. The runtime fills it with the calling session’s logger, so warnings (missing binary, failed detectMimetype, …) land with the right per-session bindings automatically — no setup needed. Custom processors should consume ctx.logger per call and not cache it, since the same instance is shared across sessions.

Memory budget

WaCreateStoreOptions.memory.limits caps apply per session. With N concurrent sessions, the worst-case in-process RAM scales linearly:

Cap	Per session	With N = 50 sessions
`signalSessions: 5_000`	up to 5 000 Double-Ratchet entries	up to 250 000
`signalRemoteIdentities: 5_000`	up to 5 000 identity rows	up to 250 000
`groupMetadataGroups: 1_000`	up to 1 000 cached groups	up to 50 000
`messages: 10_000` (when `providers.messages: 'memory'`)	up to 10 000 messages	up to 500 000

Tune the per-session caps downward as N grows, or move the mailbox/large-cardinality domains to a persistent backend (the in-memory provider exists for tests and small accounts). TTLs in memory.cacheTtlMs are independent of N — they only cap how long an entry survives in each cache.

Sharding strategies

Layout	Use when
One process · N sessions · one store	A few tenants, all light traffic. Simplest setup; the process is a shared point of failure for all tenants.
N processes · one session each · shared backend	High per-tenant load, or you want blast-radius isolation per tenant. The most robust at scale. Requires a network backend (`@zapo-js/store-postgres` / `mysql` / `redis` / `mongo`).
K processes · M/K sessions each · shared backend	The middle ground at scale. Pack tenants per process until CPU saturates, then add a process. Pair with consistent hashing on `sessionId` so the same account always lands on the same process.

@zapo-js/store-sqlite is single-host only and the SQLite file is held by one process — pick one of the network backends for any layout with more than one process.

Graceful shutdown

async function shutdown() {
  await Promise.all(clients.map((c) => c.disconnect()))
  await store.destroy()
}
for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.on(signal, shutdown)
}

client.disconnect() flushes the per-session write-behind queue and closes the socket without unlinking the device, so the next boot resumes from the store. store.destroy() then releases the shared backend (pool, file handle, …). Calling disconnect() on every client before store.destroy() ensures each session’s pending writes flush; store.destroy() does not do that for you.

Don’t substitute logout() for disconnect() here — logout() unlinks the device server-side and clears stored state. Use it only when you intentionally want the account removed.

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

Multi-session deployments

The pattern

What’s per-session vs shared

Session lifecycle

Adding tenants on the fly

Removing tenants

Process ownership

Memory budget

Sharding strategies

Graceful shutdown

See also

​The pattern

​What’s per-session vs shared

​Session lifecycle

​Adding tenants on the fly

​Removing tenants

​Process ownership

​Sharing a media processor

​Memory budget

​Sharding strategies

​Graceful shutdown

​See also

The pattern

What’s per-session vs shared

Session lifecycle

Adding tenants on the fly

Removing tenants

Process ownership

Sharing a media processor

Memory budget

Sharding strategies

Graceful shutdown

See also