document settings crate (#271)

actix-settings/src/settings/address.rs

@@ -37,9 +37,13 @@ static ADDR_LIST_REGEX: Lazy<Regex> = Lazy::new(|| {
     .expect("Failed to compile regex: ADDRS_REGEX")
 });
 
+/// A host/port pair for the server to bind to.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)]
 pub struct Address {
+    /// Host part of address.
     pub host: String,
+
+    /// Port part of address.
     pub port: u16,
 }
 

actix-settings/src/settings/backlog.rs

@@ -4,9 +4,20 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// The maximum number of pending connections.
+///
+/// This refers to the number of clients that can be waiting to be served. Exceeding this number
+/// results in the client getting an error when attempting to connect. It should only affect servers
+/// under significant load.
+///
+/// Generally set in the 64–2048 range. The default value is 2048. Takes a string value: Either
+/// "default", or an integer N > 0 e.g. "6".
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Backlog {
+    /// The default number of connections. See struct docs.
     Default,
+
+    /// A specific number of connections.
     Manual(usize),
 }
 

actix-settings/src/settings/keep_alive.rs

@@ -6,11 +6,24 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// The server keep-alive preference.
+///
+/// By default keep alive is set to 5 seconds. Takes a string value: Either "default", "disabled",
+/// "os", or a string of the format "N seconds" where N is an integer > 0 e.g. "6 seconds".
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum KeepAlive {
+    /// The default keep-alive as defined by Actix Web.
     Default,
+
+    /// Disable keep-alive.
     Disabled,
+
+    /// Let the OS determine keep-alive duration.
+    ///
+    /// Note: this is usually quite long.
     Os,
+
+    /// A specific keep-alive duration (in seconds).
     Seconds(usize),
 }
 

actix-settings/src/settings/max_connection_rate.rs

@@ -4,9 +4,17 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// The maximum per-worker concurrent TLS connection limit.
+///
+/// All listeners will stop accepting connections when this limit is reached. It can be used to
+/// limit the global TLS CPU usage. By default max connections is set to a 256. Takes a string
+/// value: Either "default", or an integer N > 0 e.g. "6".
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum MaxConnectionRate {
+    /// The default connection limit. See struct docs.
     Default,
+
+    /// A specific connection limit.
     Manual(usize),
 }
 

actix-settings/src/settings/max_connections.rs

@@ -4,9 +4,17 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// The maximum per-worker number of concurrent connections.
+///
+/// All socket listeners will stop accepting connections when this limit is reached for each worker.
+/// By default max connections is set to a 25k. Takes a string value: Either "default", or an
+/// integer N > 0 e.g. "6".
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum MaxConnections {
+    /// The default number of connections. See struct docs.
     Default,
+
+    /// A specific number of connections.
     Manual(usize),
 }
 

actix-settings/src/settings/mod.rs

@@ -24,17 +24,42 @@ pub use self::tls::Tls;
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub struct ActixSettings {
+    /// List of addresses for the server to bind to.
     pub hosts: Vec<Address>,
-    pub mode: mode::Mode,
+
+    /// Marker of intended deployment environment.
+    pub mode: Mode,
+
+    /// True if the [`Compress`](actix_web::middleware::Compress) middleware should be enabled.
     pub enable_compression: bool,
+
+    /// True if the [`Logger`](actix_web::middleware::Logger) middleware should be enabled.
     pub enable_log: bool,
+
+    /// The number of workers that the server should start.
     pub num_workers: NumWorkers,
+
+    /// The maximum number of pending connections.
     pub backlog: Backlog,
+
+    /// The per-worker maximum number of concurrent connections.
     pub max_connections: MaxConnections,
+
+    /// The per-worker maximum concurrent TLS connection limit.
     pub max_connection_rate: MaxConnectionRate,
+
+    /// Server keep-alive preference.
     pub keep_alive: KeepAlive,
+
+    /// Timeout duration for reading client request header.
     pub client_timeout: Timeout,
+
+    /// Timeout duration for connection shutdown.
     pub client_shutdown: Timeout,
+
+    /// Timeout duration for graceful worker shutdown.
     pub shutdown_timeout: Timeout,
+
+    /// TLS (HTTPS) configuration.
     pub tls: Tls,
 }

actix-settings/src/settings/mode.rs

@@ -2,10 +2,14 @@ use serde::Deserialize;
 
 use crate::{AtResult, Parse};
 
+/// Marker of intended deployment environment.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum Mode {
+    /// Marks development environment.
     Development,
+
+    /// Marks production environment.
     Production,
 }
 

actix-settings/src/settings/num_workers.rs

@@ -4,9 +4,16 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// The number of workers that the server should start.
+///
+/// By default the number of available logical cpu cores is used. Takes a string value: Either
+/// "default", or an integer N > 0 e.g. "6".
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum NumWorkers {
+    /// The default number of workers. See struct docs.
     Default,
+
+    /// A specific number of workers.
     Manual(usize),
 }
 

actix-settings/src/settings/timeout.rs

@@ -6,10 +6,16 @@ use serde::de;
 
 use crate::{AtError, AtResult, Parse};
 
+/// A timeout duration in milliseconds or seconds.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Timeout {
+    /// The default timeout. Depends on context.
     Default,
+
+    /// Timeout in milliseconds.
     Milliseconds(usize),
+
+    /// Timeout in seconds.
     Seconds(usize),
 }
 
@@ -34,18 +40,22 @@ impl Parse for Timeout {
                 })
             }
         }
+
         match string {
             "default" => Ok(Timeout::Default),
+
             string if !FMT.is_match(string) => invalid_value!(string),
+
             string => match (DIGITS.find(string), UNIT.find(string)) {
-                (None, _) => invalid_value!(string),
-                (_, None) => invalid_value!(string),
-                (Some(dmatch), Some(umatch)) => {
-                    let digits = &string[dmatch.start()..dmatch.end()];
-                    let unit = &string[umatch.start()..umatch.end()];
+                (None, _) | (_, None) => invalid_value!(string),
+
+                (Some(digits), Some(unit)) => {
+                    let digits = &string[digits.range()];
+                    let unit = &string[unit.range()];
+
                     match (digits.parse(), unit) {
-                        (Ok(v), "milliseconds") => Ok(Timeout::Milliseconds(v)),
-                        (Ok(v), "seconds") => Ok(Timeout::Seconds(v)),
+                        (Ok(n), "milliseconds") => Ok(Timeout::Milliseconds(n)),
+                        (Ok(n), "seconds") => Ok(Timeout::Seconds(n)),
                         _ => invalid_value!(string),
                     }
                 }

actix-settings/src/settings/tls.rs

@@ -2,10 +2,17 @@ use std::path::PathBuf;
 
 use serde::Deserialize;
 
+/// TLS (HTTPS) configuration.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)]
 #[serde(rename_all = "kebab-case")]
+#[doc(alias = "ssl", alias = "https")]
 pub struct Tls {
+    /// Tru if accepting TLS connections should be enabled.
     pub enabled: bool,
+
+    /// Path to certificate `.pem` file.
     pub certificate: PathBuf,
+
+    /// Path to private key `.pem` file.
     pub private_key: PathBuf,
 }