pub enum AtError { + ?
pub enum AtError { EnvVarError(VarError), FileExists(PathBuf), InvalidValue { @@ -15,16 +15,25 @@ ParseIntError(ParseIntError), ParseAddressError(String), TomlError(TomlError), -}
EnvVarError(VarError)
FileExists(PathBuf)
InvalidValue
expected: &'static str
got: String
file: &'static str
line: u32
column: u32
IoError(IoError)
ParseBoolError(ParseBoolError)
ParseIntError(ParseIntError)
ParseAddressError(String)
TomlError(TomlError)
Returns a copy of the value. Read more
Errors that can be returned from methods in this crate.
Environment variable does not exists or is invalid.
File already exists on disk.
Invalid value.
I/O error.
Value is not a boolean.
Value is not an integer.
Value is not an address.
Error deserializing as TOML.
Performs copy-assignment from source. Read more
source
Formats the value using the given formatter. Read more
Converts to this type from the input type.
Gets the TypeId of self. Read more
TypeId
self
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
pub enum Backlog { + ?
pub enum Backlog { Default, Manual(usize), -}
Default
Manual(usize)
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”.
The default number of connections. See struct docs.
A specific number of connections.
Deserialize this value from the given Serde deserializer. Read more
Feeds this value into the given Hasher. Read more
Hasher
Feeds a slice of this type into the given Hasher. Read more
This method tests for self and other values to be equal, and is used +
other
Parse Self from string.
Self
string
This method tests for self and other values to be equal, and is used by ==. Read more
==
This method tests for !=.
!=
Compare self to key and return true if they are equal.
key
true
pub enum KeepAlive { + ?
pub enum KeepAlive { Default, Disabled, Os, Seconds(usize), -}
Disabled
Os
Seconds(usize)
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”.
The default keep-alive as defined by Actix Web.
Disable keep-alive.
Let the OS determine keep-alive duration.
Note: this is usually quite long.
A specific keep-alive duration (in seconds).
pub enum MaxConnectionRate { + ?
pub enum MaxConnectionRate { Default, Manual(usize), -}
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”.
The default connection limit. See struct docs.
A specific connection limit.
pub enum MaxConnections { + ?
pub enum MaxConnections { Default, Manual(usize), -}
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”.
pub enum Mode { + ?
pub enum Mode { Development, Production, -}
Development
Production
Marker of intended deployment environment.
Marks development environment.
Marks production environment.
pub enum NumWorkers { + ?
pub enum NumWorkers { Default, Manual(usize), -}
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”.
The default number of workers. See struct docs.
A specific number of workers.
pub enum Timeout { + ?
pub enum Timeout { Default, Milliseconds(usize), Seconds(usize), -}
Milliseconds(usize)
A timeout duration in milliseconds or seconds.
The default timeout. Depends on context.
Timeout in milliseconds.
Timeout in seconds.
Easily manage Actix Web’s settings from a TOML file and environment variables.
To get started add a Settings::parse_toml("./Server.toml") call to the +top of your main function. This will create a template file with descriptions of all the +configurable settings. You can change or remove anything in that file and it will be picked up +the next time you run your application.
Settings::parse_toml("./Server.toml")
Overriding parts of the file can be done from values using Settings::override_field or from +the environment using Settings::override_field_with_env_var.
Settings::override_field
Settings::override_field_with_env_var
See examples folder on GitHub for complete example.
use actix_settings::{ApplySettings as _, Mode, Settings}; + +#[actix_web::main] +async fn main() -> std::io::Result<()> { + let mut settings = Settings::parse_toml("./Server.toml") + .expect("Failed to parse `Settings` from Server.toml"); + + // If the environment variable `$APPLICATION__HOSTS` is set, + // have its value override the `settings.actix.hosts` setting: + Settings::override_field_with_env_var(&mut settings.actix.hosts, "APPLICATION__HOSTS")?; + + init_logger(&settings); + + HttpServer::new({ + // clone settings into each worker thread + let settings = settings.clone(); + + move || { + App::new() + // Include this `.wrap()` call for compression settings to take effect + .wrap(Condition::new( + settings.actix.enable_compression, + Compress::default(), + )) + + // add request logger + .wrap(Logger::default()) + + // make `Settings` available to handlers + .app_data(web::Data::new(settings.clone())) + + // add request handlers as normal + .service(index) + } + }) + // apply the `Settings` to Actix Web's `HttpServer` + .apply_settings(&settings) + .run() + .await +}
Settings types for Actix Web.
A host/port pair for the server to bind to.
Wrapper for server and application-specific settings.
Marker type representing no defined application-specific settings.
TLS (HTTPS) configuration.
Extension trait for applying parsed settings to the server object.
A specialized FromStr trait that returns AtError errors
FromStr
AtError
Convenience type alias for Result<T, AtError>.
Result<T, AtError>
Convenience type alias for BasicSettings with no defined application-specific settings.
BasicSettings
pub struct ActixSettings {Show 13 fields + ?
pub struct ActixSettings {Show 13 fields pub hosts: Vec<Address>, pub mode: Mode, pub enable_compression: bool, @@ -15,7 +15,20 @@ pub shutdown_timeout: Timeout, pub tls: Tls, }
hosts: Vec<Address>
mode: Mode
enable_compression: bool
enable_log: bool
num_workers: NumWorkers
backlog: Backlog
max_connections: MaxConnections
max_connection_rate: MaxConnectionRate
keep_alive: KeepAlive
client_timeout: Timeout
client_shutdown: Timeout
shutdown_timeout: Timeout
tls: Tls
List of addresses for the server to bind to.
True if the Compress middleware should be enabled.
Compress
True if the Logger middleware should be enabled.
Logger
The per-worker maximum number of concurrent connections.
The per-worker maximum concurrent TLS connection limit.
Server keep-alive preference.
Timeout duration for reading client request header.
Timeout duration for connection shutdown.
Timeout duration for graceful worker shutdown.
pub struct Address { + ?
pub struct Address { pub host: String, pub port: u16, -}
host: String
port: u16
Host part of address.
Port part of address.
pub struct BasicSettings<A> { + ?
pub struct BasicSettings<A> { pub actix: ActixSettings, pub application: A, -}
actix: ActixSettings
application: A
Parse an instance of Self from a TOML file located at filepath. -If the file doesn’t exist, it is generated from the default TOML -template, after which the newly generated file is read in and parsed.
TOML
filepath
Parse an instance of Self straight from the default TOML template.
Write the default TOML template to a new file, to be located -at filepath. Return a Error::FileExists(_) error if a -file already exists at that location.
Error::FileExists(_)
Actix Web server settings.
Application-specific settings.
Parse an instance of Self from a TOML file located at filepath.
If the file doesn’t exist, it is generated from the default TOML template, after which the +newly generated file is read in and parsed.
Writes the default TOML template to a new file, located at filepath.
Returns a FileExists error if a file already exists at that +location.
FileExists
Attempts to parse value and override the referenced field.
value
field
use actix_settings::{Settings, Mode}; + +let mut settings = Settings::from_default_template()?; +assert_eq!(settings.actix.mode, Mode::Development); + +Settings::override_field(&mut settings.actix.mode, "production")?; +assert_eq!(settings.actix.mode, Mode::Production);
Attempts to read an environment variable, parse it, and override the referenced field.
use actix_settings::{Settings, Mode}; + +std::env::set_var("OVERRIDE__MODE", "production"); + +let mut settings = Settings::from_default_template()?; +assert_eq!(settings.actix.mode, Mode::Development); + +Settings::override_field_with_env_var(&mut settings.actix.mode, "OVERRIDE__MODE")?; +assert_eq!(settings.actix.mode, Mode::Production);
#[non_exhaustive]pub struct NoSettings {}
pub struct Tls { + ?
pub struct Tls { pub enabled: bool, pub certificate: PathBuf, pub private_key: PathBuf, -}
enabled: bool
certificate: PathBuf
private_key: PathBuf
Tru if accepting TLS connections should be enabled.
Path to certificate .pem file.
.pem
Path to private key .pem file.
pub trait ApplySettings { + ?
pub trait ApplySettings { fn apply_settings<A>(self, settings: &BasicSettings<A>) -> Self where A: DeserializeOwned; -}
Apply a BasicSettings value to self.
pub trait Parse: Sized { + ?
pub trait Parse: Sized { fn parse(string: &str) -> Result<Self, AtError>; -}
pub type AtResult<T> = Result<T, AtError>;
pub type Settings = BasicSettings<NoSettings>;
U::from(self)
ProtoBufMessage
actix
RespValue
actix-redis
Supervisor
RedisActor
Session
actix-web
Session::get
Session::insert
SessionMiddleware
SessionMiddleware::new
Domain
HttpOnly
Path
SameSite
Secure
SessionStore::load
RedisActorSessionStore
RedisSessionStore
SessionStore::save
SessionStore::update
Error
BasicAuth
WWW-Authenticate
realm
BearerAuth
scope
Authorization
Basic
Bearer
Scheme
user_id
error
error_description
error_uri
HttpAuthentication
use std::{env::VarError, io, num::ParseIntError, path::PathBuf, str::ParseBoolError}; use toml::de::Error as TomlError; +/// Convenience type alias for `Result<T, AtError>`. pub type AtResult<T> = std::result::Result<T, AtError>; -#[derive(Clone, Debug)] +/// Errors that can be returned from methods in this crate. +#[derive(Debug, Clone)] pub enum AtError { + /// Environment variable does not exists or is invalid. EnvVarError(VarError), + + /// File already exists on disk. FileExists(PathBuf), + + /// Invalid value. + #[allow(missing_docs)] InvalidValue { expected: &'static str, got: String, @@ -140,10 +166,20 @@ line: u32, column: u32, }, + + /// I/O error. IoError(ioe::IoError), + + /// Value is not a boolean. ParseBoolError(ParseBoolError), + + /// Value is not an integer. ParseIntError(ParseIntError), + + /// Value is not an address. ParseAddressError(String), + + /// Error deserializing as TOML. TomlError(TomlError), } diff --git a/src/actix_settings/lib.rs.html b/src/actix_settings/lib.rs.html index 044204f92..8f782ee41 100644 --- a/src/actix_settings/lib.rs.html +++ b/src/actix_settings/lib.rs.html @@ -702,12 +702,174 @@ 700 701 702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805
//! Easily manage Actix Web's settings from a TOML file and environment variables. +//! +//! To get started add a [`Settings::parse_toml("./Server.toml")`](Settings::parse_toml) call to the +//! top of your main function. This will create a template file with descriptions of all the +//! configurable settings. You can change or remove anything in that file and it will be picked up +//! the next time you run your application. +//! +//! Overriding parts of the file can be done from values using [`Settings::override_field`] or from +//! the environment using [`Settings::override_field_with_env_var`]. +//! +//! # Examples +//! +//! See examples folder on GitHub for complete example. +//! +//! ```ignore +//! # use actix_web::{ +//! # get, +//! # middleware::{Compress, Condition, Logger}, +//! # web, App, HttpServer, +//! # }; +//! use actix_settings::{ApplySettings as _, Mode, Settings}; +//! +//! #[actix_web::main] +//! async fn main() -> std::io::Result<()> { +//! let mut settings = Settings::parse_toml("./Server.toml") +//! .expect("Failed to parse `Settings` from Server.toml"); +//! +//! // If the environment variable `$APPLICATION__HOSTS` is set, +//! // have its value override the `settings.actix.hosts` setting: +//! Settings::override_field_with_env_var(&mut settings.actix.hosts, "APPLICATION__HOSTS")?; +//! +//! init_logger(&settings); +//! +//! HttpServer::new({ +//! // clone settings into each worker thread +//! let settings = settings.clone(); +//! +//! move || { +//! App::new() +//! // Include this `.wrap()` call for compression settings to take effect +//! .wrap(Condition::new( +//! settings.actix.enable_compression, +//! Compress::default(), +//! )) +//! +//! // add request logger +//! .wrap(Logger::default()) +//! +//! // make `Settings` available to handlers +//! .app_data(web::Data::new(settings.clone())) +//! +//! // add request handlers as normal +//! .service(index) +//! } +//! }) +//! // apply the `Settings` to Actix Web's `HttpServer` +//! .apply_settings(&settings) +//! .run() +//! .await +//! } +//! ``` #![forbid(unsafe_code)] #![deny(rust_2018_idioms, nonstandard_style)] -#![warn(future_incompatible, missing_debug_implementations)] -// #![warn(missing_docs)] +#![warn(future_incompatible, missing_docs, missing_debug_implementations)] #![doc(html_logo_url = "https://actix.rs/img/logo.png")] #![doc(html_favicon_url = "https://actix.rs/favicon.ico")] @@ -741,15 +903,21 @@ NumWorkers, Timeout, Tls, }; +/// Wrapper for server and application-specific settings. #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)] #[serde(bound = "A: Deserialize<'de>")] pub struct BasicSettings<A> { + /// Actix Web server settings. pub actix: ActixSettings, + + /// Application-specific settings. pub application: A, } +/// Convenience type alias for [`BasicSettings`] with no defined application-specific settings. pub type Settings = BasicSettings<NoSettings>; +/// Marker type representing no defined application-specific settings. #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize)] #[non_exhaustive] pub struct NoSettings {/* NOTE: turning this into a unit struct will cause deserialization failures. */} @@ -758,14 +926,16 @@ where A: de::DeserializeOwned, { - /// NOTE **DO NOT** mess with the ordering of the tables in this template. - /// Especially the `[application]` table needs to be last in order - /// for some tests to keep working. + // NOTE **DO NOT** mess with the ordering of the tables in the default template. + // Especially the `[application]` table needs to be last in order + // for some tests to keep working. + /// Default settings file contents. pub(crate) const DEFAULT_TOML_TEMPLATE: &'static str = include_str!("./defaults.toml"); - /// Parse an instance of `Self` from a `TOML` file located at `filepath`. - /// If the file doesn't exist, it is generated from the default `TOML` - /// template, after which the newly generated file is read in and parsed. + /// Parse an instance of `Self` from a TOML file located at `filepath`. + /// + /// If the file doesn't exist, it is generated from the default TOML template, after which the + /// newly generated file is read in and parsed. pub fn parse_toml<P>(filepath: P) -> AtResult<Self> where P: AsRef<Path>, @@ -777,43 +947,62 @@ } let mut f = File::open(filepath)?; + // TODO: don't bail on metadata fail let mut contents = String::with_capacity(f.metadata()?.len() as usize); f.read_to_string(&mut contents)?; Ok(toml::from_str::<Self>(&contents)?) } - /// Parse an instance of `Self` straight from the default `TOML` template. + /// Parse an instance of `Self` straight from the default TOML template. + // TODO: make infallible + // TODO: consider "template" rename pub fn from_default_template() -> AtResult<Self> { Self::from_template(Self::DEFAULT_TOML_TEMPLATE) } - /// Parse an instance of `Self` straight from the default `TOML` template. + /// Parse an instance of `Self` straight from the default TOML template. + // TODO: consider "template" rename pub fn from_template(template: &str) -> AtResult<Self> { Ok(toml::from_str(template)?) } - /// Write the default `TOML` template to a new file, to be located - /// at `filepath`. Return a `Error::FileExists(_)` error if a - /// file already exists at that location. + /// Writes the default TOML template to a new file, located at `filepath`. + /// + /// # Errors + /// Returns a [`FileExists`](crate::AtError::FileExists) error if a file already exists at that + /// location. pub fn write_toml_file<P>(filepath: P) -> AtResult<()> where P: AsRef<Path>, { let filepath = filepath.as_ref(); - let contents = Self::DEFAULT_TOML_TEMPLATE.trim(); if filepath.exists() { return Err(AtError::FileExists(filepath.to_path_buf())); } let mut file = File::create(filepath)?; - file.write_all(contents.as_bytes())?; + file.write_all(Self::DEFAULT_TOML_TEMPLATE.trim().as_bytes())?; file.flush()?; Ok(()) } + /// Attempts to parse `value` and override the referenced `field`. + /// + /// # Examples + /// ``` + /// use actix_settings::{Settings, Mode}; + /// + /// # fn inner() -> actix_settings::AtResult<()> { + /// let mut settings = Settings::from_default_template()?; + /// assert_eq!(settings.actix.mode, Mode::Development); + /// + /// Settings::override_field(&mut settings.actix.mode, "production")?; + /// assert_eq!(settings.actix.mode, Mode::Production); + /// # Ok(()) } + /// ``` pub fn override_field<F, V>(field: &mut F, value: V) -> AtResult<()> where F: Parse, @@ -823,6 +1012,22 @@ Ok(()) } + /// Attempts to read an environment variable, parse it, and override the referenced `field`. + /// + /// # Examples + /// ``` + /// use actix_settings::{Settings, Mode}; + /// + /// std::env::set_var("OVERRIDE__MODE", "production"); + /// + /// # fn inner() -> actix_settings::AtResult<()> { + /// let mut settings = Settings::from_default_template()?; + /// assert_eq!(settings.actix.mode, Mode::Development); + /// + /// Settings::override_field_with_env_var(&mut settings.actix.mode, "OVERRIDE__MODE")?; + /// assert_eq!(settings.actix.mode, Mode::Production); + /// # Ok(()) } + /// ``` pub fn override_field_with_env_var<F, N>(field: &mut F, var_name: N) -> AtResult<()> where F: Parse, @@ -836,6 +1041,7 @@ } } +/// Extension trait for applying parsed settings to the server object. pub trait ApplySettings { /// Apply a [`BasicSettings`] value to `self`. /// @@ -904,9 +1110,9 @@ self = match settings.actix.client_timeout { Timeout::Default => self, Timeout::Milliseconds(n) => { - self.client_disconnect_timeout(Duration::from_millis(n as u64)) + self.client_request_timeout(Duration::from_millis(n as u64)) } - Timeout::Seconds(n) => self.client_disconnect_timeout(Duration::from_secs(n as u64)), + Timeout::Seconds(n) => self.client_request_timeout(Duration::from_secs(n as u64)), }; self = match settings.actix.client_shutdown { diff --git a/src/actix_settings/parse.rs.html b/src/actix_settings/parse.rs.html index 4bfb92bce..7f769fa00 100644 --- a/src/actix_settings/parse.rs.html +++ b/src/actix_settings/parse.rs.html @@ -38,11 +38,15 @@ 36 37 38 +39 +40
use std::{path::PathBuf, str::FromStr}; use crate::AtError; +/// A specialized `FromStr` trait that returns [`AtError`] errors pub trait Parse: Sized { + /// Parse `Self` from `string`. fn parse(string: &str) -> Result<Self, AtError>; } diff --git a/src/actix_settings/settings/address.rs.html b/src/actix_settings/settings/address.rs.html index 3222e0600..bebd52a72 100644 --- a/src/actix_settings/settings/address.rs.html +++ b/src/actix_settings/settings/address.rs.html @@ -89,6 +89,10 @@ 87 88 89 +90 +91 +92 +93
use once_cell::sync::Lazy; use regex::Regex; use serde::Deserialize; @@ -128,9 +132,13 @@ .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, } diff --git a/src/actix_settings/settings/backlog.rs.html b/src/actix_settings/settings/backlog.rs.html index 0b958d946..8d1f7a5d4 100644 --- a/src/actix_settings/settings/backlog.rs.html +++ b/src/actix_settings/settings/backlog.rs.html @@ -59,15 +59,37 @@ 57 58 59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70
use std::fmt; 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), } diff --git a/src/actix_settings/settings/keep_alive.rs.html b/src/actix_settings/settings/keep_alive.rs.html index 646c31fc0..7464ff354 100644 --- a/src/actix_settings/settings/keep_alive.rs.html +++ b/src/actix_settings/settings/keep_alive.rs.html @@ -82,6 +82,19 @@ 80 81 82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95
use std::fmt; use once_cell::sync::Lazy; @@ -90,11 +103,24 @@ 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), } diff --git a/src/actix_settings/settings/max_connection_rate.rs.html b/src/actix_settings/settings/max_connection_rate.rs.html index ab6118917..0c836fe0e 100644 --- a/src/actix_settings/settings/max_connection_rate.rs.html +++ b/src/actix_settings/settings/max_connection_rate.rs.html @@ -59,15 +59,31 @@ 57 58 59 +60 +61 +62 +63 +64 +65 +66 +67
use std::fmt; 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), } diff --git a/src/actix_settings/settings/max_connections.rs.html b/src/actix_settings/settings/max_connections.rs.html index c92103c5c..7776dcd99 100644 --- a/src/actix_settings/settings/max_connections.rs.html +++ b/src/actix_settings/settings/max_connections.rs.html @@ -59,15 +59,31 @@ 57 58 59 +60 +61 +62 +63 +64 +65 +66 +67
use std::fmt; 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), } diff --git a/src/actix_settings/settings/mod.rs.html b/src/actix_settings/settings/mod.rs.html index 32f55e6b1..c95f5fa5c 100644 --- a/src/actix_settings/settings/mod.rs.html +++ b/src/actix_settings/settings/mod.rs.html @@ -40,6 +40,31 @@ 38 39 40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65
use serde::Deserialize; mod address; @@ -66,18 +91,43 @@ #[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, }
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, } diff --git a/src/actix_settings/settings/num_workers.rs.html b/src/actix_settings/settings/num_workers.rs.html index 6f7cb5a42..6686ef0f4 100644 --- a/src/actix_settings/settings/num_workers.rs.html +++ b/src/actix_settings/settings/num_workers.rs.html @@ -59,15 +59,29 @@ 57 58 59 +60 +61 +62 +63 +64 +65 +66
use std::fmt; 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), } diff --git a/src/actix_settings/settings/timeout.rs.html b/src/actix_settings/settings/timeout.rs.html index 9ac0dd584..12eafc005 100644 --- a/src/actix_settings/settings/timeout.rs.html +++ b/src/actix_settings/settings/timeout.rs.html @@ -88,6 +88,16 @@ 86 87 88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98
use std::fmt; use once_cell::sync::Lazy; @@ -96,10 +106,16 @@ 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), } @@ -124,18 +140,22 @@ }) } } + 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), } } diff --git a/src/actix_settings/settings/tls.rs.html b/src/actix_settings/settings/tls.rs.html index 7fbdff2dd..86e842549 100644 --- a/src/actix_settings/settings/tls.rs.html +++ b/src/actix_settings/settings/tls.rs.html @@ -11,15 +11,29 @@ 9 10 11 +12 +13 +14 +15 +16 +17 +18
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, }