liminal_server/error.rs
1use std::net::SocketAddr;
2
3use crate::server::participant::ParticipantServiceFatal;
4
5/// Error taxonomy for standalone liminal server deployment failures.
6#[derive(Debug, thiserror::Error)]
7pub enum ServerError {
8 /// The configuration file could not be read or parsed.
9 #[error("configuration load failed: {message}")]
10 ConfigLoad { message: String },
11
12 /// The configuration file was read but failed semantic validation.
13 #[error("configuration validation failed: {message}")]
14 ConfigValidation { message: String },
15
16 /// The server could not bind its configured listener address.
17 #[error("listener bind failed for {address}: {source}")]
18 ListenerBind {
19 /// Address the server attempted to bind.
20 address: SocketAddr,
21 /// Underlying operating-system bind failure.
22 #[source]
23 source: std::io::Error,
24 },
25
26 /// The server listener failed while accepting an inbound connection.
27 #[error("listener accept failed: {message}")]
28 ListenerAccept { message: String },
29
30 /// Durable participant-incarnation startup or allocation failed before its
31 /// result could be published.
32 #[error("participant incarnation {phase} failed: {message}")]
33 ParticipantIncarnation {
34 /// Exact server seam that failed.
35 phase: &'static str,
36 /// Underlying durable or bounded-bridge diagnostic.
37 message: String,
38 },
39
40 /// A durable connection-fate Open could not be completed in this process.
41 ///
42 /// The normal runtime shutdown path returns this typed fatal only after it has
43 /// stopped both listeners and run the ordinary connection drain/flush sequence.
44 #[error("participant service fatal: {fatal}")]
45 ParticipantServiceFatal {
46 /// First process-wide post-Open failure; later failures cannot replace it.
47 fatal: ParticipantServiceFatal,
48 },
49
50 /// Startup found durable connection-fate work that the Decision A/C producer must complete
51 /// before listener or semantic-service publication.
52 #[error(
53 "participant startup requires recovery of {open_count} connection-fate Opens beginning at sequence {first_open_sequence}"
54 )]
55 ConnectionFateRecoveryRequired {
56 /// Number of replay-validated unmatched Opens.
57 open_count: usize,
58 /// Lowest unmatched Open sequence.
59 first_open_sequence: u64,
60 },
61
62 /// The durable server-incarnation namespace has no successor.
63 #[error("participant server-incarnation namespace is exhausted")]
64 ServerIncarnationExhausted,
65
66 /// Production participant startup restore failed: the durable
67 /// conversation streams could not be scanned or replayed, so the
68 /// server-scope capacity ledger cannot be made exact and the server
69 /// refuses to start over state it cannot account for.
70 #[error("participant startup restore failed: {message}")]
71 ParticipantStartupRestore {
72 /// Underlying durable, replay, or bridge diagnostic.
73 message: String,
74 },
75
76 /// The current durable server incarnation has no collision-free connection
77 /// ordinal left, so the accepted socket was not admitted.
78 #[error(
79 "connection incarnation exhausted for server incarnation {attempted_server_incarnation}"
80 )]
81 ConnectionIncarnationExhausted {
82 /// Server incarnation whose complete ordinal suffix was examined.
83 attempted_server_incarnation: u64,
84 },
85
86 /// A frame requested an operation the configured services profile does not
87 /// serve (e.g. ordinary publish/subscribe/conversation traffic against the
88 /// capability-scoped worker front door). Server-internal taxonomy, not wire
89 /// vocabulary: the connection process renders it as the operation's existing
90 /// typed error frame with this error's text as the message.
91 #[error("{operation} is not supported by the {profile} services profile")]
92 UnsupportedOperation {
93 /// Human-readable description of the refused operation.
94 operation: String,
95 /// The configured services profile that refused it.
96 profile: &'static str,
97 },
98
99 /// A server→client push reply slot was dropped before a correlated reply
100 /// arrived — the connection closed (the prompt worker-death signal). Distinct
101 /// from [`Self::PushReplyTimeout`] so consumers can tell a worker that DIED
102 /// (fast failover) from one that is merely SLOW, by type rather than message.
103 #[error(
104 "push correlation {correlation_id} did not complete: the connection closed before sending a correlated push reply"
105 )]
106 PushReplyDisconnected {
107 /// Correlation id of the push whose reply will never arrive.
108 correlation_id: u64,
109 },
110
111 /// A server→client push reply did not arrive within the awaiter's timeout —
112 /// the worker is still connected but did not reply in this wait quantum. This
113 /// is BENIGN: the reply slot survives untouched and the caller may re-arm
114 /// [`PushReplyAwaiter::receive`](crate::server::connection::PushReplyAwaiter::receive)
115 /// indefinitely. It is not a worker-death signal.
116 #[error(
117 "push correlation {correlation_id} did not complete: no correlated push reply arrived within the timeout"
118 )]
119 PushReplyTimeout {
120 /// Correlation id of the push whose wait quantum elapsed.
121 correlation_id: u64,
122 },
123
124 /// A server→client push carrying an explicit reply deadline (via
125 /// [`push_to_connection_with_deadline`](crate::server::connection::ConnectionSupervisor::push_to_connection_with_deadline))
126 /// reached that deadline before a correlated reply arrived. Unlike
127 /// [`Self::PushReplyTimeout`] this is TERMINAL: the reply slot has been
128 /// removed and its §5 `max_pending_pushes_per_connection` cap admission
129 /// released. Returned PROMPTLY once the deadline is due — a `receive` call
130 /// does not hold a due expiry until its caller's quantum ends, so the
131 /// terminal outcome is independent of how the caller polls. Distinct
132 /// variant so callers classify by type, not message.
133 #[error(
134 "push correlation {correlation_id} did not complete: its reply deadline passed before a correlated push reply arrived"
135 )]
136 PushReplyExpired {
137 /// Correlation id of the push whose reply deadline passed.
138 correlation_id: u64,
139 },
140
141 /// The server could not join the configured beamr distribution cluster.
142 #[error("cluster join failed: {message}")]
143 ClusterJoin { message: String },
144
145 /// Cluster state propagation through beamr distribution failed.
146 #[error("cluster sync failed: {message}")]
147 ClusterSync { message: String },
148
149 /// Graceful shutdown did not drain within the configured timeout.
150 #[error("shutdown timed out: {message}")]
151 ShutdownTimeout { message: String },
152
153 /// Durable state could not be flushed during graceful shutdown.
154 #[error("shutdown flush failed: {message}")]
155 ShutdownFlush { message: String },
156
157 /// The health endpoint failed to start or serve requests.
158 #[error("health endpoint failed: {message}")]
159 HealthEndpoint { message: String },
160
161 /// A new connection was refused because the configured `max_connections`
162 /// cap (§5) is already reached. The listener drops the freshly accepted
163 /// stream, refusing the connection, rather than admitting an unbounded fleet.
164 #[error(
165 "connection refused: the configured max_connections limit of {limit} live connections is reached"
166 )]
167 ConnectionLimitReached {
168 /// The configured `max_connections` cap that was hit.
169 limit: usize,
170 },
171
172 /// An admission-time per-connection cap (§5) refused an operation: too many
173 /// subscriptions, conversations, in-flight pushes, or pending conversation
174 /// replies on one connection. The connection process renders it as the
175 /// operation's existing typed error frame with this text as the message.
176 #[error("{operation} refused: the per-connection {cap} limit of {limit} is reached")]
177 ConnectionCapReached {
178 /// Human-readable description of the refused operation.
179 operation: String,
180 /// The name of the cap that refused it (a `limits.*` config key).
181 cap: &'static str,
182 /// The configured cap value that was hit.
183 limit: usize,
184 },
185}