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.
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.
axil capacity runs the scan only when the config describes more than one process (vertical.workers > 1 or horizontal.instances.max > 1).
The rules
| Component | Detected by | Level |
|---|---|---|
@axiljs/security rateLimit | rateLimit( without store: in its arguments | warn |
@axiljs/queue Scheduler | new Scheduler( | fail |
@axiljs/queue Queue | new Queue( | warn |
@axiljs/events | getGlobalEventBus( or new EventBus( | warn |
@axiljs/websocket | new WSServer( | warn |
@axiljs/cloud CloudCache | new CloudCache( | warn |
| SQLite | better-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.
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.
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.*).
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 = 1scanSource(file, source)
Scans one source string. file is only used for reporting.
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
| Field | Type | Description |
|---|---|---|
level | 'warn' | 'fail' | fail for Scheduler and SQLite, warn for the rest |
component | string | e.g. '@axiljs/queue Scheduler' |
file | string | Path relative to root, with forward slashes |
line | number | 1-based line of the match |
title | string | What goes wrong with several processes |
fix | string | What 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 textstore:appears in its arguments.rateLimit(options)with a variable is reported even ifoptionshas 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
Mapused 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.
Related
Was this page helpful?