Bree Plugin Jitter

bree-plugin-jitter

Deterministic jitter for [Bree](https://github.com/breejs/bree) scheduled jobs. Prevents the thundering herd problem when multiple jobs share the same cron schedule.

The problem

When you have multiple Bree jobs on the same cron (e.g. `*/5 * * * *`), they all fire at the exact same second. If those jobs compete for shared resources (SSH connections, database pools, APIs), they can cause timeouts, connection failures, and cascading errors.

The solution

This plugin adds a small, deterministic delay before each job starts. The delay is derived from a hash of the job name, so:

• The same job always gets the same offset (predictable, easy to debug)
• Different jobs with the same cron naturally spread out
• No random variance between runs

Install

npm install bree-plugin-jitter

Usage

const Bree = require('bree');
const jitter = require('bree-plugin-jitter');

Bree.extend(jitter);

// Or with options:
Bree.extend(jitter, {
  maxMs: 30000,          // Maximum jitter in ms (default: 30000)
  periodFraction: 0.1,   // Fraction of cron period used as ceiling (default: 0.1)
  verbose: false          // Log jitter delays to console (default: false)
});

const bree = new Bree({
  jobs: [
    { name: 'sync-data',    cron: '*/5 * * * *' },
    { name: 'health-check', cron: '*/5 * * * *' },
    { name: 'cleanup',      cron: '*/5 * * * *' },
  ]
});

// sync-data starts at :00 + 12.4s
// health-check starts at :00 + 3.8s
// cleanup starts at :00 + 27.1s

How it works

For each job execution:

1. The job name is hashed to a stable integer
2. The hash is reduced modulo the jitter ceiling
3. The job sleeps for that many milliseconds before starting

The jitter ceiling depends on the job's cron period:

Schedule	Period	Max jitter (at default 10%)
*/2 * * * *	2 min	12s
*/5 * * * *	5 min	30s (capped)
*/15 * * * *	15 min	30s (capped)
0 9 * * *	daily	30s (flat cap)

J