lib.rs

Overview

This file implements a gossip-based cluster membership and state synchronization service using the chitchat crate. It provides:

• Configuration and initialization of a gossip protocol node.

• REST API endpoints to query cluster state and set key-value pairs on the node.

• Spawning and running both the gossip protocol service and the REST server concurrently.

The core functionality revolves around maintaining and exposing the cluster state via the Chitchat protocol, which enables nodes to gossip their state to each other. This file bridges the Chitchat cluster with a RESTful API for external interaction.

Structs and Types

ApiResponse

pub struct ApiResponse {
    pub cluster_id: String,
    pub cluster_state: ClusterStateSnapshot,
    pub live_nodes: Vec<ChitchatId>,
    pub dead_nodes: Vec<ChitchatId>,
}

• Represents the response returned by the API root endpoint (GET /).

• Fields:

  • cluster_id: Identifier of the cluster.

  • cluster_state: Snapshot of the current cluster state.

  • live_nodes: List of currently live nodes in the cluster.

  • dead_nodes: List of nodes considered dead.

SetKeyValueResponse

pub struct SetKeyValueResponse {
    pub status: bool,
}

• Represents the response to setting a key-value pair on the node (GET /set_kv/).

• Fields:

  • status: Boolean indicating success of the operation.

Api

struct Api {
    chitchat: ChitchatRef,
}

• REST API implementation using the poem_openapi crate.

• Holds a reference to the Chitchat cluster state (ChitchatRef).

GossipConfig

pub struct GossipConfig {
    pub listen_addr: SocketAddr,
    pub advertise_addr: Option<SocketAddr>,
    pub seeds: Vec<SocketAddr>,
    pub cluster_id: String,
}

• Configuration struct for the gossip protocol node.

• Fields:

  • listen_addr: UDP socket address to listen for gossip messages. Defaults to 127.0.0.1:10000.

  • advertise_addr: Optional socket address advertised to other nodes. Defaults to listen_addr if not specified.

  • seeds: List of seed node addresses to bootstrap gossip.

  • cluster_id: Identifier for the gossip cluster.

• Implements Default which sets default values for these fields.

Functions and Methods

Api::index

async fn index(&self) -> Json<serde_json::Value>

• Endpoint: GET /

• Retrieves the current cluster state and returns it as JSON.

• Returns: JSON serialized ApiResponse.

• Behavior:

  • Locks the Chitchat instance.

  • Extracts cluster ID, cluster state snapshot, live nodes, and dead nodes.

  • Serializes and returns these as JSON.

Usage example:

Request:

GET http://<node_address>/

Response:

{
  "cluster_id": "acki_nacki",
  "cluster_state": { /* snapshot data */ },
  "live_nodes": ["server:127.0.0.1:10000-xyz"],
  "dead_nodes": []
}

Api::set_kv

async fn set_kv(&self, key: Query<String>, value: Query<String>) -> Json<serde_json::Value>

• Endpoint: GET /set_kv/?key=KEY&value=VALUE

• Sets a key-value pair on the local node's state without validation.

• Parameters:

  • key: Query parameter specifying the key to set.

  • value: Query parameter specifying the value to associate.

• Returns: JSON serialized SetKeyValueResponse indicating success.

Usage example:

Request:

GET http://<node_address>/set_kv/?key=foo&value=bar

Response:

{
  "status": true
}

generate_server_id

fn generate_server_id(public_addr: SocketAddr) -> String

• Generates a unique server ID string combining the public socket address and a medium-sized random ID from cool_id_generator.

• Parameters:

  • public_addr: Socket address advertised by the node.

• Returns: A string in format "server:<public_addr>-<random_id>".

GossipConfig::advertise_addr

pub fn advertise_addr(&self) -> SocketAddr

• Returns the advertise address of the node.

• If advertise_addr is not explicitly set, returns listen_addr.

default_gossip_listen_addr

fn default_gossip_listen_addr() -> SocketAddr

• Returns the default socket address 127.0.0.1:10000 used for gossip listening.

default_chitchat_cluster_id

