liminal_server/error.rs
1use std::net::SocketAddr;
2
3/// Error taxonomy for standalone liminal server deployment failures.
4#[derive(Debug, thiserror::Error)]
5pub enum ServerError {
6 /// The configuration file could not be read or parsed.
7 #[error("configuration load failed: {message}")]
8 ConfigLoad { message: String },
9
10 /// The configuration file was read but failed semantic validation.
11 #[error("configuration validation failed: {message}")]
12 ConfigValidation { message: String },
13
14 /// The server could not bind its configured listener address.
15 #[error("listener bind failed for {address}: {source}")]
16 ListenerBind {
17 /// Address the server attempted to bind.
18 address: SocketAddr,
19 /// Underlying operating-system bind failure.
20 #[source]
21 source: std::io::Error,
22 },
23
24 /// The server listener failed while accepting an inbound connection.
25 #[error("listener accept failed: {message}")]
26 ListenerAccept { message: String },
27
28 /// A frame requested an operation the configured services profile does not
29 /// serve (e.g. ordinary publish/subscribe/conversation traffic against the
30 /// capability-scoped worker front door). Server-internal taxonomy, not wire
31 /// vocabulary: the connection process renders it as the operation's existing
32 /// typed error frame with this error's text as the message.
33 #[error("{operation} is not supported by the {profile} services profile")]
34 UnsupportedOperation {
35 /// Human-readable description of the refused operation.
36 operation: String,
37 /// The configured services profile that refused it.
38 profile: &'static str,
39 },
40
41 /// A server→client push reply slot was dropped before a correlated reply
42 /// arrived — the connection closed (the prompt worker-death signal). Distinct
43 /// from [`Self::PushReplyTimeout`] so consumers can tell a worker that DIED
44 /// (fast failover) from one that is merely SLOW, by type rather than message.
45 #[error(
46 "push correlation {correlation_id} did not complete: the connection closed before sending a correlated push reply"
47 )]
48 PushReplyDisconnected {
49 /// Correlation id of the push whose reply will never arrive.
50 correlation_id: u64,
51 },
52
53 /// A server→client push reply did not arrive within the awaiter's timeout —
54 /// the worker is still connected but did not reply in this wait quantum. This
55 /// is BENIGN: the reply slot survives untouched and the caller may re-arm
56 /// [`PushReplyAwaiter::receive`](crate::server::connection::PushReplyAwaiter::receive)
57 /// indefinitely. It is not a worker-death signal.
58 #[error(
59 "push correlation {correlation_id} did not complete: no correlated push reply arrived within the timeout"
60 )]
61 PushReplyTimeout {
62 /// Correlation id of the push whose wait quantum elapsed.
63 correlation_id: u64,
64 },
65
66 /// A server→client push carrying an explicit reply deadline (via
67 /// [`push_to_connection_with_deadline`](crate::server::connection::ConnectionSupervisor::push_to_connection_with_deadline))
68 /// reached that deadline before a correlated reply arrived. Unlike
69 /// [`Self::PushReplyTimeout`] this is TERMINAL: the reply slot has been
70 /// removed and its §5 `max_pending_pushes_per_connection` cap admission
71 /// released. Returned PROMPTLY once the deadline is due — a `receive` call
72 /// does not hold a due expiry until its caller's quantum ends, so the
73 /// terminal outcome is independent of how the caller polls. Distinct
74 /// variant so callers classify by type, not message.
75 #[error(
76 "push correlation {correlation_id} did not complete: its reply deadline passed before a correlated push reply arrived"
77 )]
78 PushReplyExpired {
79 /// Correlation id of the push whose reply deadline passed.
80 correlation_id: u64,
81 },
82
83 /// The server could not join the configured beamr distribution cluster.
84 #[error("cluster join failed: {message}")]
85 ClusterJoin { message: String },
86
87 /// Cluster state propagation through beamr distribution failed.
88 #[error("cluster sync failed: {message}")]
89 ClusterSync { message: String },
90
91 /// Graceful shutdown did not drain within the configured timeout.
92 #[error("shutdown timed out: {message}")]
93 ShutdownTimeout { message: String },
94
95 /// Durable state could not be flushed during graceful shutdown.
96 #[error("shutdown flush failed: {message}")]
97 ShutdownFlush { message: String },
98
99 /// The health endpoint failed to start or serve requests.
100 #[error("health endpoint failed: {message}")]
101 HealthEndpoint { message: String },
102
103 /// A new connection was refused because the configured `max_connections`
104 /// cap (§5) is already reached. The listener drops the freshly accepted
105 /// stream, refusing the connection, rather than admitting an unbounded fleet.
106 #[error(
107 "connection refused: the configured max_connections limit of {limit} live connections is reached"
108 )]
109 ConnectionLimitReached {
110 /// The configured `max_connections` cap that was hit.
111 limit: usize,
112 },
113
114 /// An admission-time per-connection cap (§5) refused an operation: too many
115 /// subscriptions, conversations, in-flight pushes, or pending conversation
116 /// replies on one connection. The connection process renders it as the
117 /// operation's existing typed error frame with this text as the message.
118 #[error("{operation} refused: the per-connection {cap} limit of {limit} is reached")]
119 ConnectionCapReached {
120 /// Human-readable description of the refused operation.
121 operation: String,
122 /// The name of the cap that refused it (a `limits.*` config key).
123 cap: &'static str,
124 /// The configured cap value that was hit.
125 limit: usize,
126 },
127}