Struct BackendPool 

pub struct BackendPool { /* private fields */ }

Thread-safe pool of backend addresses, optionally refreshed in the background.

Clone this type freely — all clones share the same underlying RwLock<Vec>.

Implementations

impl BackendPool

pub fn static(backends: Vec<String>) -> Self

Create a pool from a fixed list of backends.

The list is available immediately; start() is a no-op.

pub fn env_prefix(prefix: impl Into<String>) -> Self

Create a pool whose backends are read from environment variables PREFIX_0, PREFIX_1, … at startup and every poll_interval_secs.

pub fn file(path: impl Into<String>) -> Self

Create a pool whose backends are read from a file (one host:port per line).

pub fn dns(hostname: impl Into<String>, port: u16) -> Self

Create a pool whose backends are discovered via DNS A-record lookup.

pub fn dns_srv(record: impl Into<String>) -> Self

Create a pool whose backends are discovered via DNS SRV lookup (e.g. _http._tcp.my-service.default.svc.cluster.local for a Kubernetes headless Service). See DiscoverySource::DnsSrv for the priority/weight handling.

pub fn consul(addr: impl Into<String>, service: impl Into<String>) -> Self

Create a pool whose backends are discovered via a Consul agent’s /v1/health/service/:name endpoint. addr is host:port of the agent, e.g. "127.0.0.1:8500". Only instances passing all health checks are returned.

pub fn docker(label: impl Into<String>) -> Self

Create a pool whose backends are discovered from running Docker containers carrying label, using the default socket path (/var/run/docker.sock). See DiscoverySource::Docker for the label-value-is-the-address convention. Unix-only; a no-op elsewhere.

pub fn docker_with_socket( label: impl Into<String>, socket_path: impl Into<String>, ) -> Self

Same as BackendPool::docker but against a non-default Docker socket path.

pub fn etcd(endpoints: Vec<String>, prefix: impl Into<String>) -> Self

Create a pool whose backends are discovered from an etcd v3 key prefix, kept live via a watch stream once BackendPool::start is called. endpoints is a list of host:port etcd cluster members — only the first is used today (no client-side failover yet). Plain HTTP only. See DiscoverySource::EtcdWatch.

pub fn poll_interval_secs(self, secs: u64) -> Self

Override the background refresh interval (default: 30 seconds).

Only meaningful for File and Dns sources.

pub fn start(&self)

Start the background refresh thread.

For Static sources this is a no-op. For all others, an immediate refresh() is performed before spawning the background thread so that the first backends() call returns a populated list.

EtcdWatch is special-cased: instead of the generic sleep-and-poll loop, a dedicated thread holds a long-lived connection to etcd’s watch stream and applies PUT/DELETE events to the backend list as they arrive — no polling interval involved after the initial refresh().

pub fn backends(&self) -> Vec<String>

Return a snapshot of the current backend list.

pub fn update(&self, backends: Vec<String>)

Replace the current backend list with backends.

Useful for testing or for external control planes that push updates.

pub fn refresh(&self)

Perform one synchronous refresh cycle.

Called automatically by start() and by the background thread.

Trait Implementations

impl Clone for BackendPool

fn clone(&self) -> BackendPool

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.