Autoscaling

Two layers scale with load. The bare-metal autoscaler spawns and drains worker processes on one machine; the scaler endpoint (serveScaler) exposes queue depth over HTTP so KEDA can size a Kubernetes deployment.

Reach for the autoscaler when you run on bare metal, Docker, or systemd. Its formula mirrors the Kubernetes HPA, so the behaviour is predictable if you already know KEDA.

Quick start

import { Queue, serveAutoscaler } from "@byteveda/flexiq";

const queue = new Queue({ dbPath: "flexiq.db" });

await serveAutoscaler(queue, {
  app: "./app.js",
  minWorkers: 1,
  maxWorkers: 10,
});

app is the same module flexiq run loads — one that exports a configured Queue as its default export or as queue. Each spawned worker imports it and starts a worker over its registered tasks.

serveAutoscaler resolves once SIGTERM or SIGINT arrives and every worker has drained.

CLI

flexiq --db flexiq.db autoscale ./app.js --min-workers 2 --max-workers 20

Every option below has a matching flag (--target-queue-depth, --target-utilisation, --scale-up-window, --scale-down-window, --tolerance, --poll-interval, --drain-timeout, --concurrency, --queues, --batch-size, --node-arg). Windows and timeouts are in milliseconds.

A systemd unit for the pool:

[Unit]
Description=flexiq autoscaler
After=network.target

[Service]
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/npx flexiq --db /var/lib/flexiq/flexiq.db autoscale ./app.js --min-workers 2 --max-workers 20
Restart=always
KillMode=process
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

KillMode=process sends systemd's SIGTERM to the autoscaler alone — it then drains its own pool, rather than having workers killed mid-job.

How it works

Every pollIntervalMs (default 5 s) the controller:

1. Reads pending and running — from all queues, or from queues when set.
2. Replaces crashed workers up to minWorkers.
3. Computes a desired count from two signals:

depthDesired = ceil(pending / targetQueueDepthPerWorker)
utilDesired  = ceil(workers × (utilisation / targetUtilisation))
desired      = clamp(max(depthDesired, utilDesired), minWorkers, maxWorkers)

4. Smooths that through the stabilisation windows.
5. Spawns or drains workers to reach the smoothed target.

Stabilisation windows

Every tick's raw recommendation is recorded, including the ticks that asked for no change. The least aggressive one in the window then wins:

• Scale-up takes the minimum, so the pool grows only once every tick in the window agrees the demand is real. scaleUpWindowMs defaults to 0, which means the current tick alone decides — an extra worker for a few seconds costs far less than a backlog.
• Scale-down takes the maximum, so a lull shorter than the window can't tear the pool down — including a tick whose metrics read failed. scaleDownWindowMs defaults to 5 minutes, matching the Kubernetes HPA's downscale stabilisation.

Tolerance band

A desired count within tolerance (default 10%, as in HPA) of the current one is treated as no change, so small fluctuations don't churn processes.

Overload override

When running exceeds workers × concurrencyPerWorker, the controller bypasses the tolerance band and adds one worker — a genuine overload shouldn't sit inside a noise filter.

Options

Invalid values throw RangeError up front rather than misbehaving at runtime.

Programmatic API

Autoscaler is the loop behind serveAutoscaler, for embedding in a larger process:

import { Autoscaler } from "@byteveda/flexiq";

const autoscaler = new Autoscaler(queue, { app: "./app.js", maxWorkers: 20 });
autoscaler.start();

// One decision cycle by hand — useful in tests or a custom loop.
const decision = await autoscaler.tick();
console.log(decision.rationale); // "scale-up: depth=4 util=2 overload=false"

await autoscaler.stop(); // drains every worker

tick() returns a ScaleDecision: pending, running, currentWorkers, desiredWorkers, and a human-readable rationale. computeDesiredWorkers is the same decision as a pure function, if you want the number without the processes.

autoscaler.processManager exposes the pool itself — spawnWorker(), terminateWorker(pid), reapDead(), countLive(), livePids(), shutdown(), and killAll().

Process model

Workers are independent OS processes, each in its own process group, so a Ctrl-C in the autoscaler's terminal doesn't cut jobs short — the autoscaler drains them itself, SIGTERM first and SIGKILL only after drainTimeoutMs. A worker that dies on its own is noticed on the next tick and replaced up to minWorkers.

Against KEDA

On Kubernetes, run serveScaler (or flexiq scaler) and let KEDA size the deployment. The two compose: KEDA sizes the fleet, and each pod can still run its own autoscaler over that machine's cores.