Cloudflare Worker Load Balancer

Advanced load balancer using Cloudflare Workers with weighted, backup, and disabled origin support.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact
7. Acknowledgments

About The Project

This project provides a robust, production-ready Cloudflare Worker that acts as a high-performance HTTP load balancer. It allows you to distribute traffic across multiple origin servers based on configurable weights, with built-in support for failover to backup servers and maintenance modes.

Key Features:

• Weighted Random Selection: Distribute traffic proportionally across primary origins.
• Automatic Failover: Seamlessly routes traffic to backup origins if primary origins are unavailable or return errors.
• Dynamic Configuration: Configure origins, weights, timeouts, and headers via environment variables.
• Health Monitoring: Built-in /health and /_lb/stats endpoints for real-time status updates.
• Header & Cookie Handling: Accurate forwarding of request/response headers and Set-Cookie support.
• Request Tracking: Optional unique request IDs for end-to-end troubleshooting.
• Security-First: Sanitizes hop-by-hop headers and prevents origin URL leakage through Location header rewriting.

(back to top)

Built With

• 
• 
• 

(back to top)

Getting Started

To get your load balancer up and running, follow these steps.

Prerequisites

You need the following installed:

• Node.js and npm

  npm install npm@latest -g

• Wrangler CLI

  npm install -g wrangler

Installation

1. Clone the repo

   git clone https://github.com/LoveDoLove/cloudflare-load-balancer.git

2. Install NPM packages

   npm install

3. Update your origin configuration in wrangler.jsonc (see Usage).
4. Deploy to Cloudflare

   npm run deploy

(back to top)

Usage

The load balancer is primarily configured through the ORIGINS_CONFIG variable in wrangler.jsonc. This allows you to update your infrastructure without redeploying code.

Configuration Schema

An origin object can have the following properties:

Property	Type	Default	Description
url	string	Required	The destination origin URL (must include protocol).
weight	number	1	Relative traffic weight (higher = more traffic).
backup	boolean	false	If true, only used if all primary origins fail.
enabled	boolean	true	Quickly enable/disable an origin.
timeout	number	10000	Request timeout in milliseconds.
headers	object	{}	Custom headers to inject for this specific origin.

Example wrangler.jsonc

"vars": {
  "ORIGINS_CONFIG": "[{\"url\":\"https://primary-1.example.com\",\"weight\":3},{\"url\":\"https://primary-2.example.com\",\"weight\":1},{\"url\":\"https://backup.example.com\",\"backup\":true}]"
}

Stats and Health

• Health Check: GET /health - Returns 200 OK if the system is functional.
• System Stats: GET /_lb/stats - Returns detailed information about current configuration and origin pools.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the Apache License 2.0. See LICENSE for more information.

(back to top)

Contact

LoveDoLove - GitHub - Discord

Project Link: https://github.com/LoveDoLove/cloudflare-load-balancer

(back to top)

Acknowledgments

• Cloudflare Workers Documentation
• Best-README-Template

(back to top)