Struct zebra_network::meta_addr::MetaAddr

pub struct MetaAddr {
    pub(crate) addr: PeerSocketAddr,
    pub(crate) services: Option<PeerServices>,
    untrusted_last_seen: Option<DateTime32>,
    last_response: Option<DateTime32>,
    last_attempt: Option<Instant>,
    last_failure: Option<Instant>,
    pub(crate) last_connection_state: PeerAddrState,
}

An address with metadata on its advertised services and last-seen time.

This struct can be created from addr or addrv2 messages.

Bitcoin reference

Fields

addr: PeerSocketAddr

The peer’s canonical socket address.

services: Option<PeerServices>

The services advertised by the peer.

The exact meaning depends on last_connection_state:

• Responded: the services advertised by this peer, the last time we performed a handshake with it
• NeverAttempted: the unverified services advertised by another peer, then gossiped by the peer that sent us this address
• Failed or AttemptPending: unverified services via another peer, or services advertised in a previous handshake

Security

services from NeverAttempted peers may be invalid due to outdated records, older peer versions, or buggy or malicious peers.

untrusted_last_seen: Option<DateTime32>

The unverified “last seen time” gossiped by the remote peer that sent us this address.

See the MetaAddr::last_seen method for details.

last_response: Option<DateTime32>

The last time we received a message from this peer.

See the MetaAddr::last_seen method for details.

last_attempt: Option<Instant>

The last time we tried to open an outbound connection to this peer.

See the MetaAddr::last_attempt method for details.

last_failure: Option<Instant>

The last time our outbound connection with this peer failed.

See the MetaAddr::last_failure method for details.

last_connection_state: PeerAddrState

The outcome of our most recent communication attempt with this peer.

Implementations

impl MetaAddr

pub fn gossiped_strategy() -> BoxedStrategy<Self>

Create a strategy that generates MetaAddrs in the NeverAttemptedGossiped state.

impl MetaAddr

pub fn new_initial_peer(addr: PeerSocketAddr) -> MetaAddrChange

Returns a MetaAddrChange::NewInitial for a peer that was excluded from the list of the initial peers.

pub fn new_gossiped_meta_addr( addr: PeerSocketAddr, untrusted_services: PeerServices, untrusted_last_seen: DateTime32 ) -> MetaAddr

Returns a new MetaAddr, based on the deserialized fields from a gossiped peer Addr message.

pub fn new_gossiped_change(self) -> Option<MetaAddrChange>

Returns a MetaAddrChange::NewGossiped, based on a gossiped peer MetaAddr.

Returns None if the gossiped peer is missing the untrusted services field.

pub fn new_connected( addr: PeerSocketAddr, services: &PeerServices ) -> MetaAddrChange

Returns a MetaAddrChange::UpdateConnected for a peer that has just successfully connected.

Security

This address must be the remote address from an outbound connection, and the services must be the services from that peer’s handshake.

Otherwise:

• malicious peers could interfere with other peers’ AddressBook state, or
• Zebra could advertise unreachable addresses to its own peers.

pub fn new_responded(addr: PeerSocketAddr) -> MetaAddrChange

Returns a MetaAddrChange::UpdateResponded for a peer that has just sent us a message.

Security

This address must be the remote address from an outbound connection.

Otherwise:

• malicious peers could interfere with other peers’ AddressBook state, or
• Zebra could advertise unreachable addresses to its own peers.

pub fn new_reconnect(addr: PeerSocketAddr) -> MetaAddrChange

Returns a MetaAddrChange::UpdateAttempt for a peer that we want to make an outbound connection to.

pub fn new_local_listener_change( addr: impl Into<PeerSocketAddr> ) -> MetaAddrChange

Returns a MetaAddrChange::NewLocal for our own listener address.

pub fn new_errored( addr: PeerSocketAddr, services: impl Into<Option<PeerServices>> ) -> MetaAddrChange

Returns a MetaAddrChange::UpdateFailed for a peer that has just had an error.

pub fn new_shutdown(addr: PeerSocketAddr) -> MetaAddrChange

Create a new MetaAddr for a peer that has just shut down.

pub fn addr(&self) -> PeerSocketAddr

Return the address for this MetaAddr.

pub fn peer_preference(&self) -> Result<PeerPreference, &'static str>

Return the address preference level for this MetaAddr.

pub fn last_seen(&self) -> Option<DateTime32>

Returns the time of the last successful interaction with this peer.

Initially set to the unverified “last seen time” gossiped by the remote peer that sent us this address.

If the last_connection_state has ever been Responded, this field is set to the last time we processed a message from this peer.

Security

last_seen times from peers that have never Responded may be incorrect due to clock skew, or buggy or malicious peers.

pub(crate) fn untrusted_last_seen(&self) -> Option<DateTime32>

Returns the unverified “last seen time” gossiped by the remote peer that sent us this address.

See the MetaAddr::last_seen method for details.

pub(crate) fn last_response(&self) -> Option<DateTime32>

Returns the last time we received a message from this peer.

See the MetaAddr::last_seen method for details.

pub(crate) fn set_untrusted_last_seen( &mut self, untrusted_last_seen: DateTime32 )

Set the gossiped untrusted last seen time for this peer.

pub fn last_attempt(&self) -> Option<Instant>

Returns the time of our last outbound connection attempt with this peer.

If the last_connection_state has ever been AttemptPending, this field is set to the last time we started an outbound connection attempt with this peer.

pub fn last_failure(&self) -> Option<Instant>

Returns the time of our last failed outbound connection with this peer.

