Skip to main content

​
Overview

The BackendPool class maintains a collection of backend servers and their health status. It provides methods to query backends, filter by health status, and update health states based on health checks or proxy errors.

​
Constructor

Creates a new BackendPool with the specified backend server URLs. 
constructor(urls: string[])
​
urls
string[]
required
Array of backend server URLs to include in the pool. Each URL should be a complete HTTP/HTTPS endpoint (e.g., http://localhost:3001).
Behavior:
  • Each URL is converted to a Backend object with initial health: true status
  • All backends start in a healthy state by default

​
Backend interface

The Backend interface represents a single backend server in the pool. 
interface Backend {
  url: string;
  health: boolean;
}
​
url
string
The complete URL of the backend server (e.g., http://localhost:3001)
​
health
boolean
Health status of the backend. true indicates healthy and available, false indicates unhealthy and should not receive traffic.

​
Methods

​
getAllBackends()

Returns all backends in the pool regardless of health status. 
getAllBackends(): Backend[]
Returns: Backend[] - Array of all backend objects in the pool. Use case: Primarily used by the health checker to verify all backends, including those currently marked unhealthy.

​
getHealthyBackends()

Returns only the backends that are currently marked as healthy. 
getHealthyBackends(): Backend[]
Returns: Backend[] - Array of backend objects where health === true. Use case: Used by the load balancer to select from available backends when routing requests.

​
markHealthy()

Marks a specific backend as healthy and available for routing traffic. 
markHealthy(url: string): void
​
url
string
required
The URL of the backend to mark as healthy.
Behavior:
  • Searches for a backend with matching URL
  • Sets health: true if found
  • No-op if URL doesn’t match any backend in the pool

​
markUnhealthy()

Marks a specific backend as unhealthy and removes it from rotation. 
markUnhealthy(url: string): void
​
url
string
required
The URL of the backend to mark as unhealthy.
Behavior:
  • Searches for a backend with matching URL
  • Sets health: false if found
  • No-op if URL doesn’t match any backend in the pool
  • Triggered by failed health checks or proxy errors

​
Usage examples

​
Creating a backend pool

import { BackendPool } from './balancer/pool';

const pool = new BackendPool([
  'http://localhost:3001',
  'http://localhost:3002',
  'http://localhost:3003'
]);

console.log('Total backends:', pool.getAllBackends().length);
// Output: Total backends: 3

​
Querying backend health

// Get all backends
const allBackends = pool.getAllBackends();
console.log('All backends:', allBackends);

// Get only healthy backends
const healthyBackends = pool.getHealthyBackends();
console.log('Healthy backends:', healthyBackends.length);

// Check specific backend health
const backend = allBackends.find(b => b.url === 'http://localhost:3001');
if (backend?.health) {
  console.log('Backend is healthy');
}

​
Updating health status

// Mark backend as unhealthy (e.g., after failed health check)
pool.markUnhealthy('http://localhost:3001');
console.log('Healthy count:', pool.getHealthyBackends().length);
// Output: Healthy count: 2

// Restore backend to healthy state
pool.markHealthy('http://localhost:3001');
console.log('Healthy count:', pool.getHealthyBackends().length);
// Output: Healthy count: 3

​
Integration with health checker

import { HealthChecker } from './healthchecker/healthChecker';

// Health checker automatically updates pool status
const healthChecker = new HealthChecker(pool, 5000);
healthChecker.start();

// Health checker will call markHealthy() or markUnhealthy()
// based on backend responses

​
Handling proxy failures

// When a proxy request fails, mark backend as unhealthy
try {
  await fetch(backend.url);
} catch (error) {
  pool.markUnhealthy(backend.url);
  console.log('Backend marked unhealthy due to proxy error');
}

Build docs developers (and LLMs) love

Get started for freeTalk to us