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.
- 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)
bun add worker-lbimport { 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);
},
};- Simple load balancing for dirty small projects
- Latency is not a concern but reliability is
- Geographic routing to regional backends
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
| 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) |
MIT