Skip to main content

kafka_client_engine/engine_host/
error.rs

1//! Stable startup failures and internal terminal host diagnostics.
2
3use std::fmt;
4
5use crate::{
6    config::EngineConfigError, consumer::AssignedConsumerOwnerBuildError, driver::DriverOwnerError,
7    producer::ProducerHostStartError,
8};
9
10mod host;
11mod host_display;
12#[cfg(test)]
13mod host_display_test;
14#[cfg(test)]
15mod host_test;
16
17pub(crate) use host::EngineHostError;
18
19/// Stable category for engine startup failure.
20#[derive(Clone, Copy, Debug, Eq, PartialEq)]
21pub enum EngineStartErrorKind {
22    /// Engine-owned configuration is invalid.
23    Configuration,
24    /// The embedded driver could not be acquired.
25    Driver,
26    /// Bounded producer resources could not be acquired.
27    Producer,
28    /// Bounded admin resources could not be acquired.
29    Admin,
30    /// Bounded direct-consumer resources could not be acquired.
31    Consumer,
32    /// The native engine host thread could not start.
33    HostThread,
34    /// Startup ownership could not be handed to the host thread.
35    HostHandoff,
36}
37
38/// Failure before an engine handle can become observable.
39#[derive(Debug)]
40pub struct EngineStartError {
41    kind: EngineStartErrorKind,
42    detail: String,
43}
44
45impl EngineStartError {
46    /// Returns the stable startup-failure category.
47    pub const fn kind(&self) -> EngineStartErrorKind {
48        self.kind
49    }
50
51    pub(crate) fn configuration(error: EngineConfigError) -> Self {
52        Self::new(
53            EngineStartErrorKind::Configuration,
54            format!("invalid engine configuration: {error:?}"),
55        )
56    }
57
58    pub(super) fn driver(error: &DriverOwnerError) -> Self {
59        Self::new(EngineStartErrorKind::Driver, error.to_string())
60    }
61
62    pub(super) fn producer(error: &ProducerHostStartError) -> Self {
63        Self::new(EngineStartErrorKind::Producer, error.to_string())
64    }
65
66    pub(super) fn admin_notifier(error: &std::io::Error) -> Self {
67        Self::new(
68            EngineStartErrorKind::Admin,
69            format!("failed to start shared admin completion notifier: {error}"),
70        )
71    }
72
73    pub(super) fn assigned_consumer_notifier(error: &std::io::Error) -> Self {
74        Self::new(
75            EngineStartErrorKind::Consumer,
76            format!("failed to start assigned-consumer completion notifier: {error}"),
77        )
78    }
79
80    pub(super) fn assigned_consumer(error: AssignedConsumerOwnerBuildError) -> Self {
81        Self::new(
82            EngineStartErrorKind::Consumer,
83            format!("failed to start assigned consumer: {error:?}"),
84        )
85    }
86
87    pub(super) fn group_consumer(error: &std::io::Error) -> Self {
88        Self::new(
89            EngineStartErrorKind::Consumer,
90            format!("failed to start group-consumer registry: {error}"),
91        )
92    }
93
94    pub(super) fn transaction_notifier(error: &std::io::Error) -> Self {
95        Self::new(
96            EngineStartErrorKind::Producer,
97            format!("failed to start transaction completion notifier: {error}"),
98        )
99    }
100
101    pub(super) fn host_thread(error: &std::io::Error) -> Self {
102        Self::new(
103            EngineStartErrorKind::HostThread,
104            format!("failed to start engine host thread: {error}"),
105        )
106    }
107
108    pub(super) fn handoff() -> Self {
109        Self::new(
110            EngineStartErrorKind::HostHandoff,
111            "engine host stopped before accepting startup ownership".to_owned(),
112        )
113    }
114
115    fn new(kind: EngineStartErrorKind, detail: String) -> Self {
116        Self { kind, detail }
117    }
118}
119
120impl fmt::Display for EngineStartError {
121    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
122        formatter.write_str(&self.detail)
123    }
124}
125
126impl std::error::Error for EngineStartError {}
127
128/// Retained failure from explicit terminal engine shutdown.
129#[derive(Clone, Debug)]
130pub struct EngineShutdownError {
131    kind: EngineShutdownErrorKind,
132    detail: String,
133}
134
135impl EngineShutdownError {
136    pub(crate) fn host(error: &EngineHostError) -> Self {
137        Self {
138            kind: EngineShutdownErrorKind::Host,
139            detail: error.to_string(),
140        }
141    }
142
143    pub(crate) fn notifier_thread() -> Self {
144        Self {
145            kind: EngineShutdownErrorKind::NotifierThread,
146            detail: "shutdown was requested from the completion notifier; terminal cleanup \
147                     continues after the callback returns"
148                .to_owned(),
149        }
150    }
151
152    /// Returns the stable shutdown-failure category.
153    pub const fn kind(&self) -> EngineShutdownErrorKind {
154        self.kind
155    }
156}
157
158impl fmt::Display for EngineShutdownError {
159    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
160        formatter.write_str(&self.detail)
161    }
162}
163
164impl std::error::Error for EngineShutdownError {}
165
166/// Stable category for an engine shutdown report.
167#[derive(Clone, Copy, Debug, Eq, PartialEq)]
168pub enum EngineShutdownErrorKind {
169    /// Host or cleanup execution failed before terminal shutdown.
170    Host,
171    /// A notifier callback initiated shutdown and cannot wait for itself.
172    NotifierThread,
173}