Scale

Readiness

Find in-memory state that splits across Node.js workers and instances: rate limits, cron, queues, event bus, WebSocket rooms, caches and SQLite, with fixes.

5 min readUpdated DocumentationEdit this page
On this page14

With more than one worker or instance, every process has its own memory. Anything that keeps state in memory silently splits: rate limits multiply, jobs stay on the worker that created them, cron fires once per process, WebSocket broadcasts miss clients connected to other workers.

Nothing crashes. The app just behaves differently than it did on your laptop with one process. @axiljs/scale ships a static scan that finds the usual causes in your source.

Terminal
❯axil capacity # includes a "Multi-process readiness" section

axil capacity runs the scan only when the config describes more than one process (vertical.workers > 1 or horizontal.instances.max > 1).

The rules

ComponentDetected byLevel
@axiljs/security rateLimitrateLimit( without store: in its argumentswarn
@axiljs/queue Schedulernew Scheduler(fail
@axiljs/queue Queuenew Queue(warn
@axiljs/eventsgetGlobalEventBus( or new EventBus(warn
@axiljs/websocketnew WSServer(warn
@axiljs/cloud CloudCachenew CloudCache(warn
SQLitebetter-sqlite3, type: 'sqlite' or dialect: 'sqlite'fail

rateLimit() without a shared store

Why it breaks: the default store counts requests in the memory of each process. With 4 workers on each of 3 instances, a client can make limit × 4 × 3 requests per window, depending on which worker the load balancer and the cluster pick.

Fix: pass a shared store, a RateLimitStore backed by Redis or your database. Calls that already pass store: are not reported.

TypeScript
TS
app.use(rateLimit({ windowMs: 60_000, max: 100, store: redisRateLimitStore }))

new Scheduler()

Why it breaks: the scheduler runs in every process. Each cron job fires once per worker per instance: a nightly invoice job on 4 workers and 3 instances sends 12 invoices.

Fix: run the scheduler in one dedicated process (for example only when an environment variable such as AXIL_ROLE=scheduler is set), or guard each job with a distributed lock.

TypeScript
TS
1if (process.env.AXIL_ROLE === 'scheduler') {
2  const scheduler = new Scheduler()
3  // register jobs ...
4}

In-memory Queue

Why it breaks: jobs live and die with the process that enqueued them. They are not shared with other workers, and a restart or crash loses them.

Fix: use a shared broker for jobs that must survive restarts or be processed by any worker. Keeping the in-memory queue for best-effort, per-process work is fine.

EventBus and getGlobalEventBus()

Why it breaks: the event bus is in-process. A subscriber on worker 2 never sees an event emitted on worker 1, or on another instance.

Fix: bridge cross-process events through a broker (Redis pub/sub, NATS, Postgres LISTEN/NOTIFY).

Note

Per-process subscribers are often exactly what you want, for example writing each worker's audit.log events (from tAudit) to stdout or a database. The scan still lists them, because it cannot tell intent; treat the finding as a reminder.

new WSServer()

Why it breaks: WebSocket rooms are per process. A broadcast to a room only reaches clients connected to the same worker.

Fix: fan out room messages through a pub/sub adapter, and enable sticky sessions on the load balancer so a client's connection stays on one instance.

new CloudCache()

Why it breaks: each process has its own cache. Invalidating a key on one worker leaves stale copies on the others until their TTL expires.

Fix: keep TTLs short for data that may change, or use a shared cache for data that must be consistent.

SQLite

Why it breaks: SQLite is a local file. Separate instances cannot share it, and several workers writing to the same file lock each other.

Fix: use PostgreSQL or MySQL for any deployment with more than one instance.

Programmatic API

scanProject(root?, dir?)

Walks root/dir (defaults: process.cwd() and 'src') and scans every .ts, .js, .mts, .cts, .mjs and .cjs file. It skips node_modules, dist, dot-directories, declaration files (.d.ts) and test files (.test.*, .spec.*).

TypeScript
TS
1import { scanProject } from '@axiljs/scale'
2
3const findings = scanProject()
4for (const f of findings) {
5  console.log(`${f.level.toUpperCase()} ${f.file}:${f.line} ${f.component}`)
6  console.log(`  ${f.title}`)
7  console.log(`  fix: ${f.fix}`)
8}
9
10if (findings.some(f => f.level === 'fail')) process.exitCode = 1

scanSource(file, source)

Scans one source string. file is only used for reporting.

TypeScript
TS
1import { scanSource } from '@axiljs/scale'
2
3scanSource('app.ts', `app.use(rateLimit({ windowMs: 60000, max: 100 }))`)
4// [{ level: 'warn', component: '@axiljs/security rateLimit', file: 'app.ts', line: 1, title: '...', fix: '...' }]
5
6scanSource('app.ts', `app.use(rateLimit({ max: 100, store: redisStore }))`)
7// []

ReadinessFinding

FieldTypeDescription
level'warn' | 'fail'fail for Scheduler and SQLite, warn for the rest
componentstringe.g. '@axiljs/queue Scheduler'
filestringPath relative to root, with forward slashes
linenumber1-based line of the match
titlestringWhat goes wrong with several processes
fixstringWhat to do instead

Limits of a static scan

The scan matches source text, so it is a checklist, not a proof:

  • It looks for the patterns above in your src/, not inside dependencies.
  • rateLimit() is cleared only when the text store: appears in its arguments. rateLimit(options) with a variable is reported even if options has a store.
  • Matches after // on the same line, and lines starting with * (block-comment bodies), are ignored. Other comment and string forms are not.
  • Your own in-memory state (a Map used as a cache, a module-level counter, an in-memory store) is not detected. The same reasoning applies to it.

What needs nothing shared: the request context, retries, timeouts, redaction, JWT verification and anything else that lives within one request.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY