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}