Struct UpgradeReject 

#[non_exhaustive]
pub struct UpgradeReject {
    pub role_byte: u8,
    pub role_name: String,
    pub zone: Option<String>,
}

Upgrade-time topology rejection carried alongside an crate::Error.

Populated when the server rejects the WebSocket upgrade with HTTP 421 plus an X-QuestDB-Role header (per failover.md §5), or when a SERVER_INFO frame advertises a role that does not match the configured target= filter. The host-health tracker (when present) reads this to decide whether the host is in TransientReject (PRIMARY_CATCHUP) or TopologyReject (every other role byte) and to update zone tier from the optional X-QuestDB-Zone / SERVER_INFO.zone_id.

role_byte is the raw SERVER_INFO.role byte from wire-egress.md §11.8 (0x00=STANDALONE, 0x01=PRIMARY, 0x02=REPLICA, 0x03=PRIMARY_CATCHUP); unrecognised values are carried through verbatim so a future role addition is observable to operators even on an older client build. role_name is the ASCII token actually seen on the wire (uppercased for the four named roles; the literal header value when the byte is unknown); it is kept so diagnostics surface what the server said, not what the client decided to call it. zone is Some only when the server advertised one (via SERVER_INFO.zone_id gated on CAP_ZONE, or the X-QuestDB-Zone upgrade header).

#[non_exhaustive] so future fields (a structured replay-hint, a retry-after value, a cluster-ID tag — anything the failover.md spec might extend 421 reject headers with) can be added without breaking downstream struct-literal construction or exhaustive destructuring. Use UpgradeReject::new to construct from external code.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

role_byte: u8

role_name: String

zone: Option<String>

Implementations

impl UpgradeReject

pub fn new( role_byte: u8, role_name: impl Into<String>, zone: Option<String>, ) -> Self

pub fn is_transient(&self) -> bool

True when the server-advertised role is PRIMARY_CATCHUP — a transient state (promotion in flight) that the tracker should classify as recoverable. Every other role byte is topological (won’t recover without operator intervention or topology change). Per failover.md §6: any non-empty X-QuestDB-Role value other than PRIMARY_CATCHUP is conservatively treated as topological, including unrecognised tokens.

Trait Implementations

impl Clone for UpgradeReject

fn clone(&self) -> UpgradeReject

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UpgradeReject

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

Formats the value using the given formatter.

impl Eq for UpgradeReject

impl PartialEq for UpgradeReject

fn eq(&self, other: &UpgradeReject) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for UpgradeReject