Struct Options

pub struct Options {

    pub tags: Arc<ArcSwap<Tags>>,
    pub protocol_version: ProtocolVersion,
    pub delegate_version: DelegateVersion,
    pub broadcast_timeout: Duration,
    pub leave_propagate_delay: Duration,
    pub coalesce_period: Duration,
    pub quiescent_period: Duration,
    pub user_coalesce_period: Duration,
    pub user_quiescent_period: Duration,
    pub reap_interval: Duration,
    pub reconnect_interval: Duration,
    pub reconnect_timeout: Duration,
    pub tombstone_timeout: Duration,
    pub flap_timeout: Duration,
    pub queue_check_interval: Duration,
    pub queue_depth_warning: usize,
    pub max_queue_depth: usize,
    pub min_queue_depth: usize,
    pub recent_intent_timeout: Duration,
    pub event_buffer_size: usize,
    pub query_buffer_size: usize,
    pub query_timeout_mult: usize,
    pub query_response_size_limit: usize,
    pub query_size_limit: usize,
    pub memberlist_options: MemberlistOptions,
    pub snapshot_path: Option<PathBuf>,
    pub rejoin_after_leave: bool,
    pub enable_id_conflict_resolution: bool,
    pub disable_coordinates: bool,
    pub keyring_file: Option<PathBuf>,
    pub max_user_event_size: usize,
}

The configuration for creating a Serf instance.

Fields

tags: Arc<ArcSwap<Tags>>

The tags for this role, if any. This is used to provide arbitrary key/value metadata per-node. For example, a “role” tag may be used to differentiate “load-balancer” from a “web” role as parts of the same cluster. Tags are deprecating ‘Role’, and instead it acts as a special key in this map.

protocol_version: ProtocolVersion

The protocol version to speak

delegate_version: DelegateVersion

The delegate version to speak

broadcast_timeout: Duration

The amount of time to wait for a broadcast message to be sent to the cluster. Broadcast messages are used for things like leave messages and force remove messages. If this is not set, a timeout of 5 seconds will be set.

leave_propagate_delay: Duration

For our leave (node dead) message to propagate through the cluster. In particular, we want to stay up long enough to service any probes from other nodes before they learn about us leaving and stop probing. Otherwise, we risk getting node failures as we leave.

coalesce_period: Duration

The settings below relate to Serf’s event coalescence feature. Serf is able to coalesce multiple events into single events in order to reduce the amount of noise that is sent along the event channel. For example if five nodes quickly join, the event channel will be sent one EventMemberJoin containing the five nodes rather than five individual EventMemberJoin events. Coalescence can mitigate potential flapping behavior.

Coalescence is disabled by default and can be enabled by setting coalesce_period.

coalesce_period specifies the time duration to coalesce events. For example, if this is set to 5 seconds, then all events received within 5 seconds that can be coalesced will be.

quiescent_period: Duration

specifies the duration of time where if no events are received, coalescence immediately happens. For example, if coalesce_period is set to 10 seconds but quiescent_period is set to 2 seconds, then the events will be coalesced and dispatched if no new events are received within 2 seconds of the last event. Otherwise, every event will always be delayed by at least 10 seconds.

user_coalesce_period: Duration

The settings below relate to Serf’s user event coalescing feature. The settings operate like above but only affect user messages and not the Member* messages that Serf generates.

user_quiescent_period: Duration

The settings below relate to Serf’s user event coalescing feature. The settings operate like above but only affect user messages and not the Member* messages that Serf generates.

reap_interval: Duration

The interval when the reaper runs. If this is not set (it is zero), it will be set to a reasonable default.

reconnect_interval: Duration

The interval when we attempt to reconnect to failed nodes. If this is not set (it is zero), it will be set to a reasonable default.

reconnect_timeout: Duration

The amount of time to attempt to reconnect to a failed node before giving up and considering it completely gone.

tombstone_timeout: Duration

The amount of time to keep around nodes that gracefully left as tombstones for syncing state with other Serf nodes.

flap_timeout: Duration

