Struct foca::Config

pub struct Config {
    pub probe_period: Duration,
    pub probe_rtt: Duration,
    pub num_indirect_probes: NonZeroUsize,
    pub max_transmissions: NonZeroU8,
    pub suspect_to_down_after: Duration,
    pub remove_down_after: Duration,
    pub max_packet_size: NonZeroUsize,
    pub notify_down_members: bool,
    pub periodic_announce: Option<PeriodicParams>,
    pub periodic_announce_to_down_members: Option<PeriodicParams>,
    pub periodic_gossip: Option<PeriodicParams>,
}

A Config specifies the parameters Foca will use for the SWIM protocol.

Fields

probe_period: Duration

Specifies how often a random member will be probed for activity.

At the end of this period, if the member didn’t reply (directly or indirectly, see crate::Message) it’s declared crate::State::Suspect.

Should be strictly larger than Self::probe_rtt. Preferably more than twice its value since we need to wait for the indirect ping cycle. If unsure, err on the safe side with probe_rtt * 3 and tune later.

Must not be zero.

probe_rtt: Duration

How long to wait for a direct reply to a probe before starting the indirect probing cycle.

It should be set to a value that describes well your transport round-trip time. A reasonable value would be a high quantile (p99, for example) of your cluster-wide ICMP PING RTT.

Must be strictly smaller than Self::probe_period.

Must not be zero.

num_indirect_probes: NonZeroUsize

How many members will be asked to perform an indirect ping in case the probed member takes too long to reply.

This doesn’t need to be a large number: we’re essentially fanning out to ensure a message actually reaches the original ping target in case of poor transmission quality or weird partitions.

Setting this to 3-5 should be more than enough for a “modern” network.

max_transmissions: NonZeroU8

Specifies how many times a single update/broadcast will be sent along with a normal message.

A high value trades off bandwidth for higher chances of fully disseminating broadcasts throughout the cluster.

Reasonable values range from 5, for small clusters to 15 for very large clusters.

suspect_to_down_after: Duration

How long a Suspect member is considered active before being declared Down.

Here you want to give time for the member to realize it has been declared Suspect and notify the cluster that its actually active.

Higher values give more time for a member to recover from a false suspicion, but slows down detection of a failed state.

Very application-dependent. Smaller clusters likely want this value to be a small multiplier of Self::probe_period whereas large clusters can easily tolerate several seconds of wait.

Must not be zero.

remove_down_after: Duration

Governs how long Foca will remember an identity as being Down.

It’s recommended to have very high values here, in the order of hours or longer.

Identities that opt-in on auto-rejoining don’t need to worry about this value being high: this setting only prevents nodes using the exact same identity from joining the cluster.

If you choose to use a small duration here (maybe you can’t enable auto-rejoin, maybe you’d like to reduce the (small) increase in memory usage that a high value here may lead to), keep a close eye on crate::Foca::updates_backlog: large numbers higher than the number of nodes in the cluster are a strong sign that this configuration should be set to a higher value.

See crate::Identity::renew.

max_packet_size: NonZeroUsize

The maximum packet size Foca will produce AND consume.

This is transport-dependent. The main goal is reducing fragmentation and congestion.

If using UDP as a transport, use rfc8085 guidelines and stick to a value smaller than your network’s MTU. 1400 is a good value for a in a non-ancient network.

notify_down_members: bool

Wether foca should try to let members that are down know about it

Whenever a member is declared down by the cluster, their messages get ignored and there’s no way for them to learn that this is happening. With this setting enabled, will try to notify the down member that their messages are being discarded.

This feature is an extension to the SWIM protocol and should be left disabled if you’re aiming at pure SWIM behavior.

periodic_announce: Option<PeriodicParams>

How often should foca ask its peers for more peers

crate::Message::Announce is the mechanism foca uses to discover members. After joining a sizeable cluster, it may take a while until foca discovers every active member. Periodically announcing helps speed up this process.

This setting is helpful for any cluster size, but smaller ones can get by without it if discovering the full active roster quickly is not a requirement.

As a rule of thumb, use large values for frequency (say, every 30s, every minute, etc) and small values for num_members: just one might be good enough for many clusters.

Whilst you can change the parameters at runtime, foca prevents you from changing it from None to Some to simplify reasoning. It’s required to recreate your foca instance in these cases.

This feature is an extension to the SWIM protocol and should be left disabled if you’re aiming at pure SWIM behavior.

periodic_announce_to_down_members: Option<PeriodicParams>

How often should foca send an announce message to members it currently considers crate::State::Down

This setting instructs foca to try and talk to members that are down so that it can (eventually) recover from network partitions without additional hand-holding.

It’s particularly useful when used in tandem with identities that can auto-rejoin (crate::Identity::renew) and with Self::notify_down_members enabled.

This feature is an extension to the SWIM protocol and should be left disabled if you’re aiming at pure SWIM behavior.

periodic_gossip: Option<PeriodicParams>

How often should foca send cluster updates to peers

By default, SWIM disseminates cluster updates during the direct and indirect probe cycle (See crate::Message). This setting instructs foca to also propagate updates periodically.

Periodically gossiping influences the speed in which the cluster learns new information, but gossiping too much is often unnecessary since cluster changes are not (normally) high-rate events.

A LAN cluster can afford high frequency gossiping (every 200ms, for example) without much worry; A WAN cluster might have better results gossiping less often (500ms) but to more members at once.

Whilst you can change the parameters at runtime, foca prevents you from changing it from None to Some to simplify reasoning. It’s required to recreate your foca instance in these cases.

This feature is an extension to the SWIM protocol and should be left disabled if you’re aiming at pure SWIM behavior.

Implementations

impl Config

pub fn simple() -> Self

A simple configuration that should work well in a LAN scenario.

This is Foca in its simplest form and has no extensions enabled. Use this config if you are trying to get a grasp of how SWIM works, without any additional behavior.

impl Config

pub fn new_lan(cluster_size: NonZeroU32) -> Self

Generate a configuration for a LAN cluster given an expected total number of active members.

The cluster_size parameter is used to define how many times updates are disseminated (Config::max_transmissions) and how long Foca will wait before declaring a suspected member as down (Config::suspect_to_down_after).

Settings derived from memberlist’s DefaultLanConfig.

pub fn new_wan(cluster_size: NonZeroU32) -> Self

Generate a configuration for a WAN cluster given an expected total number of active members.

Settings derived from memberlist’s DefaultWanConfig.

See Config::new_lan.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Config

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Config

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

where __S: Serializer,

Serialize this value into the given Serde serializer.