Skip to main content

domain_status/status_server/
error.rs

1//! Lifecycle error types for the status server.
2//!
3//! [`StatusServerLifecycleError`] is returned by
4//! [`super::spawn_status_server`] and [`super::StatusServerHandle::shutdown`]
5//! so callers can branch on bind / serve / background-task failures
6//! without resorting to string matching against an opaque `anyhow::Error`.
7//!
8//! Note: the `super::` references are written as plain code spans rather than
9//! rustdoc intra-doc links because the parent `status_server` module is
10//! private; rustdoc's `private-intra-doc-links` lint (escalated to error by
11//! CI's `RUSTDOCFLAGS="-D warnings"` setting) would reject the bracketed
12//! `super::...` form.
13
14use thiserror::Error;
15
16/// Lifecycle errors for `spawn_status_server` and `StatusServerHandle::shutdown`.
17///
18/// Typed (rather than `anyhow::Error`) so library callers can branch on the
19/// failure mode (port already bound, server-loop crash, background-task
20/// panic) without parsing error messages.
21///
22/// Marked `#[non_exhaustive]` so adding new failure modes is not breaking.
23#[derive(Error, Debug)]
24#[non_exhaustive]
25pub enum StatusServerLifecycleError {
26    /// Failed to bind to the configured TCP port.
27    #[error("Failed to bind status server to port {port}")]
28    Bind {
29        /// The port that was being bound.
30        port: u16,
31        /// The underlying I/O error.
32        #[source]
33        source: std::io::Error,
34    },
35
36    /// Axum's `serve` loop returned an error after the server started.
37    #[error("Status server error during serve")]
38    Serve(#[source] std::io::Error),
39
40    /// The background `tokio::spawn` task panicked or was cancelled.
41    #[error("Status server background task panicked")]
42    BackgroundTask(#[from] tokio::task::JoinError),
43}