web-faith 1.0.0

//! Building an agent a setting at a time.
//!
//! [`Agent::builder`] returns a builder whose setters mirror the option groups. A group is reached
//! through a closure, so one left alone is absent from the call rather than spelled out as absent:
//!
//! ```no_run
//! # use std::time::Duration;
//! # use web_faith::agent::Agent;
//! let agent = Agent::builder()
//!     .user_agent("YourApp/1.2.3")
//!     .timeout(|timeout| timeout.connect(Duration::from_secs(2)).build())
//!     .pool(|pool| pool.max_idle_per_host(8).build())
//!     .build()?;
//! # Ok::<(), web_faith::FaithError>(())
//! ```
//!
//! Durations are `Duration` here whatever unit the setting is carried in, and a setting left unset
//! takes its default. The setters are generated by `bon` from
//! [`AgentOptions`](crate::options::AgentOptions) and its groups, so
//! an option is declared once, as a field on [`AgentOptions`](crate::options::AgentOptions),
//! rather than once as a field and again as a setter.
//!
//! Two terminals: [`build`] validates and produces the agent, and [`into_options`] hands back the
//! options as they stand, for a caller assembling them to pass on rather than to use here.
//!
//! [`Agent::builder`]: crate::agent::Agent::builder
//! [`build`]: AgentOptionsBuilder::build
//! [`into_options`]: crate::options::AgentOptions::builder

// spec:AGENT

use crate::{agent::Agent, error::FaithError, options::agent_options_builder};

pub use crate::options::AgentOptionsBuilder;

/// The terminal that validates the options and builds the agent.
///
/// `bon`'s own finisher on [`AgentOptions`](crate::options::AgentOptions) is `into_options`,
/// which yields the options; this is
/// the one that yields an [`Agent`], so `Agent::builder()` reads to `build()` as the rest of the
/// API does. Every option is optional, so there is no state in which the builder is incomplete.
impl<S: agent_options_builder::State> AgentOptionsBuilder<S> {
	/// Validate what has been set and build the agent.
	pub fn build(self) -> Result<Agent, FaithError> {
		Agent::from_options(self.into_options())
	}
}