The amount of time less than which we consider a node being failed and rejoining looks like a flap for telemetry purposes. This should be set less than a typical reboot time, but large enough to see actual events, given our expected detection times for a failed node.

queue_check_interval: Duration

The interval at which we check the message queue to apply the warning and max depth.

queue_depth_warning: usize

Used to generate warning message if the number of queued messages to broadcast exceeds this number. This is to provide the user feedback if events are being triggered faster than they can be disseminated

max_queue_depth: usize

Used to start dropping messages if the number of queued messages to broadcast exceeds this number. This is to prevent an unbounded growth of memory utilization

min_queue_depth: usize

if >0 will enforce a lower limit for dropping messages and then the max will be max(MinQueueDepth, 2*SizeOfCluster). This defaults to 0 which disables this dynamic sizing feature. If this is

0 then max_queue_depth will be ignored.

recent_intent_timeout: Duration

Used to determine how long we store recent join and leave intents. This is used to guard against the case where Serf broadcasts an intent that arrives before the Memberlist event. It is important that this not be too short to avoid continuous rebroadcasting of dead events.

event_buffer_size: usize

Used to control how many events are buffered. This is used to prevent re-delivery of events to a client. The buffer must be large enough to handle all “recent” events, since Serf will not deliver messages that are older than the oldest entry in the buffer. Thus if a client is generating too many events, it’s possible that the buffer gets overrun and messages are not delivered.

query_buffer_size: usize

used to control how many queries are buffered. This is used to prevent re-delivery of queries to a client. The buffer must be large enough to handle all “recent” events, since Serf will not deliver queries older than the oldest entry in the buffer. Thus if a client is generating too many queries, it’s possible that the buffer gets overrun and messages are not delivered.

query_timeout_mult: usize

Configures the default timeout multipler for a query to run if no specific value is provided. Queries are real-time by nature, where the reply is time sensitive. As a result, results are collected in an async fashion, however the query must have a bounded duration. We want the timeout to be long enough that all nodes have time to receive the message, run a handler, and generate a reply. Once the timeout is exceeded, any further replies are ignored. The default value is

timeout = gossip_interval * query_timeout_mult * log(N+1)

query_response_size_limit: usize

Limit the outbound payload sizes for queries, respectively. These must fit in a UDP packet with some additional overhead, so tuning these past the default values of 1024 will depend on your network configuration.

query_size_limit: usize

Limit the inbound payload sizes for queries, respectively. These must fit in a UDP packet with some additional overhead, so tuning these past the default values of 1024 will depend on your network configuration.

memberlist_options: MemberlistOptions

The memberlist configuration that Serf will use to do the underlying membership management and gossip.

snapshot_path: Option<PathBuf>

If provided is used to snapshot live nodes as well as lamport clock values. When Serf is started with a snapshot, it will attempt to join all the previously known nodes until one succeeds and will also avoid replaying old user events.

rejoin_after_leave: bool

Controls our interaction with the snapshot file. When set to false (default), a leave causes a Serf to not rejoin the cluster until an explicit join is received. If this is set to true, we ignore the leave, and rejoin the cluster on start.

enable_id_conflict_resolution: bool

Controls if Serf will actively attempt to resolve a name conflict. Since each Serf member must have a unique name, a cluster can run into issues if multiple nodes claim the same name. Without automatic resolution, Serf merely logs some warnings, but otherwise does not take any action. Automatic resolution detects the conflict and issues a special query which asks the cluster for the Name -> IP:Port mapping. If there is a simple majority of votes, that node stays while the other node will leave the cluster and exit.

disable_coordinates: bool

Controls if Serf will maintain an estimate of this node’s network coordinate internally. A network coordinate is useful for estimating the network distance (i.e. round trip time) between two nodes. Enabling this option adds some overhead to ping messages.

keyring_file: Option<PathBuf>

Provides the location of a writable file where Serf can persist changes to the encryption keyring.

max_user_event_size: usize

Maximum byte size limit of user event name + payload in bytes. It’s optimal to be relatively small, since it’s going to be gossiped through the cluster.

