add documenting comments

bin/src/command/mod.rs

@@ -49,8 +49,8 @@ mod worker;
 
 pub use worker::*;
 
-// The CommandServer receives these CommandMessages, either from within Sōzu,
-// or from without, in which case they are ALWAYS of the ClientRequest variant.
+/// The CommandServer receives these CommandMessages, either from within Sōzu,
+/// or from without, in which case they are ALWAYS of the ClientRequest variant.
 enum CommandMessage {
     ClientNew {
         client_id: String,

bin/src/command/worker.rs

@@ -12,6 +12,7 @@ use sozu_command_lib::{
     scm_socket::ScmSocket,
 };
 
+/// An instance of Sōzu, as seen from the main process
 pub struct Worker {
     pub id: u32,
     /// for the worker to receive requests and respond to the main process
@@ -23,6 +24,7 @@ pub struct Worker {
     pub queue: VecDeque<ProxyRequest>,
     /// Used to send and receive listeners (socket addresses and file descriptors)
     pub scm_socket: ScmSocket,
+    /// Used to send proxyrequests to the worker loop
     pub sender: Option<futures::channel::mpsc::Sender<ProxyRequest>>,
 }
 
@@ -64,8 +66,8 @@ impl Worker {
         }
     }
 
+    /// send a kill -0 to check on the pid, if it's dead it should be an error
     pub fn the_pid_is_alive(&self) -> bool {
-        // send a kill -0 to check on the pid, if it's dead it should be an error
         kill(Pid::from_raw(self.pid), None).is_ok()
     }
 

bin/src/upgrade.rs

@@ -130,6 +130,7 @@ pub fn fork_main_into_new_main(
     }
 }
 
+/// starts new main process with upgrade data, notifies the old main process
 pub fn begin_new_main_process(
     new_to_old_channel_fd: i32,
     upgrade_file_fd: i32,

command/src/command.rs

@@ -10,20 +10,33 @@ use crate::{
 
 pub const PROTOCOL_VERSION: u8 = 0;
 
+/// Details of a request sent by the CLI (or other) to the main process
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum CommandRequestOrder {
+    /// an order to forward to workers
     Proxy(Box<ProxyRequestOrder>),
+    /// save Sōzu's parseable state as a file
     SaveState { path: String },
+    /// load a state file
     LoadState { path: String },
+    /// dump the state in JSON
     DumpState,
+    /// list the workers and their status
     ListWorkers,
+    /// list the frontends, filtered by protocol and/or domain
     ListFrontends(FrontendFilters),
+    /// launche a new worker
     LaunchWorker(String),
+    /// upgrade the main process
     UpgradeMain,
+    /// upgrade an existing worker
     UpgradeWorker(u32),
+    /// subscribe to proxy events
     SubscribeEvents,
+    /// reload the configuration from the config file, or a new file
     ReloadConfiguration { path: Option<String> },
+    /// give status of main process and all workers
     Status,
 }
 
@@ -35,6 +48,7 @@ pub struct FrontendFilters {
     pub domain: Option<String>,
 }
 
+/// Sent to the main process by the CLI (or other) through the unix socket
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct CommandRequest {
     pub id: String,
@@ -64,16 +78,21 @@ pub enum CommandStatus {
     Error,
 }
 
+/// details of a response sent by the main process to the client
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum CommandResponseContent {
+    /// a list of workers, with ids, pids, statuses
     Workers(Vec<WorkerInfo>),
-    /// used by the main process to respond to the CLI
+    /// aggregated metrics of main process and workers
     Metrics(AggregatedMetricsData),
-    /// worker_id -> query_answer
+    /// worker responses to a same query: worker_id -> query_answer
     Query(BTreeMap<String, QueryAnswer>),
+    /// the state of Sōzu: frontends, backends, listeners, etc.
     State(Box<ConfigState>),
+    /// a proxy event
     Event(Event),
+    /// a filtered list of frontend
     FrontendList(ListedFrontends),
     // this is new
     Status(Vec<WorkerInfo>),
@@ -86,6 +105,7 @@ pub struct ListedFrontends {
     pub tcp_frontends: Vec<TcpFrontend>,
 }
 
+/// Responses of the main process to the CLI (or other client)
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct CommandResponse {
     pub id: String,
@@ -112,6 +132,7 @@ impl CommandResponse {
     }
 }
 
+/// Runstate of a worker
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum RunState {
@@ -134,6 +155,7 @@ pub struct WorkerInfo {
     pub run_state: RunState,
 }
 
+/// a backend event that happened on a proxy
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum Event {

command/src/config.rs

@@ -22,11 +22,10 @@ use crate::{
     },
 };
 
-// [`DEFAULT_RUSTLS_CIPHER_LIST`] provides all supported cipher suites exported by Rustls TLS
-// provider as it support only strongly secure ones.
-//
-// See:
-// - https://docs.rs/rustls/latest/rustls/static.ALL_CIPHER_SUITES.html
+/// [`DEFAULT_RUSTLS_CIPHER_LIST`] provides all supported cipher suites exported by Rustls TLS
+/// provider as it support only strongly secure ones.
+///
+/// See the [documentation](https://docs.rs/rustls/latest/rustls/static.ALL_CIPHER_SUITES.html)
 pub const DEFAULT_RUSTLS_CIPHER_LIST: [&'static str; 9] = [
     // TLS 1.3 cipher suites
     "TLS13_AES_256_GCM_SHA384",
@@ -62,9 +61,8 @@ pub const DEFAULT_SIGNATURE_ALGORITHMS: [&'static str; 9] = [
 
 pub const DEFAULT_GROUPS_LIST: [&'static str; 4] = ["P-521", "P-384", "P-256", "x25519"];
 
-// -------------------------------------------------------------------------------------------------
-// Listener structure
-
+// todo: refactor this with a builder pattern for cleanliness
+/// an HTTP, HTTPS or TCP listener as ordered by a client
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Listener {
@@ -863,6 +861,7 @@ impl FileConfig {
         }
     }
 
+    // TODO: split into severa functions
     pub fn into(self, config_path: &str) -> anyhow::Result<Config> {
         let mut clusters = HashMap::new();
         let mut http_listeners = Vec::new();

command/src/proxy.rs

@@ -196,6 +196,7 @@ impl fmt::Display for ProxyRequest {
     }
 }
 
+/// An order sent by the main process to the workers
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum ProxyRequestOrder {
@@ -606,6 +607,7 @@ pub struct DeactivateListener {
     pub to_scm: bool,
 }
 
+/// details of an HTTP listener, sent by the main process to the worker
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct HttpListener {
     pub address: SocketAddr,
@@ -615,7 +617,7 @@ pub struct HttpListener {
     #[serde(default)]
     #[serde(skip_serializing_if = "is_false")]
     pub expect_proxy: bool,
-    // TODO: explain what this does
+    /// identifies sticky sessions
     #[serde(default = "default_sticky_name")]
     pub sticky_name: String,
     /// client inactive time
@@ -694,6 +696,7 @@ impl error::Error for ParseErrorTlsVersion {
     }
 }
 
+/// details of an HTTPS listener, sent by the main process to the worker
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct HttpsListener {
     pub address: SocketAddr,
@@ -758,6 +761,7 @@ impl Default for HttpsListener {
     }
 }
 
+/// details of an TCP listener, sent by the main process to the worker
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct TcpListener {
     pub address: SocketAddr,
@@ -778,6 +782,7 @@ pub enum MetricsConfiguration {
     Clear,
 }
 
+/// Details of a query for information, sent to a worker
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum Query {
@@ -818,6 +823,7 @@ pub struct QueryMetricsOptions {
     pub metric_names: Vec<String>,
 }
 
+/// details of an query answer, sent by a worker
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "type", content = "data", rename_all = "SCREAMING_SNAKE_CASE")]
 pub enum QueryAnswer {
@@ -839,7 +845,7 @@ pub struct QueryAnswerCluster {
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub enum QueryAnswerCertificate {
-    /// returns a list of domain -> fingerprint
+    /// returns a list of certificates: domain -> fingerprint
     All(HashMap<SocketAddr, BTreeMap<String, Vec<u8>>>),
     /// returns a fingerprint
     Domain(HashMap<SocketAddr, Option<(String, Vec<u8>)>>),
@@ -859,6 +865,7 @@ pub enum QueryAnswerMetrics {
 }
 
 impl ProxyRequestOrder {
+    /// determine to which of the three proxies (HTTP, HTTPS, TCP) a request is destined
     pub fn get_destinations(&self) -> ProxyDestinations {
         let mut proxy_destination = ProxyDestinations {
             to_http_proxy: false,