Worker configuration

A FlareWorker is configured entirely through its constructor.

import { FlareWorker } from "@zeridion/flare/worker";

const worker = new FlareWorker({
  apiKey: process.env.FLARE_API_KEY,
  baseUrl: "https://api.zeridion.com",
  concurrency: 5,
  jobs: [sendWelcome, nightlyCleanup],
  logger: console,
});

Credentials

Supply either an apiKey (the worker builds its own client) or a pre-built client:

Option	Type	Description
apiKey	string	Your Zeridion API key. Falls back to the FLARE_API_KEY environment variable when omitted.
baseUrl	string	API base URL. Defaults to https://api.zeridion.com. Point it at a local or dev API as needed.
client	FlareClient	A configured client to reuse (its credential, base URL, and body cap are inherited).

The worker derives a dedicated connection for polling tuned for the long-poll — a poll read-timeout above the server's polling window, so a long-poll is never cut short — and reuses pooled connections across the loop.

Jobs

Option	Type	Description
jobs	JobDefinition[]	The defineJob / defineRecurringJob results to run. Required. An empty array makes start() a no-op.

Concurrency and polling

Option	Type	Default	Description
concurrency	number	10	Maximum jobs run at once. Reported to the server as available capacity (clamped to the server's accepted range).
queues	string[]	["default"]	Queues to poll. Every registered job's queue is added automatically.
pollIntervalMs	number	2000	Idle delay between polls when no jobs are returned.
pollTimeoutMs	number	35000	Read timeout for a single long-poll request. Keep it above the server's polling window.
pollMaxRetries	number	2	Bounded retry budget for a failed poll, so a transient-error storm cannot exceed the poll window.

The worker reports its free slots as capacity on every poll and never starts more jobs than it has slots for, so the server hands it only what it can run.

Graceful shutdown

Option	Type	Default	Description
gracePeriodMs	number	25000	How long stop() waits for in-flight jobs to finish before resolving.

On stop() (or a SIGTERM / SIGINT when started via run()), the worker stops polling, signals in-flight jobs to wind down via their cancellation signal, and waits up to gracePeriodMs for them to finish. Keep the grace window under your platform's own shutdown grace so handlers get a chance to drain before the process is force-killed.

Identity

Option	Type	Description
hostname	string	Override the reported hostname (otherwise the machine hostname).
workerId	string	Override the generated worker id.

By default the worker id is wrk_{host}_{pid}_{random} — the host segment sanitized to the characters the server accepts, the random segment from a cryptographic source so ids never collide across containers.

Logging

Option	Type	Description
logger	Logger	A structural logger (debug / info / warn / error). console satisfies it. Omit for a silent default.

The library never logs to a global and never logs raw payloads or credentials. Job handlers receive a logger pre-bound with the job's id, type, and attempt — see job context.

See also

• Worker overview — lifecycle and what the runtime does.
• Defining jobs — building the definitions you pass in jobs.