smart-stick-loadbalancer 1.0.5 → 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for your interest in contributing to smart-stick-loadbalancer. This is a small, focused package — contributions that keep it simple and beginner-friendly are most welcome.
+
+## What's welcome
+
+- Bug fixes
+- Documentation improvements
+- New routing strategies (add a `case` in `router.js`)
+- Health check improvements
+- Better error messages
+
+## What to discuss first
+
+Open an issue before starting work on anything large — new features, breaking config changes, or architectural shifts. Keeps everyone from wasting time.
+
+## Getting started
+
+```bash
+git clone https://github.com/SwayamGupta12345/smart-stick-loadbalancer.git
+cd smart-stick-loadbalancer
+npm install
+```
+
+Create two simple backend servers (see the Quick Start in the README) and run `node src/index.js` against a local config to verify your changes work end-to-end.
+
+## Submitting a pull request
+
+1. Fork the repo and create a branch: `git checkout -b fix/your-fix-name`
+2. Make your changes
+3. Test manually with at least two backends
+4. Update the README if you're changing behaviour or adding config options
+5. Open a pull request with a clear description of what changed and why
+
+## Adding a routing strategy
+
+All routing logic lives in `src/router.js`. Add a new `case` to `selectBackend`, handle the `nextIndex` return value correctly, and document it in the README under **Routing Strategies**.
+
+## Style
+
+- No external linting setup — just match the style of the surrounding code
+- Clear variable names over clever one-liners
+- Add a comment if the logic isn't immediately obvious
+
+## Reporting bugs
+
+Open a GitHub issue with:
+- What you expected to happen
+- What actually happened
+- Your config (remove any credentials)
+- Node.js version
+
+---
+
+Small project, low friction. If something's unclear, just open an issue and ask.

package/README.md

@@ -1,16 +1,94 @@
 # Smart Stick Load Balancer
 
