smart-stick-loadbalancer 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# 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.  
+
+---
+
+## Features
+
+- Sticky sessions via cookies  
+- Health checks with automatic failover  
+- Optional email alerts  
+- WebSocket and HTTP support  
+- Minimal setup  
+
+---
+
+## Installation
+
+```bash
+npm install smart-stick-loadbalancer
+```
+
+---
+
+## Example Configuration (`config.json`)
+
+```json
+{
+  "port": 3001,
+  "backends": [
+    { "id": 0, "url": "http://localhost:5000", "owner": "example@example.com", "weight": 1 },
+    { "id": 1, "url": "http://localhost:5001", "owner": "example@example.com", "weight": 1 }
+  ],
+  "health": { "interval": 10000, "timeout": 2000 },
+  "email": {
+    "service": "gmail",
+    "auth": { "user": "<your-email@gmail.com>", "pass": "<your-app-password>" }
+  }
+}
+```
+
+---
+
+## Usage
+
+```js
+const { createStickyProxy } = require('smart-stick-loadbalancer');
+const config = require('./config.json');
+
+const lb = createStickyProxy(config);
+lb.start(); // starts the load balancer
+```
+
+- 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.  
+
+---
+
+## Health Endpoint
+
+```http
+GET /_lb/health
+```
+
+Response example:
+
+```json
+{
+  "timestamp": "2025-12-28T12:00:00.000Z",
+  "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 }
+  ]
+}
+```
+
+---
+
+## Email Alerts
+
+- Alerts are sent when a backend goes down or comes back up.  
+- Requires valid Gmail credentials (or any supported email service).  
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "smart-stick-loadbalancer",
+  "version": "1.0.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"
+  },
+  "keywords": [
+    "load-balancer",
+    "sticky-session",
+    "proxy",
+    "Node.js",
+    "http-proxy",
+    "health-check"
+  ],
+  "author": "SWAYAM GUPTA",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.10.0",
+    "cookie-parser": "^1.4.7",
+    "express": "^5.1.0",
+    "http-proxy-middleware": "^3.0.5",
+    "nodemailer": "^7.0.5",
+    "socket.io": "^4.8.3"
+  }
+}

package/src/config.json

@@ -0,0 +1,28 @@
+{
+  "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>"
+    }
+  }
+}

package/src/healthChecker.js

@@ -0,0 +1,32 @@
+const axios = require("axios");
+
+async function checkHealth(server, timeout = 2000) {
+  try {
+    await axios.get(server.url, { timeout });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function startHealthChecker(servers, config, onDown, onUp) {
+  const lastStatus = new Map();
+  const interval = config?.interval || 10000;
+  const timeout = config?.timeout || 2000;
+
+  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();
+
+      if (!isUp && wasUp && onDown) onDown(server);
+      if (isUp && !wasUp && onUp) onUp(server);
+
+      lastStatus.set(server.url, isUp);
+    }
+  }, interval);
+}
+
+module.exports = { checkHealth, startHealthChecker };

package/src/index.js

@@ -0,0 +1,108 @@
+const express = require("express");
+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 { sendDownAlert, sendUpAlert } = require("./notifier");
+
+function createStickyProxy(options = {}) {
+  if (!options.port || !options.backends) {
+    throw new Error("Port and backends must be provided");
+  }
+
+  const app = express();
+  const server = http.createServer(app);
+  const io = socketIo(server);
+
+  let current = 0;
+  const servers = options.backends.map((b) => ({
+    ...b,
+    healthy: true,
+    requests: 0,
+    lastChecked: null,
+  }));
+
+  // Middleware
+  app.use(cookieParser());
+
+  // Health endpoint
+  app.get("/_lb/health", (req, res) => {
+    res.json({
+      timestamp: new Date().toISOString(),
+      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,
+      })),
+    });
+  });
+
+  // Sticky selection logic
+  function getHealthyBackend(req, res) {
+    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];
+    }
+
+    const selected = healthyBackends[current % healthyBackends.length];
+    current++;
+    res.cookie("X-Backend-ID", selected.id, { httpOnly: true });
+    return selected;
+  }
+
+  // Proxy instances
+  const proxies = new Map();
+  servers.forEach((backend) => {
+    proxies.set(
+      backend.id,
+      createProxyMiddleware({
+        target: backend.url,
+        changeOrigin: true,
+        ws: true,
+        onProxyRes(proxyRes, req, res) {
+          res.setHeader("x-backend", backend.url);
+        },
+      })
+    );
+  });
+
+  // Proxy handler
+  app.use((req, res, next) => {
+    const backend = getHealthyBackend(req, res);
+    if (!backend) return res.status(503).send("All servers down.");
+
+    backend.requests++;
+    io.emit("request", { ip: req.ip, to: backend.url });
+    io.emit("update", servers);
+
+    const proxy = proxies.get(backend.id);
+    proxy(req, res, next);
+  });
+
+  // Health checks with optional email alerts
+  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
+  );
+
+  function start() {
+    server.listen(options.port, () =>
+      console.log(`Sticky Proxy running on port ${options.port}`)
+    );
+  }
+
+  return { app, server, io, start, servers };
+}
+
+module.exports = { createStickyProxy };

package/src/notifier.js

@@ -0,0 +1,33 @@
+const nodemailer = require("nodemailer");
+
+function createTransport(emailConfig) {
+  if (!emailConfig) return null;
+  return nodemailer.createTransport({
+    service: emailConfig.service,
+    auth: emailConfig.auth,
+  });
+}
+
+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.`,
+  });
+}
+
+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.`,
+  });
+}
+
+module.exports = { sendDownAlert, sendUpAlert };