If the last_connection_state has ever been Failed, this field is set to the last time:

• a connection attempt failed, or
• an open connection encountered a fatal protocol error.

pub fn has_connection_recently_responded(&self, now: DateTime<Utc>) -> bool

Have we had any recently messages from this peer?

Returns true if the peer is likely connected and responsive in the peer set.

constants::MIN_PEER_RECONNECTION_DELAY represents the time interval in which we should receive at least one message from a peer, or close the connection. Therefore, if the last-seen timestamp is older than constants::MIN_PEER_RECONNECTION_DELAY ago, we know we should have disconnected from it. Otherwise, we could potentially be connected to it.

pub fn was_connection_recently_attempted(&self, now: Instant) -> bool

Have we recently attempted an outbound connection to this peer?

Returns true if this peer was recently attempted, or has a connection attempt in progress.

pub fn has_connection_recently_failed(&self, now: Instant) -> bool

Have we recently had a failed connection to this peer?

Returns true if this peer has recently failed.

pub fn was_recently_live(&self, now: DateTime<Utc>) -> bool

Returns true if this peer has recently sent us a message.

pub fn is_active_for_gossip(&self, now: DateTime<Utc>) -> bool

Has this peer been seen recently?

Returns true if this peer has responded recently or if the peer was gossiped with a recent reported last seen time.

constants::MAX_PEER_ACTIVE_FOR_GOSSIP represents the maximum time since a peer was seen to still be considered reachable.

pub fn was_recently_updated( &self, instant_now: Instant, chrono_now: DateTime<Utc> ) -> bool

Returns true if any messages were recently sent to or received from this address.

pub fn is_ready_for_connection_attempt( &self, instant_now: Instant, chrono_now: DateTime<Utc>, network: &Network ) -> bool

Is this address ready for a new outbound connection attempt?

pub fn address_is_valid_for_outbound(&self, network: &Network) -> bool

Is the PeerSocketAddr we have for this peer valid for outbound connections?

Since the addresses in the address book are unique, this check can be used to permanently reject entire MetaAddrs.

pub fn last_known_info_is_valid_for_outbound(&self, network: &Network) -> bool

Is the last known information for this peer valid for outbound connections?

The last known info might be outdated or untrusted, so this check can only be used to:

• reject NeverAttempted... MetaAddrChanges, and
• temporarily stop outbound connections to a MetaAddr.

pub fn is_probably_reachable(&self, now: DateTime<Utc>) -> bool

Should this peer considered reachable?

A peer is probably reachable if:

• it has never been attempted, or
• the last connection attempt was successful, or
• the last successful connection was less than 3 days ago.

Security

This is used by Self::is_ready_for_connection_attempt so that Zebra stops trying to connect to peers that are likely unreachable.

The untrusted_last_seen time is used as a fallback time if the local node has never itself seen the peer. If the reported last seen time is a long time ago or None, then the local node will attempt to connect the peer once, and if that attempt fails it won’t try to connect ever again. (The state can’t be Failed until after the first connection attempt.)

pub fn last_seen_is_recent(&self, now: DateTime<Utc>) -> bool

Was this peer last seen recently?

Returns true if this peer was last seen at most MAX_RECENT_PEER_AGE ago. Returns false if the peer is outdated, or it has no last seen time.

pub fn sanitize(&self, network: &Network) -> Option<MetaAddr>

Return a sanitized version of this MetaAddr, for sending to a remote peer.

Returns None if this MetaAddr should not be sent to remote peers.

Trait Implementations

impl Arbitrary for MetaAddr

type Parameters = (<Option<PeerServices> as Arbitrary>::Parameters, <Option<DateTime32> as Arbitrary>::Parameters, <Option<DateTime32> as Arbitrary>::Parameters, <Option<Instant> as Arbitrary>::Parameters, <Option<Instant> as Arbitrary>::Parameters, <PeerAddrState as Arbitrary>::Parameters)

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = Map<(BoxedStrategy<PeerSocketAddr>, <Option<PeerServices> as Arbitrary>::Strategy, <Option<DateTime32> as Arbitrary>::Strategy, <Option<DateTime32> as Arbitrary>::Strategy, <Option<Instant> as Arbitrary>::Strategy, <Option<Instant> as Arbitrary>::Strategy, <PeerAddrState as Arbitrary>::Strategy), fn(_: (PeerSocketAddr, Option<PeerServices>, Option<DateTime32>, Option<DateTime32>, Option<Instant>, Option<Instant>, PeerAddrState)) -> MetaAddr>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_top: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

impl Clone for MetaAddr

fn clone(&self) -> MetaAddr

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MetaAddr

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

Formats the value using the given formatter.

impl From<AddrV1> for MetaAddr

fn from(addr: AddrV1) -> Self

Converts to this type from the input type.

impl From<MetaAddr> for AddrV1

fn from(meta_addr: MetaAddr) -> Self

Converts to this type from the input type.

impl Ord for MetaAddr

fn cmp(&self, other: &Self) -> Ordering

MetaAddrs are sorted in approximate reconnection attempt order, but with Responded peers sorted first as a group.

But this order should not be used for reconnection attempts: use reconnection_peers instead.

See CandidateSet for more details.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for MetaAddr

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for MetaAddr

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<AddrV2> for MetaAddr

type Error = UnsupportedAddrV2NetworkIdError

The type returned in the event of a conversion error.

fn try_from(addr: AddrV2) -> Result<MetaAddr, UnsupportedAddrV2NetworkIdError>

Performs the conversion.

impl Copy for MetaAddr

impl Eq for MetaAddr