Skip to main content

Usage

The Load Balancer exposes several endpoints and features for task routing, monitoring, and management.

Endpoints​

  • POST /task: Submit a task to the Load Balancer
  • GET /health: Get the status of the Load Balancer (public info, more details with authentication)
  • GET /logs: Retrieve the last 1000 log lines (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 optional priority (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.
  • Tasks can be retried automatically in case of failure.

Dynamic Worker Discovery​

  • The Worker list can be updated on the fly without restarting the Load Balancer.
  • The Load Balancer checks each Worker's /health endpoint to verify group, contract, and slot availability.
  • Real-time slot updates are received from Workers via WebSocket.

Logs and Monitoring​

  • /logs endpoint provides the last 1000 log lines for 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_KEY in the Authorization header and the LB_AUTH_KEY in a dedicated x-lb-auth header.
  • The Load Balancer authenticates with Workers (on /logs, /health, etc.) using LB_AUTH_KEY in a dedicated x-lb-auth header.

Example: Submitting a Task to the Load Balancer​

Note: When submitting a task to the /task endpoint, you must include the following HTTP headers:

  • Authorization: <LB_AUTH_KEY> (your Load Balancer's LB_AUTH_KEY)
  • 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"
}