config.rs

Overview

This file defines the configuration management for a proxy service component. It primarily focuses on loading, saving, and handling dynamic reloading of proxy configurations, as well as providing conversion to network-specific configuration structures. The ProxyConfig struct encapsulates all relevant configuration parameters such as network bindings, cryptographic certificates, peer addresses, and gossip protocol settings. The file also includes asynchronous signal handling for runtime configuration reloads triggered by Unix SIGHUP signals.

Detailed Components

Struct: ProxyConfig

Represents the main configuration for the proxy service.

Fields

• bind: SocketAddr
  The socket address on which the proxy binds to listen for incoming connections.

• gossip: GossipConfig
  Configuration settings related to the gossip protocol used by the proxy.
  See GossipConfig for details.

• my_addr: Option<Vec<SocketAddr>>
  Optional list of socket addresses representing the proxy's own network addresses.
  Custom serialization and deserialization are implemented to allow either a single address or multiple addresses in the config file.

• my_cert: CertFile
  The proxy's TLS certificate file used for secure communications.

• my_key: PrivateKeyFile
  The private key file corresponding to the proxy's TLS certificate.

• peer_certs: CertStore
  Stores peer TLS certificates trusted by the proxy.

• peer_ed_pubkeys: Vec<transport_layer::VerifyingKey>
  A list of public verifying keys for peers, serialized/deserialized as hex strings.

• bk_addrs: Vec<SocketAddr>
  Addresses of the backup nodes or services the proxy interacts with.

• subscribe: Vec<Vec<SocketAddr>>
  Lists of socket addresses representing subscription groups for message propagation.
  Custom serialization and deserialization are applied here. See PubSub Subscribe Serialization.

• broadcast_buffer_len: usize
  Buffer length for broadcast operations, defaulting to 2000 if not explicitly specified.

Methods

• from_file(path: impl AsRef<Path>) -> anyhow::Result<Self>
  Loads a ProxyConfig instance from a YAML configuration file located at the given path.
  Returns an error if the file cannot be read or deserialized.

  Example usage:

  let config = ProxyConfig::from_file("config.yaml")?;
  

• save(&self, path: impl AsRef<Path>) -> anyhow::Result<()>
  Serializes and writes the current configuration state to a YAML file at the specified path.
  Returns an error if the file cannot be created or written.

  Example usage:

  config.save("new_config.yaml")?;
  

• network_config(&self, tls_cert_cache: Option<TlsCertCache>) -> anyhow::Result<NetworkConfig>
  Converts the proxy configuration into a NetworkConfig structure, which is used by other network components for establishing connections and managing peer communications.
  Accepts an optional TLS certificate cache to improve certificate handling performance.

  Example usage:

  let network_cfg = config.network_config(None)?;
  

Function: default_broadcast_buffer_len() -> usize

Returns the default value for the broadcast buffer length, which is 2000.

Async Function: config_reload_handler

pub(crate) async fn config_reload_handler(
    config_updates: tokio::sync::watch::Sender<ProxyConfig>,
    config_path: PathBuf,
) -> anyhow::Result<()>

• Listens asynchronously for Unix SIGHUP signals.

• On receiving SIGHUP, attempts to reload the configuration from the specified file path.

• If successful, sends the updated configuration through the provided Tokio watch channel for consumption by other components.

• Logs errors when the reload fails but does not terminate the process.

• Panics on signal subscription errors.

Parameters:

• config_updates: Sender channel to broadcast configuration updates.

• config_path: Filesystem path to the YAML configuration file.

Usage:

This function is intended to be run in a Tokio runtime environment to enable hot-reloading of proxy configurations without restarting the service.

Module: addr_serde

Custom serialization and deserialization helpers for handling Option<Vec<SocketAddr>> types that may be represented as either a single address or a list of addresses in the configuration YAML.

• opt_vec_deser: Deserialize either a single SocketAddr or a list of them into Option<Vec<SocketAddr>>.

• opt_vec_ser: Serialize Option<Vec<SocketAddr>> as either a single address or a list, or None.

Test Module

Contains a basic test verifying that the configuration file at config.yaml (in the project directory) can be successfully loaded into a ProxyConfig instance.

#[test]
fn config_file_match_test() {
    let config_path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("config.yaml");
    _ = ProxyConfig::from_file(config_path).unwrap();
}

Important Implementation Details

• The file uses serde for (de)serialization of the configuration in YAML format.

• The addr_serde module employs untagged enums to flexibly accept either a single address or multiple addresses, improving user convenience in config files.

• The asynchronous signal handling relies on Tokio's Unix signal handling facilities to listen for SIGHUP and trigger configuration reloads at runtime.

• The network configuration conversion excludes some fields (empty vectors are passed) indicating selective propagation of configuration parameters to network layers.

• Cryptographic material (certificates and keys) are tightly integrated with the proxy configuration and are essential for establishing secure connections.

Interaction with Other System Components

• Gossip Protocol: Uses GossipConfig for configuring gossip-related parameters, implying integration with Gossip Protocol Handling.

• Network Layer: Converts the proxy config into NetworkConfig, which is consumed by the Network Module.

• Pub/Sub System: The subscribe field and certificate/key files interact with the Pub/Sub subsystem, relating to PubSub Configuration.

• Transport Layer: Uses TlsCertCache and verifying keys from the transport layer for TLS and cryptographic verification, linking to Transport Layer Security.

• Signal Handling: Utilizes Tokio's Unix signal handling for runtime config reloads, connecting to Async Signal Processing.

Diagram: ProxyConfig Structure and Workflow

classDiagram
class ProxyConfig {
+bind: SocketAddr
+gossip: GossipConfig
+my_addr: Option<Vec<SocketAddr>>
+my_cert: CertFile
+my_key: PrivateKeyFile
+peer_certs: CertStore
+peer_ed_pubkeys: Vec<VerifyingKey>
+bk_addrs: Vec<SocketAddr>
+subscribe: Vec<Vec<SocketAddr>>
+broadcast_buffer_len: usize
+from_file()
+save()
+network_config()
}
class addr_serde {
+opt_vec_deser()
+opt_vec_ser()
}
class config_reload_handler {
+async run()
}
ProxyConfig ..> GossipConfig : uses
ProxyConfig ..> CertFile : contains
ProxyConfig ..> PrivateKeyFile : contains
ProxyConfig ..> CertStore : contains
ProxyConfig ..> VerifyingKey : contains
ProxyConfig ..> NetworkConfig : converts to
config_reload_handler ..> ProxyConfig : reloads config
ProxyConfig ..> addr_serde : serialization helpers

This diagram illustrates the key entities in this file, their primary fields and methods, and the relationships between them, highlighting how configuration data flows from file to runtime usage and reload handling.