Usage
The Load Balancer exposes several endpoints and features for task routing, monitoring, and management.
Endpoints
POST /mcp: Optional tool discovery and calls using one dedicatedMCP_AUTH_KEYPOST /task: Submit a task to the Load BalancerGET /health: Get the status of the Load Balancer (public info, more details with authentication)GET /logs: Retrieve recent log lines, bounded byMAX_LOGS(authentication required)/dashboard: Access the monitoring dashboard (if enabled)/bull: Access the BullMQ interface (if enabled)
Task Routing and Prioritization
- Tasks specify
group,function,contract, and optionalpriority(an integer from 1 to 2097152, 1 = highest priority). - The Load Balancer finds available Workers matching the group and contract version.
- If all Workers are busy, tasks are queued and prioritized using BullMQ. Waiting for a free slot does not consume an attempt, but the whole task must complete within
TASK_TIMEOUT.
Errors and retries
- Worker rejections (HTTP 4xx except 408 and 429) are not retried: the caller receives the Worker's status code and error message.
- Webhook delivery failures (Worker HTTP 502 with
code: "WEBHOOK_FAILED") are not retried either, because the function already ran. The caller receives the Worker's status and error message. - Timeouts are not retried: Worker HTTP 504 responses, upstream request timeouts and tasks whose caller deadline (
TASK_TIMEOUT) expired return HTTP 500 with{ "error": "Task failed or timed out" }. - Other failures (unreachable Worker, HTTP 5xx, 408, 429, no matching Worker) are retried up to
TASK_ATTEMPTSattempts, then return HTTP 500.
An LB timeout does not cancel the Worker handler; the Worker enforces its own cooperative cancellation deadline.
Requests rejected by the Load Balancer itself return 401 (invalid LB_AUTH_KEY), 400 (missing x-wr-auth, malformed JSON or invalid group, function, contract, priority, mode, input or webhook) or 413 (body larger than REQUEST_BODY_LIMIT).
Execution modes
sync(default): the Load Balancer waits for the Worker and returns its response.stream: the Load Balancer reserves a slot on a Worker whose function supports streaming, then proxies the Worker's response. Chunks arrive progressively; they are not buffered by response compression. If the task cannot be dispatched to a Worker, the Load Balancer returns HTTP 503.webhook: requireswebhook.url(httporhttps) and optionalwebhook.headerswith string values. The Load Balancer answers immediately with{ "success": true, "message": "Task accepted, result will be sent to webhook" }and the Worker delivers the result to the webhook. If the task fails (rejected by the Worker, function error, timeout, or no Worker available beforeTASK_TIMEOUT), the Load Balancer posts{ "success": false, "error": "...", "code": "..." }to the same URL instead, with your webhook headers and anX-Andera-Status: failedheader so the receiver can tell it apart from a result. The code isWORKER_REJECTED(the Worker refused the task, e.g. invalid input),WEBHOOK_FAILED(the function ran but the Worker could not deliver its result),TASK_TIMEOUTorTASK_FAILED. This notice does not include the Worker'sWEBHOOK_HEADERS; it is sent up to four times, one second apart. A Worker that finishes afterTASK_TIMEOUTmay still deliver its result after the timeout notice, and tasks lost when the Load Balancer restarts are not reported.
Task data and credentials
Task payloads, including input, are stored in Redis by BullMQ and are visible in the BullMQ interface; completed and failed jobs are kept for 24 hours. The Worker credential (x-wr-auth) and webhook headers supplied by the caller stay in the Load Balancer's memory and never enter Redis or Bull Board. For this reason, run one active Load Balancer per Redis queue (see Queue process boundary).
Dynamic Worker Discovery
- The Worker list can be updated on the fly without restarting the Load Balancer.
- The Load Balancer checks each Worker's
/healthendpoint to verify group, contract, and slot availability. - Real-time slot updates are received from Workers via WebSocket.
Logs and Monitoring
/logsendpoint provides recent log lines, bounded byMAX_LOGSfor monitoring and debugging (authentication required).- The dashboard lists connected Workers, their status, and logs.
Communication with Workers
- Workers authenticate incoming requests from the Load Balancer and clients using their own
AUTH_KEYin theAuthorizationheader and theLB_AUTH_KEYin a dedicatedx-lb-authheader. - The Load Balancer authenticates with Workers (on
/logs,/health, etc.) usingLB_AUTH_KEYin a dedicatedx-lb-authheader, and as a subprotocol when it opens the Worker WebSocket.LB_AUTH_KEYmust therefore be identical on the Load Balancer and every Worker.
Example: Submitting a Task to the Load Balancer
Note: When submitting a task to the
/taskendpoint, you must include the following HTTP headers:
Authorization: <LB_AUTH_KEY>(your Load Balancer's LB_AUTH_KEY; aBearerprefix and thex-lb-authheader are also accepted)x-wr-auth: <AUTH_KEY>(the target Worker's AUTH_KEY)
When you submit a task to the Load Balancer, it will forward the request to the selected Worker with the following headers:
Authorization: <AUTH_KEY>(the target Worker's AUTH_KEY)x-lb-auth: <LB_AUTH_KEY>(your Load Balancer's LB_AUTH_KEY)
You can submit a task to the Load Balancer using the /task endpoint. The priority field is optional (1 = highest priority).
{
"group": "default", // The Workers from this group will handle the job
"function": "hello",
"contract": 1,
"priority": 1, // Optional: 1
"input": { "name": "Andera" },
"mode": "sync"
}
MCP tools for agents
Optional POST /mcp exposes selected functions through Streamable HTTP. It accepts one dedicated MCP_AUTH_KEY bearer token; REST /task keeps its own authentication. Authenticated /health includes sanitized MCP status and the exposed tools. See MCP setup.