Implementations

impl Options

pub fn tags(&self) -> Arc<Tags>

Returns the tags for this role, if any. This is used to provide arbitrary key/value metadata per-node. For example, a “role” tag may be used to differentiate “load-balancer” from a “web” role as parts of the same cluster.

pub const fn protocol_version(&self) -> ProtocolVersion

Returns the protocol version to speak

pub const fn delegate_version(&self) -> DelegateVersion

Returns the delegate version to speak

pub const fn broadcast_timeout(&self) -> Duration

Returns the amount of time to wait for a broadcast message to be sent to the cluster.

pub const fn leave_propagate_delay(&self) -> Duration

Returns the leave propagate delay.

pub const fn coalesce_period(&self) -> Duration

Returns the coalesce period.

pub const fn quiescent_period(&self) -> Duration

Returns the specifies the duration of time where if no events are received, coalescence immediately happens.

pub const fn user_coalesce_period(&self) -> Duration

Returns the user event coalesce period.

pub const fn user_quiescent_period(&self) -> Duration

Returns the user quiescent period.

pub const fn reap_interval(&self) -> Duration

Returns the interval when the reaper runs.

pub const fn reconnect_interval(&self) -> Duration

Returns the interval when we attempt to reconnect to failed nodes.

pub const fn reconnect_timeout(&self) -> Duration

Returns the amount of time to attempt to reconnect to a failed node before giving up and considering it completely gone.

pub const fn tombstone_timeout(&self) -> Duration

Returns the amount of time to keep around nodes that gracefully left as tombstones for syncing state with other Serf nodes.

pub const fn flap_timeout(&self) -> Duration

Returns the amount of time less than which we consider a node being failed and rejoining looks like a flap for telemetry purposes.

pub const fn queue_check_interval(&self) -> Duration

Returns the interval at which we check the message queue to apply the warning and max depth.

pub const fn queue_depth_warning(&self) -> usize

Returns the queue depth warning.

pub const fn max_queue_depth(&self) -> usize

Returns the max queue depth.

pub const fn min_queue_depth(&self) -> usize

Returns if >0 will enforce a lower limit for dropping messages and then the max will be max(min_queue_depth, 2 * size_of_cluster). This defaults to 0 which disables this dynamic sizing feature. If this is >0 then max_queue_depth will be ignored.

pub const fn recent_intent_timeout(&self) -> Duration

Returns how long we store recent join and leave intents.

pub const fn event_buffer_size(&self) -> usize

Returns how many events are buffered.

pub const fn query_buffer_size(&self) -> usize

Returns how many queries are buffered.

pub const fn query_timeout_mult(&self) -> usize

Returns the default timeout multipler for a query to run if no specific value is provided.

pub const fn query_response_size_limit(&self) -> usize

Returns the limit of the outbound payload sizes for queries.

pub const fn query_size_limit(&self) -> usize

Returns the limit of the inbound payload sizes for queries.

pub const fn memberlist_options(&self) -> &MemberlistOptions

Returns the memberlist configuration that Serf will use to do the underlying membership management and gossip.

pub const fn snapshot_path(&self) -> Option<&PathBuf>

Returns the path to the snapshot file.

pub const fn rejoin_after_leave(&self) -> bool

Returns if Serf will rejoin the cluster after a leave.

pub const fn enable_id_conflict_resolution(&self) -> bool

Returns if Serf will attempt to resolve a name conflict.

pub const fn disable_coordinates(&self) -> bool

Returns if Serf will maintain an estimate of this node’s network coordinate internally.

pub const fn keyring_file(&self) -> Option<&PathBuf>

Returns the location of a writable file where Serf can persist changes to the encryption keyring.

pub const fn max_user_event_size(&self) -> usize

Returns the maximum byte size limit of user event name + payload in bytes.

pub fn with_protocol_version(self, val: ProtocolVersion) -> Self

Sets the protocol version to speak

pub fn with_delegate_version(self, val: DelegateVersion) -> Self

Sets the delegate version to speak

