Struct HealthCheckApiConfig 

pub struct HealthCheckApiConfig { /* private fields */ }

Health Check API configuration with domain invariants enforced at construction

The Health Check API is a minimal HTTP endpoint used by Docker and container orchestration tools to verify service health. It’s separate from the main HTTP API.

This type guarantees that any instance is valid according to domain rules:

• Bind address has a non-zero port
• If TLS proxy is enabled, a domain is configured
• If TLS proxy is enabled, bind address is not localhost

Construction

Use HealthCheckApiConfig::new() to create instances with validation:

use torrust_tracker_deployer_lib::domain::tracker::HealthCheckApiConfig;
use torrust_tracker_deployer_lib::shared::DomainName;

// Without TLS (typical for internal health checks)
let config = HealthCheckApiConfig::new(
    "127.0.0.1:1313".parse().unwrap(),
    None,
    false,
)?;

// With TLS for external monitoring (requires domain)
let tls_config = HealthCheckApiConfig::new(
    "0.0.0.0:1313".parse().unwrap(),
    Some(DomainName::new("health.example.com")?),
    true,
)?;

Invariants

The following invariants are enforced at construction time:

1. No dynamic ports: bind_address.port() != 0
2. TLS requires domain: use_tls_proxy == true implies domain.is_some()
3. No localhost with TLS: use_tls_proxy == true implies !is_localhost(bind_address)

Implementations

impl HealthCheckApiConfig

pub fn new( bind_address: SocketAddr, domain: Option<DomainName>, use_tls_proxy: bool, ) -> Result<Self, HealthCheckApiConfigError>

Creates a new Health Check API configuration with validation

This is the primary way to construct a HealthCheckApiConfig. All domain invariants are validated before the instance is created.

Arguments

• bind_address - Socket address to bind to (e.g., “127.0.0.1:1313”)
• domain - Optional domain for TLS certificate (required if use_tls_proxy is true)
• use_tls_proxy - Whether to enable TLS via Caddy reverse proxy

Errors

Returns HealthCheckApiConfigError if any invariant is violated:

• DynamicPortNotSupported - if port is 0
• TlsProxyRequiresDomain - if use_tls_proxy is true but domain is None
• LocalhostWithTls - if use_tls_proxy is true and bind_address is localhost

Examples

use torrust_tracker_deployer_lib::domain::tracker::HealthCheckApiConfig;
use torrust_tracker_deployer_lib::shared::DomainName;

// Basic configuration without TLS (typical)
let config = HealthCheckApiConfig::new(
    "127.0.0.1:1313".parse().unwrap(),
    None,
    false,
)?;

// Configuration with TLS for external monitoring
let tls_config = HealthCheckApiConfig::new(
    "0.0.0.0:1313".parse().unwrap(),
    Some(DomainName::new("health.example.com")?),
    true,
)?;

pub fn bind_address(&self) -> SocketAddr

Returns the bind address

pub fn domain(&self) -> Option<&DomainName>

Returns a reference to the domain, if configured

pub fn use_tls_proxy(&self) -> bool

Returns whether TLS proxy is enabled

pub fn uses_tls_proxy(&self) -> bool

Returns true if this API uses the TLS proxy

Alias for use_tls_proxy() for semantic clarity.

pub fn tls_domain(&self) -> Option<&str>

Returns the TLS domain as a string if TLS proxy is configured

Returns None if TLS is disabled, even if a domain is configured. This is useful for determining the effective TLS domain.

Trait Implementations

impl Clone for HealthCheckApiConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HealthCheckApiConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for HealthCheckApiConfig

Enables deserialization with validation through the constructor

This ensures that JSON deserialization also validates the config, maintaining the “always valid” invariant even for loaded data.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for HealthCheckApiConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for HealthCheckApiConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for HealthCheckApiConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for HealthCheckApiConfig

impl TryFrom<HealthCheckApiSection> for HealthCheckApiConfig

Converts from application DTO to domain type using TryFrom trait

This implementation follows the standard library convention for fallible conversions, enabling use of .try_into() and TryFrom::try_from().

Example

let section = HealthCheckApiSection {
    bind_address: "127.0.0.1:1313".to_string(),
    domain: None,
    use_tls_proxy: None,
};
let config: HealthCheckApiConfig = section.try_into()?;

type Error = CreateConfigError

The type returned in the event of a conversion error.

fn try_from(section: HealthCheckApiSection) -> Result<Self, Self::Error>

Performs the conversion.