configuration.rs

Overview

This file defines the configuration structures and types necessary for initializing and customizing a Chitchat instance, which is a gossip-based membership and failure detection protocol implementation. The configuration encapsulates parameters such as cluster identity, network settings, gossip intervals, seed nodes, failure detection tuning, and user-defined callbacks. It enables fine-grained control over the behavior of the Chitchat protocol, particularly around node liveness determination and key deletion handling.

Types and Structures

CatchupCallback

pub type CatchupCallback = Box<dyn Fn() + Send>;

• Description: Represents an optional user-defined callback function that is executed when the local node detects that it is lagging behind other nodes in the cluster.

• Usage: Typically, this callback can be used to trigger catch-up logic or alerting mechanisms to handle state synchronization delays.

• Parameters: None.

• Return Value: None.

ExtraLivenessPredicate

pub type ExtraLivenessPredicate = Box<dyn Fn(&NodeState) -> bool + Send>;

• Description: An optional user-defined predicate function that applies additional logic on top of the failure detector's output to determine if a node is considered live.

• Usage: This can be used to refine liveness checks, for example, by requiring that a node holds certain keys or satisfies specific application-level conditions to be considered alive.

• Parameters:

  • &NodeState: Reference to the current state of a node.

• Return Value: bool indicating whether the node meets the extra liveness criteria.

ChitchatConfig

pub struct ChitchatConfig {
    pub chitchat_id: ChitchatId,
    pub cluster_id: String,
    pub gossip_interval: Duration,
    pub listen_addr: SocketAddr,
    pub seed_nodes: Vec<String>,
    pub failure_detector_config: FailureDetectorConfig,
    pub marked_for_deletion_grace_period: Duration,
    pub catchup_callback: Option<CatchupCallback>,
    pub extra_liveness_predicate: Option<ExtraLivenessPredicate>,
}

• Description: Main configuration struct for setting up a Chitchat instance.

• Fields:

  • chitchat_id: Unique identifier for the local node within the cluster, encapsulated by the ChitchatId type.

  • cluster_id: String identifier for the cluster group this node belongs to, used for logical grouping.

  • gossip_interval: Duration specifying how frequently gossip messages are sent.

  • listen_addr: Network address (SocketAddr) where the node listens for incoming gossip connections.

  • seed_nodes: List of seed node addresses (as String) used for initial contact during cluster join.

  • failure_detector_config: Configuration parameters for the failure detector component, encapsulated in FailureDetectorConfig.

  • marked_for_deletion_grace_period: Duration representing the grace period (in number of heartbeats) before keys marked for deletion are permanently removed.

  • catchup_callback: Optional CatchupCallback executed when the node is lagging.

  • extra_liveness_predicate: Optional ExtraLivenessPredicate to impose additional liveness criteria.

• Important Implementation Details:

  • The marked_for_deletion_grace_period supports three key mechanisms to ensure eventual deletion of marked keys:

    1. Garbage Collection: Periodically deletes keys whose deletion grace period elapsed.

    2. Delta Computation: Flags nodes for reset if their heartbeat is sufficiently behind, triggering full state synchronization.

    3. Delta Application: Removes and resets node state for flagged nodes to reconcile state.

Methods

for_test(port: u16) -> Self

pub fn for_test(port: u16) -> Self

• Description: Creates a preconfigured ChitchatConfig instance optimized for testing purposes.

• Parameters:

  • port: The port number to use for the local node's gossip address.

• Returns: A ChitchatConfig instance with:

  • cluster_id set to "default-cluster".

  • gossip_interval set to 50 milliseconds.

  • Empty seed nodes list.

  • marked_for_deletion_grace_period set to 10,000 seconds.

  • failure_detector_config initialized to default.

  • No catchup or extra liveness callbacks.

• Usage Example:

  let test_config = ChitchatConfig::for_test(8080);
  

Default Implementation (for tests)

impl Default for ChitchatConfig

• Provides default values for test configurations.

• Sets gossip_interval to 1,000 milliseconds.

• Sets marked_for_deletion_grace_period to 2 hours (7,200 seconds).

• Uses port 10,000 for the ChitchatId.

• Other defaults align with for_test.

Interactions with Other Components

• ChitchatId: Used to uniquely identify the local node and determine its gossip advertise address.

• FailureDetectorConfig: Configures parameters for the failure detector, which is critical for node liveness detection and failure handling within the gossip protocol.

• NodeState: The extra liveness predicate uses this to apply additional logic on node status.

• The configuration influences how the gossip protocol manages membership, failure detection, state synchronization, and key deletion.

Important Algorithms and Mechanisms

• Marked-for-Deletion Grace Period: Enforces eventual consistency and cleanup for keys marked for deletion using a combination of garbage collection, delta computation, and delta application.

• Failure Detection and Liveness: The configuration supports an extensible liveness model by allowing injection of additional predicates on top of the core failure detector output.

• Catchup Handling: Provides hooks for handling cases where the local node falls behind others, enabling custom recovery or notification strategies.

Diagram: Structure of ChitchatConfig

classDiagram
class ChitchatConfig {
+ChitchatId chitchat_id
+String cluster_id
+Duration gossip_interval
+SocketAddr listen_addr
+Vec<String> seed_nodes
+FailureDetectorConfig failure_detector_config
+Duration marked_for_deletion_grace_period
+Option<CatchupCallback> catchup_callback
+Option<ExtraLivenessPredicate> extra_liveness_predicate
+for_test(port: u16) ChitchatConfig
}
class CatchupCallback {
<<type>>
+Fn() + Send
}
class ExtraLivenessPredicate {
<<type>>
+Fn(&NodeState) -> bool + Send
}
ChitchatConfig "1" --> "0..1" CatchupCallback : catchup_callback
ChitchatConfig "1" --> "0..1" ExtraLivenessPredicate : extra_liveness_predicate
ChitchatConfig --> ChitchatId : chitchat_id
ChitchatConfig --> FailureDetectorConfig : failure_detector_config

This diagram illustrates the main ChitchatConfig struct, its fields, and its relationships to the callback types and other configuration components. The optional callbacks are represented as zero-or-one associations.