fn default_chitchat_cluster_id() -> String

• Returns the default cluster ID string "acki_nacki" used for Chitchat gossip clusters.

run

pub async fn run(
    _shutdown_rx: tokio::sync::watch::Receiver<bool>,
    config_rx: tokio::sync::watch::Receiver<GossipConfig>,
    transport: impl chitchat::transport::Transport,
) -> anyhow::Result<(ChitchatHandle, JoinHandle<anyhow::Result<()>>)>

• Main entrypoint to start the gossip node and REST API server.

• Parameters:

  • _shutdown_rx: Receiver to listen for shutdown signals (currently unused).

  • config_rx: Receiver for GossipConfig updates.

  • transport: Transport implementation used by Chitchat for gossip communication.

• Returns: Tuple containing:

  • ChitchatHandle to interact with the running Chitchat instance.

  • Tokio JoinHandle for the spawned REST API server task.

• Detailed Behavior:

  1. Clones the latest gossip configuration.

  2. Generates a unique node ID and Chitchat ID using current system time.

  3. Builds a ChitchatConfig with parameters such as cluster ID, gossip interval, listen address, seed nodes, and failure detector settings.

  4. Spawns the Chitchat gossip service using spawn_chitchat.

  5. Sets up REST API routes using the Api struct and OpenApiService.

  6. Launches an HTTP server listening on the configured listen address.

  7. Returns handles for both the Chitchat service and REST server.

• This function enables the node to participate in cluster gossip and expose its state externally.

Implementation Details and Algorithms

• Gossip Protocol: Uses the chitchat crate to implement a UDP-based gossip protocol for cluster membership and state propagation. The node periodically gossips its state and failure detector data to other nodes.

• Node Identification: Each node generates a unique ID combining its advertised socket address and a random medium-sized ID generated from cool_id_generator.

• Failure Detection: A default FailureDetectorConfig is used to monitor node availability based on gossip messages.

• REST API: Built using poem and poem_openapi crates. It exposes:

  • Current cluster state via / endpoint.

  • Key-value state modifications via /set_kv/ endpoint.

• Concurrency: Uses Tokio async runtime to run the gossip protocol and REST server concurrently.

Interaction with Other System Components

• chitchat crate: Provides core gossip protocol functionality and cluster state management.

• cool_id_generator: Generates unique node IDs.

• poem and poem_openapi: Build and serve the REST API for cluster interaction.

• Transport Layer: Abstracted via the transport parameter, allowing pluggable network transports for gossip messages.

• Tokio Runtime: Manages asynchronous tasks for the gossip protocol and HTTP server.

Together, these dependencies enable this module to serve as a networked cluster membership service with a RESTful interface.

Visual Diagram

flowchart TD
Run["run()"]
Run --> Config["Load GossipConfig"]
Run --> GenID["Generate ChitchatId"]
Run --> ChitchatConfig["Build ChitchatConfig"]
Run --> SpawnChitchat["spawn_chitchat()"]
SpawnChitchat --> ChitchatHandle["ChitchatHandle"]
ChitchatHandle --> Api["Api Struct (holds ChitchatRef)"]
Api --> OpenApiService["OpenApiService"]
OpenApiService --> RESTServer["REST Server (poem)"]
RESTServer --> TcpListener["TcpListener binds listen_addr"]
RESTServer --> ServeEndpoints["Serve / and /set_kv endpoints"]
subgraph REST API Endpoints
ServeEndpoints --> Index["GET / (index)"]
ServeEndpoints --> SetKV["GET /set_kv/ (set_kv)"]
end

• This flowchart illustrates the initialization and runtime components.

• run() function is the main orchestration point creating configuration, spawning gossip and REST servers.

• The Api struct encapsulates access to the gossip cluster state and exposes REST endpoints.

• The REST server listens on the configured address and serves two main endpoints interacting with the Chitchat cluster.

References

• Chitchat Cluster Membership Protocol

• REST API Design

• Tokio Asynchronous Runtime

• poem Web Framework

• ID Generation Techniques