Clusters & Endpoints

A cluster is a logical group of upstream backend endpoints that share a load balancing policy, circuit breaker, and connection pool.

[[clusters]]
name = "api-backend"
lb_policy = "round_robin"
connect_timeout_ms = 5000
max_idle_connections = 8
endpoints = [
  { address = "10.0.1.1:8080", weight = 1 },
  { address = "10.0.1.2:8080", weight = 2 },
  { address = "10.0.1.3:8080", weight = 1 },
]

Fields

Field	Type	Required	Default	Description
`name`	string	yes	—	Unique cluster name
`lb_policy`	string	yes	—	Load balancing algorithm
`connect_timeout_ms`	integer	yes	—	Upstream TCP connect timeout
`max_idle_connections`	integer	no	8	Max idle pooled connections per endpoint
`endpoints`	array	yes	—	List of backend endpoints
`circuit_breaker`	table	no	see below	Circuit breaker limits
`health_check`	table	no	none	Active health check config

Load Balancing Policies

Policy	Description
`round_robin`	Cycles through healthy endpoints sequentially
`least_request`	Power-of-two-choices: picks the endpoint with fewer active requests
`maglev`	Consistent hashing for sticky sessions (minimal disruption on changes)
`random`	Random selection among healthy endpoints

Endpoint Weights

Endpoints with higher weights receive proportionally more traffic. A weight of 2 receives roughly twice the traffic of weight 1.

Circuit Breaker

[clusters.circuit_breaker]
max_connections = 1024
max_pending_requests = 1024
max_requests = 1024

When limits are exceeded, the proxy returns 503 Service Unavailable instead of overloading the backend. Circuit breaker state is managed via RAII guards — the slot is automatically released when the request completes or the connection drops.

Connection Pooling

Meridian maintains a pool of idle TCP connections to each endpoint. When a new request arrives, it checks out a pooled connection instead of performing a TCP handshake. Connections are returned to the pool after use if the upstream supports keep-alive.

Max idle per endpoint: configurable (default 8)
Max connection age: 90 seconds (expired connections are evicted)
LIFO ordering: most recently returned connection is reused first (warmest cache)