worker-lb

Note

I don't know if you should use this in production just yet, this is more of an experiment and by no means is battle-tested.

worker-lb is a small and extensible load balancer built on Cloudflare Workers. It's basically a poor mans Cloudflare Load Balancer, but running on Cloudflare Workers, because why not.

Note that in the current state it actually works more like a failover/high availability solution rather than a fully fledged load balancer. You can see the load balancing status bits as coming soon below.

Features

• Failover between multiple HTTP endpoints
• Health checks with customizable intervals and timeouts
• Recovery function to dump requests that did not reach any healthy endpoints
• Geo steering (route by continent, country, region, or Cloudflare colo)
• (coming soon) Response time based steering
• (coming soon) Load based steering
• (coming soon) Sampleable endpoints (helpful for phased rollouts)

Installation

bun add worker-lb

Quick Start

import { Endpoint, LoadBalancer } from "worker-lb";

const lb = new LoadBalancer({
  endpoints: [
    new Endpoint("https://api1.example.com"),
    new Endpoint("https://api2.example.com"),
    new Endpoint("https://api3.example.com"),
  ],
});

export default {
  async fetch(
    request: Request<unknown, IncomingRequestCfProperties>,
  ): Promise<Response> {
    return lb.handleRequest(request);
  },
};

Use Cases

• Simple load balancing for dirty small projects
• Latency is not a concern but reliability is
• Geographic routing to regional backends

Documentation

Note

This project is still a work in progress and not battle-tested. Use at your own risk.

Note

Since this will be deployed on Cloudflare Workers, you will receive their headers, such as cf-ray and cf-cache-status, in addition to the headers added by worker-lb. This is important to consider when grabbing the connecting IP or other specific client data. Please refer to Cloudflare's documentation for more details.

• Endpoints - Configure backend endpoints
• Availability Methods - Failover strategies
• Geo Steering - Route by geographic location

Headers Added to Responses

Header	Description
X-Load-Balancer-Endpoint	The endpoint URL that served the request
X-Load-Balancer-Latency	Total request latency in milliseconds
X-Load-Balancer-Endpoint-Gather-Latency	Time to select the endpoint in milliseconds
X-Load-Balancer-Tried-Count	Number of endpoints tried (only on failover)
X-Load-Balancer-Tried-Endpoints	Comma-separated endpoint URLs tried (only on failover)

License

MIT