Struct Cluster 

pub struct Cluster {
    pub name: Arc<str>,
    pub connection_timeout_ms: Option<u64>,
    pub endpoints: Vec<Endpoint>,
    pub health_check: Option<HealthCheckConfig>,
    pub idle_timeout_ms: Option<u64>,
    pub load_balancer_strategy: LoadBalancerStrategy,
    pub max_connections: Option<u32>,
    pub read_timeout_ms: Option<u64>,
    pub tls: Option<ClusterTls>,
    pub total_connection_timeout_ms: Option<u64>,
    pub write_timeout_ms: Option<u64>,
}

A named group of upstream endpoints.

let yaml = r#"
name: "backend"
endpoints: ["10.0.0.1:8080"]
connection_timeout_ms: 5000
idle_timeout_ms: 30000
"#;
let cluster: Cluster = serde_yaml::from_str(yaml).unwrap();
assert_eq!(cluster.connection_timeout_ms, Some(5000));
assert_eq!(cluster.idle_timeout_ms, Some(30000));
assert!(cluster.read_timeout_ms.is_none());
assert!(cluster.tls.is_none());

Fields

name: Arc<str>

Unique name for the cluster.

connection_timeout_ms: Option<u64>

TCP connection timeout in milliseconds.

Applies to the TCP handshake only (before TLS). When exceeded, the connection attempt fails and the load balancer may retry on the next endpoint. None (the default) uses Pingora’s built-in timeout.

endpoints: Vec<Endpoint>

List of endpoints for the cluster. Each entry is either a plain "host:port" string or a { address, weight } object.

health_check: Option<HealthCheckConfig>

Active health check configuration for this cluster.

idle_timeout_ms: Option<u64>

Idle connection timeout in milliseconds.

Closes pooled upstream connections that have been idle longer than this duration. None uses Pingora’s default.

load_balancer_strategy: LoadBalancerStrategy

Load-balancing algorithm for this cluster. Defaults to round_robin.

max_connections: Option<u32>

Maximum concurrent in-flight requests to this cluster.

When set, excess requests receive 503. Prevents a single slow upstream from consuming all available capacity.

let yaml = r#"
name: backend
endpoints: ["10.0.0.1:80"]
max_connections: 100
"#;
let cluster: Cluster = serde_yaml::from_str(yaml).unwrap();
assert_eq!(cluster.max_connections, Some(100));

read_timeout_ms: Option<u64>

Per-read timeout in milliseconds.

Applies to each individual read operation on an established upstream connection. A timeout fires a 502 response to the client. Use total_connection_timeout_ms to bound the entire exchange instead.

tls: Option<ClusterTls>

TLS settings for upstream connections.

Presence implies TLS is enabled. Omit for plaintext HTTP.

total_connection_timeout_ms: Option<u64>

Total connection timeout in milliseconds (TCP + TLS).

Bounds the combined TCP handshake and TLS negotiation. When exceeded, the connection attempt fails with a 502 response. Prefer this over connection_timeout_ms for TLS-enabled clusters where the handshake dominates latency.

write_timeout_ms: Option<u64>

Per-write timeout in milliseconds.

Applies to each individual write operation on an established upstream connection. A timeout fires a 502 response to the client.

Implementations

impl Cluster

pub fn with_defaults(name: &str, endpoints: Vec<Endpoint>) -> Self

Build a cluster with only a name and endpoints; all other fields use their defaults (no timeouts, no TLS, no health check, round_robin strategy).

use praxis_core::config::Cluster;
use praxis_tls::ClusterTls;

let c = Cluster {
    tls: Some(ClusterTls::default()),
    ..Cluster::with_defaults("backend", vec!["10.0.0.1:443".into()])
};
assert_eq!(&*c.name, "backend");
assert!(c.tls.is_some());
assert!(c.tls.as_ref().unwrap().verify);

Trait Implementations

impl Clone for Cluster

fn clone(&self) -> Cluster

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Cluster

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Cluster

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<&Cluster> for ConnectionOptions

Converts cluster timeout fields (milliseconds) to Duration values.

use std::time::Duration;

use praxis_core::{config::Cluster, connectivity::ConnectionOptions};

let cluster: Cluster = serde_yaml::from_str(
    r#"
name: backend
endpoints: ["10.0.0.1:80"]
connection_timeout_ms: 5000
"#,
)
.unwrap();
let opts = ConnectionOptions::from(&cluster);
assert_eq!(opts.connection_timeout, Some(Duration::from_secs(5)));

fn from(cluster: &Cluster) -> Self

Converts to this type from the input type.

impl Serialize for Cluster

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.