pub fn with_broadcast_timeout(self, val: Duration) -> Self

Sets the amount of time to wait for a broadcast message to be sent to the cluster.

pub fn with_leave_propagate_delay(self, val: Duration) -> Self

Sets the leave propagate delay.

pub fn with_coalesce_period(self, val: Duration) -> Self

Sets the coalesce period.

pub fn with_quiescent_period(self, val: Duration) -> Self

Sets specifies the duration of time where if no events are received, coalescence immediately happens.

pub fn with_user_coalesce_period(self, val: Duration) -> Self

Sets the user event coalesce period.

pub fn with_user_quiescent_period(self, val: Duration) -> Self

Sets the user quiescent period.

pub fn with_reap_interval(self, val: Duration) -> Self

Sets the interval when the reaper runs.

pub fn with_reconnect_interval(self, val: Duration) -> Self

Sets the interval when we attempt to reconnect to failed nodes.

pub fn with_reconnect_timeout(self, val: Duration) -> Self

Sets the amount of time to attempt to reconnect to a failed node before giving up and considering it completely gone.

pub fn with_tombstone_timeout(self, val: Duration) -> Self

Sets the amount of time to keep around nodes that gracefully left as tombstones for syncing state with other Serf nodes.

pub fn with_flap_timeout(self, val: Duration) -> Self

Sets the amount of time less than which we consider a node being failed and rejoining looks like a flap for telemetry purposes.

pub fn with_queue_check_interval(self, val: Duration) -> Self

Sets the interval at which we check the message queue to apply the warning and max depth.

pub fn with_queue_depth_warning(self, val: usize) -> Self

Sets the queue depth warning.

pub fn with_max_queue_depth(self, val: usize) -> Self

Sets the max queue depth.

pub fn with_min_queue_depth(self, val: usize) -> Self

Sets if >0 will enforce a lower limit for dropping messages and then the max will be max(min_queue_depth, 2 * size_of_cluster). This defaults to 0 which disables this dynamic sizing feature. If this is >0 then max_queue_depth will be ignored.

pub fn with_recent_intent_timeout(self, val: Duration) -> Self

Sets how long we store recent join and leave intents.

pub fn with_event_buffer_size(self, val: usize) -> Self

Sets how many events are buffered.

pub fn with_query_buffer_size(self, val: usize) -> Self

Sets how many queries are buffered.

pub fn with_query_timeout_mult(self, val: usize) -> Self

Sets the default timeout multipler for a query to run if no specific value is provided.

pub fn with_query_response_size_limit(self, val: usize) -> Self

Sets the limit of the outbound payload sizes for queries.

pub fn with_query_size_limit(self, val: usize) -> Self

Sets the limit of the inbound payload sizes for queries.

pub fn with_memberlist_options(self, val: MemberlistOptions) -> Self

Sets the memberlist configuration that Serf will use to do the underlying membership management and gossip.

pub fn with_snapshot_path(self, val: Option<PathBuf>) -> Self

Sets the path to the snapshot file.

pub fn with_rejoin_after_leave(self, val: bool) -> Self

Sets if Serf will rejoin the cluster after a leave.

pub fn with_enable_id_conflict_resolution(self, val: bool) -> Self

Sets if Serf will attempt to resolve a name conflict.

pub fn with_disable_coordinates(self, val: bool) -> Self

Sets if Serf will maintain an estimate of this node’s network coordinate internally.

pub fn with_keyring_file(self, val: Option<PathBuf>) -> Self

Sets the location of a writable file where Serf can persist changes to the encryption keyring.

pub fn with_max_user_event_size(self, val: usize) -> Self

Sets the maximum byte size limit of user event name + payload in bytes.

impl Options

pub fn new() -> Self

Returns a new instance of Options with default configurations.

pub fn with_tags<K: Into<SmolStr>, V: Into<SmolStr>>( self, tags: impl Iterator<Item = (K, V)>, ) -> Self

Sets the tags for this node.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Options

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Options

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

where __S: Serializer,

Serialize this value into the given Serde serializer.