Worker Guide

This guide explains how workers fit into Vona within the Cabloy monorepo.

Why workers matter

Vona uses a distributed worker-process architecture, which means the backend runtime is naturally multi-process rather than assuming one long-lived server instance only.

This matters because operational behavior, reload behavior, queue execution, broadcast, and auth-sensitive runtime logic can all depend on worker semantics.

bean.worker

A global worker-management bean provides capabilities such as:

• get current worker id
• exit current worker
• exit all workers
• reload current worker
• reload all workers
• manage alive state

This makes worker control part of the application’s operational surface.

SERVER_WORKERS

Worker count can be controlled through env or command-line setup.

Representative idea:

• development often uses multiple workers to expose distributed-environment issues earlier
• single-worker modes still matter for Docker or simpler execution scenarios

A practical runtime reading in the current repo is:

• SERVER_WORKERS becomes part of backend server config
• npm run dev and cd vona && npm run dev normally exercise multi-worker behavior
• dev:one, start:one, and Docker-oriented single-worker flows remain important when you want simpler runtime shape or one-worker debugging

Worker control behavior

At a high level:

• reload() targets the current worker
• reloadAll() broadcasts reload intent across workers
• exit() closes the current app process and exits
• exitAll() broadcasts a process-exit intent across workers

This matters because worker control belongs to runtime behavior, not only to deployment tooling.

Implementation checks for worker-sensitive runtime changes

When touching runtime or operational backend behavior, ask:

1. does this assume a single-process runtime incorrectly?
2. does the behavior change across worker count or worker lifecycle?
3. is this a place where reload or worker-control operations matter?
4. should the verification path consider multi-worker behavior explicitly?

That keeps backend reasoning aligned with Vona’s actual runtime architecture.