Struct ClientTopology 

pub struct ClientTopology { /* private fields */ }

A driver’s cached view of cluster topology, and the contract for keeping it correct (issue #994).

Holds the ranges the driver believes in, the authoritative version of the last polled or pushed snapshot, and a needs_refresh flag that is raised whenever the driver is running on an advisory hint correction rather than authoritative topology.

The three inputs compose by authority: apply_refresh and apply_update are authoritative and monotonic; apply_hint is advisory and only ever corrects a known range’s owner/epoch. Authority always wins — an authoritative apply that is newer overwrites a prior hint correction and clears needs_refresh.

Implementations

impl ClientTopology

pub fn from_snapshot(snapshot: TopologySnapshot) -> ClientTopology

Seed a cache from an initial topology poll.

pub fn version(&self) -> CatalogVersion

The authoritative generation of this cache — the version of the most recent snapshot or range delta adopted. Advisory hint corrections do not move it, so it always reflects authoritative topology.

pub fn needs_refresh(&self) -> bool

Whether the cache is running on an advisory hint correction and should poll for authoritative topology. Raised by apply_hint; cleared by an authoritative apply_refresh (or a full-snapshot apply_update).

pub fn route( &self, collection: &CollectionId, key: &[u8], ) -> Option<&TopologyRange>

The cached range owning a normalized range key.

pub fn resolve( &self, collection: &CollectionId, key: &[u8], ) -> Option<&NodeIdentity>

The owner a driver should send a request for key to — the routing answer.

pub fn route_shard_key( &self, collection: &CollectionId, shard_key: &[u8], ) -> Option<&TopologyRange>

The cached range owning a logical shard key.

pub fn range( &self, collection: &CollectionId, range_id: RangeId, ) -> Option<&TopologyRange>

One cached range by identity.

pub fn apply_refresh(&mut self, snapshot: TopologySnapshot) -> RefreshOutcome

Adopt a freshly polled snapshot — the authoritative refresh path.

Monotonic: the snapshot is adopted if its generation advances the cache’s authoritative version, or if it carries same-generation range content that does not roll any cached range backwards. An adopted snapshot replaces the cached ranges wholesale and clears needs_refresh; an older or duplicate one is Ignored.

pub fn apply_update(&mut self, update: TopologyUpdate) -> RefreshOutcome

Fold a pushed topology update in — the optional push/subscription path.

A Full push is exactly an apply_refresh. A Range delta advances a single range when its version is newer than the cached one (and bumps the authoritative version to match), or is Ignored when it is not newer. Because both go through the same monotonic guard, a missed push is never a correctness problem — a later poll or delta carries the change forward.

pub fn apply_hint(&mut self, hint: &RoutingHint) -> HintOutcome

Apply an advisory routing-hint correction from a redirect response — the stale-ownership correctness path (issue #993, ADR 0037).

A hint is not authoritative: it can only correct the owner/epoch of a range the cache already knows, and only when it is strictly newer than the cached range. On a correction the cached owner/epoch/version advance (the known bounds are kept; the replica set is left as-is because a hint carries none) and needs_refresh is raised so the driver reconciles against an authoritative poll. A hint for an unknown range creates nothing — it only raises needs_refresh.

Trait Implementations

impl Clone for ClientTopology

fn clone(&self) -> ClientTopology

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClientTopology

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

Formats the value using the given formatter.

impl Eq for ClientTopology

impl PartialEq for ClientTopology

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ClientTopology