-A lightweight **sticky-session load balancer** for Node.js. It distributes requests to multiple backends, supports sticky sessions via cookies, performs health checks, and can optionally send email alerts.
+![npm](https://img.shields.io/npm/v/smart-stick-loadbalancer)
+![npm downloads](https://img.shields.io/npm/dm/smart-stick-loadbalancer)
+![License](https://img.shields.io/npm/l/smart-stick-loadbalancer)
+![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)
+
+A lightweight sticky-session load balancer for Node.js with health checks, automatic failover, WebSocket support, configurable routing strategies, and optional email alerts.
+
+Designed for developers who want a simple load-balancing solution directly inside the Node.js ecosystem - no Nginx, no HAProxy, no external configuration.
+
+---
+
+## Why this package?
+
+Most Node developers don't want to configure
+Nginx or HAProxy just to balance requests during
+development or for small deployments.
+
+Smart Stick Load Balancer provides:
+
+- sticky sessions
+- health monitoring
+- automatic failover
+- WebSocket support
+
+directly inside your Node.js application with a simple JSON configuration.
+
+---
+
+## Table of Contents
+
+- [Why this package?](#why-this-package)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Project Structure](#project-structure)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Routing Strategies](#routing-strategies)
+- [Health Checks](#health-checks)
+- [Weights](#weights)
+- [How It Works](#how-it-works)
+- [Sticky Sessions](#sticky-sessions)
+- [Local Development Demo](#local-development-demo)
+- [Health Endpoint](#health-endpoint)
+- [Email Alerts](#email-alerts)
+- [Use Cases](#use-cases)
+- [Notes](#notes)
+- [License](#license)
 
 ---
 
 ## Features
 
-- Sticky sessions via cookies
-- Health checks with automatic failover
-- Optional email alerts
+- Sticky sessions using cookies
+- Three routing strategies: `round-robin`, `least-connections`, `random`
+- Weight support - send more traffic to stronger backends
+- Configurable health check path per backend
+- Configurable health check algorithm (`http`, `http-status`, or your own function)
+- Automatic backend health checks with configurable interval
+- Automatic failover and recovery
+- Active connection tracking per backend
 - WebSocket and HTTP support
-- Minimal setup
+- Optional email alerts when backends go down or recover
+- Simple JSON configuration
+- Pure Node.js implementation with no dependency on external load balancers such as Nginx or HAProxy.
+
+---
+
+## Architecture
+
+```text
+                Client Requests
+                        │
+                        ▼
+             Smart Stick Load Balancer
+                        │
+           ┌─────────────┼─────────────┐
+           │             │             │
+           ▼             ▼             ▼
+        Backend A     Backend B     Backend C
+           │             │             │
+         /health       /ready       /health
+         
+           ▲              ▲              ▲
+           └──── Health Checker ─────────┘
+```
+
+The load balancer continuously monitors backend health, routes new requests using the configured strategy, and preserves sticky sessions using cookies.
+The cookie stores the assigned backend's identifier and is automatically updated if failover occurs.
 
 ---
 
@@ -20,105 +98,429 @@ A lightweight **sticky-session load balancer** for Node.js. It distributes reque
 npm install smart-stick-loadbalancer
 ```
 
+### Requirements
+ - Node.js **18 or later**
+ - npm
+
+The package relies on modern Node.js features such as the built-in `fetch()` API.
+
+---
+
+## Project Structure
+
+Create a `config.json` and `index.js` inside your own project folder:
+
+```text
+my-project/
+├── config.json   ← your configuration
+└── index.js      ← your entry point
+```
+
+> ⚠️ **Never commit `config.json` to a public repository if it contains email credentials.**
+> Add it to your `.gitignore`:
+> ```
+> config.json
+> ```
+
 ---
 
-## Example Configuration (`config.json`)
+## Configuration
+
+### config.json
 
 ```json
 {
   "port": 3001,
+  "strategy": "round-robin",
   "backends": [
     {
       "id": 0,
       "url": "http://localhost:5000",
-      "owner": "example@example.com",
-      "weight": 1
+      "weight": 2,
+      "healthPath": "/health",
+      "healthMethod": "GET",
+      "owner": "your-email@example.com"
     },
     {
       "id": 1,
       "url": "http://localhost:5001",
-      "owner": "example@example.com",
-      "weight": 1
+      "weight": 1,
+      "healthPath": "/ready",
+      "healthMethod": "HEAD",
+      "healthTimeout": 5000,
+      "owner": "your-email@example.com"
     }
   ],
-  "health": { "interval": 10000, "timeout": 2000 },
+  "health": {
+    "interval": 10000,
+    "timeout": 2000,
+    "algorithm": "http-status"
+  },
   "email": {
     "service": "gmail",
-    "auth": { "user": "<your-email@gmail.com>", "pass": "<your-app-password>" }
+    "auth": {
+      "user": "your-email@gmail.com",
+      "pass": "your-app-password"
+    }
   }
 }
 ```
 
+### Config fields
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `port` | Yes | - | Port the load balancer listens on |
+| `strategy` | No | `"round-robin"` | Routing strategy: `"round-robin"`, `"least-connections"`, `"random"` |
+| `backends` | Yes | - | Array of backend servers (minimum 1) |
+| `backends[].id` | Yes | - | Unique integer ID for each backend |
+| `backends[].url` | Yes | - | Full URL of the backend server |
+| `backends[].weight` | No | `1` | Relative traffic weight (higher = more requests) |
+| `backends[].owner` | No | - | Email to notify when this backend changes state (requires `email` config) |
+| `backends[].healthPath` | No | `"/"` | Health check path - overrides global `health.path` |
+| `backends[].healthMethod` | No | `"GET"` | HTTP method for health checks - overrides global `health.method` |
+| `backends[].healthAlgorithm` | No | `"http-status"` | Health algorithm - overrides global `health.algorithm` |
+| `backends[].healthTimeout` | No | `2000` | Timeout in ms - overrides global `health.timeout` |
+| `backends[].healthHeaders` | No | `{}` | Headers sent with health check requests - overrides global `health.headers` |
+| `backends[].healthCheck` | No | - | Custom check function for this backend - overrides global `health.check` (JS only) |
+| `health.interval` | No | `10000` | How often to run health checks, in ms (no per-backend override) |
+| `health.path` | No | `"/"` | Default health check path for all backends |
+| `health.method` | No | `"GET"` | Default HTTP method for all health checks |
+| `health.algorithm` | No | `"http-status"` | Default algorithm: `"http"` (any response) or `"http-status"` (2xx only) |
+| `health.timeout` | No | `2000` | Default timeout in ms for health check requests |
+| `health.headers` | No | `{}` | Default headers sent with all health check requests |
+| `health.check` | No | - | Default custom check function for all backends (JS only) |
+| `email` | No | - | Nodemailer config - omit entirely to disable email alerts |
+
 ---
 
 ## Usage
 
+### index.js
+
 ```js
 const { createStickyProxy } = require("smart-stick-loadbalancer");
 const config = require("./config.json");
 
 const lb = createStickyProxy(config);
-lb.start(); // starts the load balancer
+lb.start();
+```
+
+---
+
+## Routing Strategies
+
+### `round-robin` (default)
+
+Requests cycle through backends in order. Weight controls how many slots each backend gets in the rotation.
+
+```
+Backend A (weight: 2), Backend B (weight: 1)
+Request order: A → A → B → A → A → B → ...
+```
+
+Recommended for: general use, backends with similar but not identical capacity.
+
+### `least-connections`
+
+Each request goes to the backend currently handling the fewest active connections.
+
+```json
+"strategy": "least-connections"
+```
+
+Recommended for: backends where some requests take much longer than others - file uploads, long polling, slow queries. Naturally balances load without needing weights.
+
+### `random`
+
+Picks a backend at random. Weight controls probability - a backend with `weight: 3` is 3x more likely to be chosen than one with `weight: 1`.
+
+```json
+"strategy": "random"
 ```
 
-- Requests to `http://localhost:3001` will be forwarded to the backends.
-- Sticky sessions are automatically managed using cookies.
-- Health checks run periodically and remove unhealthy backends from rotation.
+Recommended for: testing, simple distribution, situations where order doesn't matter.
 
 ---
 
-## Quick Start Demo
+## Health Checks
 
-Create two simple backend servers:
+Every health check setting can be set globally under `health:` and overridden per backend. Per-backend always wins.
 
-// server5000.js
+### Per-backend health path
+
+By default the health checker hits `/` on each backend. Point each backend to its own endpoint:
+
+```json
+"backends": [
+  { "id": 0, "url": "http://localhost:5000", "healthPath": "/health" },
+  { "id": 1, "url": "http://localhost:5001", "healthPath": "/ready" },
+  { "id": 2, "url": "http://localhost:5002", "healthPath": "/ping" }
+]
+```
+
+Or set a global default that all backends fall back to:
+
+```json
+"health": { "path": "/health" }
+```
+
+### Per-backend HTTP method
+
+Some health endpoints respond only to `HEAD` (faster, no body). Others need `GET`. Set per backend or globally:
+
+```json
+"backends": [
+  { "id": 0, "url": "http://localhost:5000", "healthMethod": "HEAD" },
+  { "id": 1, "url": "http://localhost:5001", "healthMethod": "GET" }
+]
+```
+
+### Per-backend algorithm
+
+**`"http-status"` (default)** - healthy only if the response is `2xx`. Recommended.
+
+**`"http"`** - healthy if any response comes back at all, regardless of status code. Use this for backends that return non-2xx on their health path but are actually running.
+
+```json
+"backends": [
+  { "id": 0, "url": "http://localhost:5000", "healthAlgorithm": "http-status" },
+  { "id": 1, "url": "http://localhost:5001", "healthAlgorithm": "http" }
+]
+```
+
+### Per-backend timeout
+
+A slow database-heavy backend might need a longer timeout before being declared unhealthy:
+
+```json
+"backends": [
+  { "id": 0, "url": "http://localhost:5000", "healthTimeout": 1000 },
+  { "id": 1, "url": "http://localhost:5001", "healthTimeout": 5000 }
+]
+```
+
+### Per-backend health headers
+
+Some backends require an auth token or API key to respond to health checks:
+
+```json
+"backends": [
+  {
+    "id": 0,
+    "url": "http://localhost:5000",
+    "healthHeaders": { "X-Health-Token": "secret123" }
+  }
+]
 ```
-const express = require('express');
+
+Or set global headers for all backends:
+
+```json
+"health": {
+  "headers": { "X-Internal": "true" }
+}
+```
+
+### Custom check function
+
+For full control, provide a `check` function in JS config. Receives the backend object, returns `true` (healthy) or `false` (unhealthy). Can be set globally or per backend.
+
+**Global** - applies to all backends that don't have their own `healthCheck`:
+
+```js
+const config = {
+  port: 3001,
+  backends: [
+    { id: 0, url: "http://localhost:5000" },
+    { id: 1, url: "http://localhost:5001" }
+  ],
+  health: {
+    interval: 10000,
+    check: async (backend) => {
+      const res = await fetch(`${backend.url}/health`);
+      const data = await res.json();
+      return data.status === "ok" && data.dbConnected === true;
+    }
+  }
+};
+```
+
+**Per-backend** - override the global function for one specific backend:
+
+```js
+const config = {
+  port: 3001,
+  backends: [
+    {
+      id: 0,
+      url: "http://localhost:5000",
+      healthCheck: async (backend) => {
+        // This backend needs a DB check
+        const res = await fetch(`${backend.url}/health`);
+        const data = await res.json();
+        return data.status === "ok" && data.dbConnected === true;
+      }
+    },
+    {
+      id: 1,
+      url: "http://localhost:5001",
+      // No healthCheck - falls back to global health.check or built-in algorithm
+    }
+  ],
+  health: { interval: 10000 }
+};
+```
+
+> Custom check functions are only available when passing config as a JS object. They cannot be expressed in JSON.
+
+---
+
+## Weights
+
+The `weight` field controls how much traffic a backend receives relative to others.
+
+```json
+"backends": [
+  { "id": 0, "url": "http://localhost:5000", "weight": 3 },
+  { "id": 1, "url": "http://localhost:5001", "weight": 1 }
+]
+```
+
+Backend 0 receives 3x as many requests as backend 1. Useful when servers have different capacity.
+
+Weight works with `round-robin` and `random`. For `least-connections`, traffic naturally flows to the least-busy backend without needing weights.
+
+---
+
+## How It Works
+
+1. An incoming request arrives at the load balancer.
+2. If the client has a sticky session cookie pointing to a healthy backend, that backend is used.
+3. If no valid sticky cookie exists, a backend is selected using the configured strategy.
+4. A cookie is set so future requests from the same client go to the same backend.
+5. Health checks run in the background at the configured interval, hitting each backend's `healthPath`.
+6. When a backend goes down, it is removed from rotation and the weighted pool is rebuilt.
+7. When a backend recovers, it is added back to rotation.
+8. If all backends go down, the load balancer returns `503 No healthy backends available`.
+
+---
+
+## Sticky Sessions
+
+To keep users connected to the same backend across multiple requests, the load balancer uses an HTTP cookie.
+
+### How it works
+
+1. A client's first request is routed using the configured strategy.
+2. The selected backend's ID is stored in a cookie.
+3. Future requests from the same client are sent to the same backend while it remains healthy.
+4. If that backend becomes unavailable, the client is automatically reassigned to another healthy backend and the cookie is updated.
+
+Sticky sessions improve compatibility with applications that store user state in memory, such as login sessions, shopping carts, or WebSocket connections.
+
+> If all backends become unavailable, the load balancer returns **503 Service Unavailable** until a healthy backend is detected.
+
+--- 
+
+## Local Development Demo
+
+### Step 1 - Create two backend servers
+
+```js
+// server5000.js
+const express = require("express");
 const app = express();
-app.get('/', (req, res) => res.send('Hello from 5000'));
-app.listen(5000, () => console.log('Server 5000 running'));
+app.get("/", (req, res) => res.send("Hello from Server 5000"));
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+app.listen(5000, () => console.log("Server 5000 running"));
 ```
 
+```js
 // server5001.js
-```
-const express = require('express');
+const express = require("express");
 const app = express();
-app.get('/', (req, res) => res.send('Hello from 5001'));
-app.listen(5001, () => console.log('Server 5001 running'));
+app.get("/", (req, res) => res.send("Hello from Server 5001"));
+app.get("/health", (req, res) => res.json({ status: "ok" }));
+app.listen(5001, () => console.log("Server 5001 running"));
 ```
 
-Start the load balancer:
+### Step 2 - Start the backends
 
+```bash
+node server5000.js
+node server5001.js
 ```
+
+### Step 3 - Start the load balancer
+
+```bash
 node index.js
 ```
 
-Open in browser: http://localhost:3001
-Requests should alternate between the two backends (sticky sessions maintained per client).
-
-Check health status:
+### Step 4 - Open in your browser
 
 ```
-curl http://localhost:3001/_lb/health
+http://localhost:3001
 ```
 
+Your session stays on the same backend. Check the `x-backend-id` response header to see which backend handled each request.
+
+---
+
 ## Health Endpoint
 
-```http
-GET /_lb/health
+This endpoint is intended for monitoring and debugging only.
+Check the live status of all backends:
+
+```bash
+curl http://localhost:3001/_lb/health
 ```
 
-Response example:
+Example response:
 
 ```json
 {
   "timestamp": "2025-12-28T12:00:00.000Z",
+  "strategy": "round-robin",
   "total": 2,
   "healthy": 2,
   "unhealthy": 0,
   "backends": [
-    { "id": 0, "url": "http://localhost:5000", "healthy": true, "requests": 5 },
-    { "id": 1, "url": "http://localhost:5001", "healthy": true, "requests": 3 }
+    {
+      "id": 0,
+      "url": "http://localhost:5000",
+      "healthy": true,
+      "weight": 2,
+      "requests": 10,
+      "activeConnections": 1,
+      "lastChecked": "2025-12-28T12:00:00.000Z",
+      "healthCheck": {
+        "path": "/health",
+        "method": "GET",
+        "algorithm": "http-status",
+        "timeout": 2000,
+        "hasCustomHeaders": false,
+        "hasCustomFunction": false
+      }
+    },
+    {
+      "id": 1,
+      "url": "http://localhost:5001",
+      "healthy": true,
+      "weight": 1,
+      "requests": 5,
+      "activeConnections": 0,
+      "lastChecked": "2025-12-28T12:00:00.000Z",
+      "healthCheck": {
+        "path": "/ready",
+        "method": "HEAD",
+        "algorithm": "http-status",
+        "timeout": 5000,
+        "hasCustomHeaders": true,
+        "hasCustomFunction": false
+      }
+    }
   ]
 }
 ```
@@ -127,11 +529,35 @@ Response example:
 
 ## Email Alerts
 
-- Alerts are sent when a backend goes down or comes back up.
-- Requires valid Gmail credentials (or any supported email service).
+When `email` is present in the config, an alert is sent to each backend's `owner` address when it goes down or comes back online.
+
+- Email alerts are implemented using [Nodemailer](https://nodemailer.com/).
+- Supports Gmail and other compatible SMTP providers.
+- For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) rather than your account password
+### Attention
+- Email alerts are optional.
+- Some hosting providers may restrict SMTP connections.
+- If email alerts are unavailable in your environment, simply omit the `email` configuration and the load balancer will continue to function normally.
+
+## Use Cases
+
+- Learning how load balancers and routing strategies work
+- Local development with multiple backend instances
+- Internal tools and prototypes
+- Small Node.js deployments that don't need Nginx
+
+---
+
+## Notes
+
+- Backend `id` values must be unique integers.
+- Sticky sessions take priority over strategy - a client always returns to their assigned backend if it is still healthy.
+- WebSocket proxying is supported out of the box.
+- If all backends go down, the load balancer returns `503 No healthy backends available`.
+- The `custom check` function is only available when passing config as a JS object - it cannot be expressed in JSON.
 
 ---
 
 ## License
 
-MIT
+MIT

package/code_of_conduct.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our Pledge
+
+Everyone who contributes to or uses this project is expected to keep interactions respectful and constructive. This is a learning-friendly project — beginners are welcome.
+
+## Expected Behaviour
+
+- Be kind and patient, especially with newcomers
+- Give constructive feedback on issues and pull requests
+- Accept feedback gracefully
+- Focus on what's best for the project
+
+## Unacceptable Behaviour
+
+- Harassment, insults, or personal attacks
+- Dismissing questions as "too basic"
+- Spam or off-topic promotion
+
+## Reporting
+
+If something feels wrong, open a private issue or contact the maintainer directly via GitHub. All reports will be handled with discretion.
+
+## Enforcement
+
+The maintainer reserves the right to close issues, remove comments, or block contributors who repeatedly violate this code.
+
+---
+
+This project follows the spirit of the [Contributor Covenant](https://www.contributor-covenant.org/).

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "smart-stick-loadbalancer",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "A lightweight sticky-session load balancer for Node.js with health checks and optional email alerts.",
   "main": "src/index.js",
-  "bin": {
-    "smart-stick-lb": "src/index.js"
-  },
   "scripts": {
     "start": "node src/index.js"
   },
@@ -13,11 +10,11 @@
     "load-balancer",
     "sticky-session",
     "proxy",
-    "Node.js",
+    "nodejs",
     "http-proxy",
     "health-check"
   ],
-  "author": "SWAYAM GUPTA",
+  "author": "Swayam Gupta",
   "license": "MIT",
   "dependencies": {
     "axios": "^1.10.0",
@@ -26,5 +23,9 @@
     "http-proxy-middleware": "^3.0.5",
     "nodemailer": "^7.0.5",
     "socket.io": "^4.8.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SwayamGupta12345/smart-stick-loadbalancer.git"
   }
 }

package/src/healthChecker.js

@@ -1,32 +1,77 @@
 const axios = require("axios");
+function resolveHealthConfig(server, globalConfig = {}) {
+  return {
+    path:      server.healthPath      ?? globalConfig.path      ?? "/",
+    method:    server.healthMethod    ?? globalConfig.method    ?? "GET",
+    algorithm: server.healthAlgorithm ?? globalConfig.algorithm ?? "http-status",
+    timeout:   server.healthTimeout   ?? globalConfig.timeout   ?? 2000,
+    headers:   server.healthHeaders   ?? globalConfig.headers   ?? {},
+    check:     server.healthCheck     ?? globalConfig.check     ?? null,
+  };
+}
+
+async function checkHealth(server, globalConfig = {}) {
+  const cfg = resolveHealthConfig(server, globalConfig);
+  const url = server.url.replace(/\/$/, "") + cfg.path;
+
+  // Custom function — per-backend or global
+  if (typeof cfg.check === "function") {
+    try {
+      const result = await cfg.check(server);
+      return Boolean(result);
+    } catch {
+      return false;
+    }
+  }
 
-async function checkHealth(server, timeout = 2000) {
   try {
-    await axios.get(server.url, { timeout });
-    return true;
+    const response = await axios.request({
+      method: cfg.method,
+      url,
+      timeout: cfg.timeout,
+      headers: cfg.headers,
+      // Never throw on status — we inspect it ourselves
+      validateStatus: () => true,
+    });
+
+    if (cfg.algorithm === "http") {
+      // Any response at all = healthy
+      return true;
+    }
+
+    // "http-status" — only 2xx
+    return response.status >= 200 && response.status < 300;
   } catch {
+    // Network error, timeout, DNS failure — always unhealthy
     return false;
   }
 }
 
-function startHealthChecker(servers, config, onDown, onUp) {
+function startHealthChecker(servers, globalConfig, onDown, onUp) {
   const lastStatus = new Map();
-  const interval = config?.interval || 10000;
-  const timeout = config?.timeout || 2000;
+  const interval = globalConfig?.interval || 10000;
 
   setInterval(async () => {
     for (const server of servers) {
-      const isUp = await checkHealth(server, timeout);
-      const wasUp = lastStatus.get(server.url) ?? true;
-      server.healthy = isUp;
-      server.lastChecked = new Date().toISOString();
+      try {
+        const isUp = await checkHealth(server, globalConfig);
+        const wasUp = lastStatus.get(server.url) ?? true;
+        server.healthy = isUp;
+        server.lastChecked = new Date().toISOString();
 
-      if (!isUp && wasUp && onDown) onDown(server);
-      if (isUp && !wasUp && onUp) onUp(server);
+        if (!isUp && wasUp && onDown) onDown(server);
+        if (isUp && !wasUp && onUp) onUp(server);
 
-      lastStatus.set(server.url, isUp);
+        lastStatus.set(server.url, isUp);
+      } catch (err) {
+        // Safety net — a bug in checkHealth should never kill the interval
+        console.error(
+          `[smart-stick-loadbalancer] Health check error for ${server.url}:`,
+          err.message
+        );
+      }
     }
   }, interval);
 }
 
-module.exports = { checkHealth, startHealthChecker };
+module.exports = { checkHealth, startHealthChecker, resolveHealthConfig };

package/src/index.js

@@ -3,43 +3,81 @@ const http = require("http");
 const { createProxyMiddleware } = require("http-proxy-middleware");
 const cookieParser = require("cookie-parser");
 const socketIo = require("socket.io");
-const { startHealthChecker } = require("./healthChecker");
+const { startHealthChecker, resolveHealthConfig } = require("./healthChecker");
 const { sendDownAlert, sendUpAlert } = require("./notifier");
+const { buildWeightedPool, selectBackend } = require("./router");
 
 function createStickyProxy(options = {}) {
-  if (!options.port || !options.backends) {
-    throw new Error("Port and backends must be provided");
+  if (!options.port) {
+    throw new Error("[smart-stick-loadbalancer] 'port' is required in config.");
+  }
+  if (!options.backends || !Array.isArray(options.backends) || options.backends.length === 0) {
+    throw new Error("[smart-stick-loadbalancer] 'backends' must be a non-empty array in config.");
+  }
+
+  const strategy = options.strategy || "round-robin";
+  const validStrategies = ["round-robin", "least-connections", "random"];
+  if (!validStrategies.includes(strategy)) {
+    throw new Error(
+      `[smart-stick-loadbalancer] Unknown strategy '${strategy}'. Valid options: ${validStrategies.join(", ")}`
+    );
   }
 
   const app = express();
   const server = http.createServer(app);
   const io = socketIo(server);
 
-  let current = 0;
   const servers = options.backends.map((b) => ({
     ...b,
+    weight: b.weight ?? 1,
     healthy: true,
     requests: 0,
+    activeConnections: 0,
     lastChecked: null,
   }));
 
+  // Pre-build weighted pool for round-robin (rebuilt when health changes)
+  let weightedPool = buildWeightedPool(servers.filter((s) => s.healthy));
+  let poolIndex = 0;
+
+  function rebuildPool() {
+    weightedPool = buildWeightedPool(servers.filter((s) => s.healthy));
+    poolIndex = 0;
+  }
+
   // Middleware
   app.use(cookieParser());
 
   // Health endpoint
+  const healthConfig = options.health || {};
   app.get("/_lb/health", (req, res) => {
     res.json({
       timestamp: new Date().toISOString(),
+      strategy,
       total: servers.length,
       healthy: servers.filter((s) => s.healthy).length,
       unhealthy: servers.filter((s) => !s.healthy).length,
-      backends: servers.map((s) => ({
-        id: s.id,
-        url: s.url,
-        healthy: s.healthy,
-        requests: s.requests,
-        lastChecked: s.lastChecked,
-      })),
+      backends: servers.map((s) => {
+        const resolved = resolveHealthConfig(s, healthConfig);
+        return {
+          id: s.id,
+          url: s.url,
+          healthy: s.healthy,
+          weight: s.weight,
+          requests: s.requests,
+          activeConnections: s.activeConnections,
+          lastChecked: s.lastChecked,
+          healthCheck: {
+            path: resolved.path,
+            method: resolved.method,
+            algorithm: resolved.algorithm,
+            timeout: resolved.timeout,
+            // Don't expose headers (may contain auth tokens) or function source
+            hasCustomHeaders: Object.keys(resolved.headers).length > 0,
+            hasCustomFunction: typeof resolved.check === "function",
+          },
+        };
+      }),
     });
   });
 
@@ -48,15 +86,21 @@ function createStickyProxy(options = {}) {
     const healthyBackends = servers.filter((s) => s.healthy);
     if (!healthyBackends.length) return null;
 
-    let backendId = parseInt(req.cookies["X-Backend-ID"]);
-    if (!isNaN(backendId) && servers[backendId]?.healthy) {
-      return servers[backendId];
+    // Honour sticky cookie if backend is still healthy
+    const cookieId = parseInt(req.cookies["X-Backend-ID"]);
+    if (!isNaN(cookieId)) {
+      const sticky = servers.find((s) => s.id === cookieId && s.healthy);
+      if (sticky) return sticky;
     }
 
-    const selected = healthyBackends[current % healthyBackends.length];
-    current++;
-    res.cookie("X-Backend-ID", selected.id, { httpOnly: true });
-    return selected;
+    // No valid sticky — select via chosen strategy
+    const result = selectBackend(strategy, healthyBackends, weightedPool, poolIndex);
+    if (strategy === "round-robin") {
+      poolIndex = result.nextIndex;
+    }
+
+    res.cookie("X-Backend-ID", result.backend.id, { httpOnly: true });
+    return result.backend;
   }
 
   // Proxy instances
@@ -68,8 +112,19 @@ function createStickyProxy(options = {}) {
         target: backend.url,
         changeOrigin: true,
         ws: true,
-        onProxyRes(proxyRes, req, res) {
-          res.setHeader("x-backend", backend.url);
+        on: {
+          proxyRes(proxyRes, req, res) {
+            if (!res.headersSent) {
+              res.setHeader("x-backend", backend.url);
+              res.setHeader("x-backend-id", backend.id);
+            }
+          },
+          error(err, req, res) {
+            backend.activeConnections = Math.max(0, backend.activeConnections - 1);
+            if (!res.headersSent) {
+              res.status(502).json({ error: "Bad gateway — backend did not respond." });
+            }
+          },
         },
       })
     );
@@ -78,31 +133,48 @@ function createStickyProxy(options = {}) {
   // Proxy handler
   app.use((req, res, next) => {
     const backend = getHealthyBackend(req, res);
-    if (!backend) return res.status(503).send("All servers down.");
+    if (!backend) {
+      return res.status(503).json({ error: "No healthy backends available." });
+    }
 
     backend.requests++;
-    io.emit("request", { ip: req.ip, to: backend.url });
-    io.emit("update", servers);
+    backend.activeConnections++;
+
+    // Decrement active connections when response finishes
+    res.on("finish", () => {
+      backend.activeConnections = Math.max(0, backend.activeConnections - 1);
+    });
+
+    // Emit per-request event for live dashboards — lightweight, no full server list
+    io.emit("request", { ip: req.ip, to: backend.url, backendId: backend.id, strategy });
 
     const proxy = proxies.get(backend.id);
     proxy(req, res, next);
   });
 
-  // Health checks with optional email alerts
+  // Health checks — rebuild weighted pool on status change
   startHealthChecker(
     servers,
     options.health || { interval: 10000, timeout: 2000 },
-    options.email ? (server) => { sendDownAlert(server, options.email); io.emit("update", servers); } : null,
-    options.email ? (server) => { sendUpAlert(server, options.email); io.emit("update", servers); } : null
+    (server) => {
+      rebuildPool();
+      io.emit("update", servers);
+      if (options.email) sendDownAlert(server, options.email);
+    },
+    (server) => {
+      rebuildPool();
+      io.emit("update", servers);
+      if (options.email) sendUpAlert(server, options.email);
+    }
   );
 
   function start() {
     server.listen(options.port, () =>
-      console.log(`Sticky Proxy running on port ${options.port}`)
+      console.log(`[smart-stick-loadbalancer] Running on port ${options.port} | strategy: ${strategy}`)
     );
   }
 
   return { app, server, io, start, servers };
 }
 
-module.exports = { createStickyProxy };
+module.exports = { createStickyProxy };

package/src/notifier.js

@@ -1,33 +1,48 @@
 const nodemailer = require("nodemailer");
 
-function createTransport(emailConfig) {
+const transporterCache = new WeakMap();
+
+function getTransporter(emailConfig) {
   if (!emailConfig) return null;
-  return nodemailer.createTransport({
+  if (transporterCache.has(emailConfig)) return transporterCache.get(emailConfig);
+
+  const transporter = nodemailer.createTransport({
     service: emailConfig.service,
     auth: emailConfig.auth,
   });
+
+  transporterCache.set(emailConfig, transporter);
+  return transporter;
 }
 
-function sendDownAlert(server, emailConfig) {
-  const transporter = createTransport(emailConfig);
-  if (!transporter) return;
-  transporter.sendMail({
-    from: emailConfig.auth.user,
-    to: server.owner,
-    subject: "⚠️ Backend Down",
-    text: `Your backend at ${server.url} is down.`,
-  });
+async function sendDownAlert(server, emailConfig) {
+  const transporter = getTransporter(emailConfig);
+  if (!transporter || !server.owner) return;
+  try {
+    await transporter.sendMail({
+      from: emailConfig.auth.user,
+      to: server.owner,
+      subject: "⚠️ Backend Down",
+      text: `Your backend at ${server.url} is down.\nTime: ${new Date().toISOString()}`,
+    });
+  } catch (err) {
+    console.error(`[smart-stick-loadbalancer] Failed to send down alert for ${server.url}:`, err.message);
+  }
 }
 
-function sendUpAlert(server, emailConfig) {
-  const transporter = createTransport(emailConfig);
-  if (!transporter) return;
-  transporter.sendMail({
-    from: emailConfig.auth.user,
-    to: server.owner,
-    subject: "✅ Backend Recovered",
-    text: `Your backend at ${server.url} is back online.`,
-  });
+async function sendUpAlert(server, emailConfig) {
+  const transporter = getTransporter(emailConfig);
+  if (!transporter || !server.owner) return;
+  try {
+    await transporter.sendMail({
+      from: emailConfig.auth.user,
+      to: server.owner,
+      subject: "✅ Backend Recovered",
+      text: `Your backend at ${server.url} is back online.\nTime: ${new Date().toISOString()}`,
+    });
+  } catch (err) {
+    console.error(`[smart-stick-loadbalancer] Failed to send up alert for ${server.url}:`, err.message);
+  }
 }
 
-module.exports = { sendDownAlert, sendUpAlert };
+module.exports = { sendDownAlert, sendUpAlert };

package/src/router.js

@@ -0,0 +1,41 @@
+function buildWeightedPool(healthyBackends) {
+  const pool = [];
+  for (const backend of healthyBackends) {
+    const slots = Math.max(1, Math.round(backend.weight ?? 1));
+    for (let i = 0; i < slots; i++) {
+      pool.push(backend);
+    }
+  }
+  return pool;
+}
+
+function selectBackend(strategy, healthyBackends, weightedPool, currentIndex) {
+  switch (strategy) {
+    case "round-robin": {
+      if (!weightedPool.length) return { backend: healthyBackends[0], nextIndex: 0 };
+      const backend = weightedPool[currentIndex % weightedPool.length];
+      return { backend, nextIndex: (currentIndex + 1) % weightedPool.length };
+    }
+
+    case "least-connections": {
+      // Pick the healthy backend with the lowest activeConnections count.
+      // Ties broken by whichever appears first (effectively round-robin on ties).
+      const backend = healthyBackends.reduce((best, candidate) =>
+        candidate.activeConnections < best.activeConnections ? candidate : best
+      );
+      return { backend, nextIndex: currentIndex };
+    }
+
+    case "random": {
+      // Weighted random — pick a random slot from the weighted pool.
+      if (!weightedPool.length) return { backend: healthyBackends[0], nextIndex: 0 };
+      const idx = Math.floor(Math.random() * weightedPool.length);
+      return { backend: weightedPool[idx], nextIndex: currentIndex };
+    }
+
+    default:
+      return { backend: healthyBackends[0], nextIndex: 0 };
+  }
+}
+
+module.exports = { buildWeightedPool, selectBackend };

package/src/config.json

@@ -1,28 +0,0 @@
-{
-  "port": 3001,
-  "backends": [
-    {
-      "id": 0,
-      "url":"<link to reviewer instance>",
-      "owner": "<reviewer email>",
-      "weight": 1
-    },
-    {
-      "id": 1,
-      "url": "<link to reviewer instance>",
-      "owner": "<reviewer email>",
-      "weight": 1
-    }
-  ],
-  "health": {
-    "interval": 10000,
-    "timeout": 2000
-  },
-  "email": {
-    "service": "gmail",
-    "auth": {
-      "user": "<sendermail>@gmail.com",
-      "pass": "<app password>"
-    }
-  }
-}