Struct AddressList

Source

pub struct AddressList { /* private fields */ }

Expand description

A structure to manage DAPI addresses to select from for DapiRequest execution.

Address selection is sticky: requests rotate over a small active set of addresses (5 by default, see AddressList::with_active_set_size) and the rest of the list serves as failover standby (see AddressList::get_live_address).

Implementations§

Source §

impl AddressList

Source

pub fn new() -> Self

Creates an empty AddressList with default base ban time.

Source

pub fn with_settings(base_ban_period: Duration) -> Self

Creates an empty AddressList with adjustable base ban time.

Source

pub fn with_active_set_size(self, size: usize) -> Self

Set how many addresses receive traffic at a time.

Defaults to 5. 0 is clamped to 1. Smaller values maximize connection reuse, larger values spread load over more nodes. The effective size is additionally capped by the number of live addresses, so a very large value (e.g. usize::MAX) disables stickiness and round-robins over the whole list.

The size lives in the rotation state shared by every clone of this list, so it applies to all clones and takes effect on the next selection (shrinking drops the excess members).

Source

pub fn ban(&self, address: &Address) -> bool

Bans address Returns false if the address is not in the list.

Back-compat shim for AddressList::ban_with_reason with no reason.

Source

pub fn ban_with_reason(&self, address: &Address, reason: Option<String>) -> bool

Bans address, recording the reason for the ban. Returns false if the address is not in the list.

Source

pub fn ban_for( &self, address: &Address, period: Duration, reason: Option<String>, ) -> bool

Ban the address for an exact period (server-advertised); delegates to AddressStatus::ban_for — see that method for the full contract including the ban_count floor and ladder side-effect.

Returns false if the address is not in the list.

Source

pub fn unban(&self, address: &Address) -> bool

Clears address’ ban record Returns false if the address is not in the list.

Source

pub fn is_banned(&self, address: &Address) -> bool

Check if the address is banned.

Source

pub fn add(&mut self, address: Address) -> bool

Adds a node Address to AddressList Returns false if the address is already in the list.

Source

pub fn remove(&mut self, address: &Address) -> Option<AddressStatus>

Remove address from the list Returns AddressStatus if the address was in the list.

Source

pub fn add_uri(&mut self, uri: Uri) -> bool

👎Deprecated

Add a node Address to AddressList by Uri. Returns false if the address is already in the list.

Source

pub fn get_live_address(&self) -> Option<Address>

Select a not-banned address to send the next request to.

Not a pure getter: every call advances the shared rotation cursor and may promote or retire active-set members, steering traffic for all clones of this list.

Selection is sticky: requests rotate round-robin over a small active set of addresses (see AddressList::with_active_set_size) instead of sampling the whole list, so connections to those hosts stay warm. An active address that got banned, removed or evicted on failover (see AddressList::evict_from_rotation) is dropped from the set here and a random live standby address is promoted in its place. Each slot also expires after a jittered lifetime (5–7.5 minutes). Evicted and expired members are used to refill slots only after all live standbys have been selected, preserving availability when alternatives are scarce.

An address is considered live when it has never been banned or when its ban period has already expired.

Source

pub fn evict_from_rotation(&self, address: &Address)

Drop address from the sticky active set, leaving its ban state untouched; the next selection prefers a random live standby in its place, falling back to evicted members if there are too few standbys.

This is the failover path for callers that disable banning (RequestSettings::ban_failed_address): a failing node yields its slot’s traffic to an available standby even when it is never banned.

Source

pub fn get_live_addresses(&self) -> Vec<Address>

Get all not banned addresses.

Returns a vector of addresses that are not currently banned or whose ban period has expired. The returned addresses use the same filtering logic as Self::get_live_address, checking if the ban period has expired based on the current time.

§Examples

use rs_dapi_client::{AddressList, Address};

let mut list = AddressList::new();
list.add("http://127.0.0.1:3000".parse().unwrap());
list.add("http://127.0.0.1:3001".parse().unwrap());

// Get all non-banned addresses
let live_addresses = list.get_live_addresses();
assert_eq!(live_addresses.len(), 2);

Source

pub fn ban_info(&self) -> Vec<AddressBanInfo>

Get an owned snapshot of every address’ ban state.

Clones the current state into an owned Vec<AddressBanInfo> so it can be inspected without holding the internal lock. The banned flag reflects the currently effectively banned semantics used by AddressList::get_live_address: the address has been banned at least once (ban_count > 0) and its ban period has not yet expired (banned_until is in the future).

Source

pub fn len(&self) -> usize

Get number of all addresses, both banned and not banned.

Source

pub fn is_empty(&self) -> bool

Check if the list is empty. Returns true if there are no addresses in the list. Returns false if there is at least one address in the list. Banned addresses are also counted.