laminar_core/
error_codes.rs

1//! LaminarDB structured error code registry.
2//!
3//! Every error in LaminarDB carries a stable `LDB-NNNN` code that is:
4//! - Present in the error message (grep-able in logs)
5//! - Present in the source code (grep-able in code)
6//! - Stable across versions (codes are never reused)
7//!
8//! # Code Ranges
9//!
10//! | Range | Category |
11//! |-------|----------|
12//! | `LDB-0xxx` | General / configuration |
13//! | `LDB-1xxx` | SQL parsing & validation |
14//! | `LDB-2xxx` | Window / watermark operations |
15//! | `LDB-3xxx` | Join operations |
16//! | `LDB-4xxx` | Serialization / state |
17//! | `LDB-5xxx` | Connector / I/O |
18//! | `LDB-6xxx` | Checkpoint / recovery |
19//! | `LDB-7xxx` | DataFusion / Arrow interop |
20//! | `LDB-8xxx` | Internal / should-not-happen |
21//!
22//! This module is the canonical registry for all error code ranges.
23//! Downstream crates (`laminar-sql`, `laminar-db`, etc.) re-export from here.
24
25// ── General / Configuration (LDB-0xxx) ──
26
27/// Invalid configuration value.
28pub const INVALID_CONFIG: &str = "LDB-0001";
29/// Missing required configuration key.
30pub const MISSING_CONFIG: &str = "LDB-0002";
31/// Unresolved config variable (e.g. `${VAR}` placeholder).
32pub const UNRESOLVED_CONFIG_VAR: &str = "LDB-0003";
33/// Database is shut down.
34pub const SHUTDOWN: &str = "LDB-0004";
35/// Invalid operation for the current state.
36pub const INVALID_OPERATION: &str = "LDB-0005";
37/// Schema mismatch between Rust type and SQL definition.
38pub const SCHEMA_MISMATCH: &str = "LDB-0006";
39
40// ── SQL Parsing & Validation (LDB-1xxx) ──
41
42/// Unsupported SQL syntax.
43pub const SQL_UNSUPPORTED: &str = "LDB-1001";
44/// Query planning failed.
45pub const SQL_PLANNING_FAILED: &str = "LDB-1002";
46/// Column not found.
47pub const SQL_COLUMN_NOT_FOUND: &str = "LDB-1100";
48/// Table or source not found.
49pub const SQL_TABLE_NOT_FOUND: &str = "LDB-1101";
50/// Type mismatch.
51pub const SQL_TYPE_MISMATCH: &str = "LDB-1200";
52
53// ── Window / Watermark (LDB-2xxx) ──
54
55/// Watermark required for this operation.
56pub const WATERMARK_REQUIRED: &str = "LDB-2001";
57/// Invalid window specification.
58pub const WINDOW_INVALID: &str = "LDB-2002";
59/// Window size must be positive.
60pub const WINDOW_SIZE_INVALID: &str = "LDB-2003";
61/// Late data rejected by window policy.
62pub const LATE_DATA_REJECTED: &str = "LDB-2004";
63
64// ── Join (LDB-3xxx) ──
65
66/// Join key column not found or invalid.
67pub const JOIN_KEY_MISSING: &str = "LDB-3001";
68/// Time bound required for stream-stream join.
69pub const JOIN_TIME_BOUND_MISSING: &str = "LDB-3002";
70/// Temporal join requires a primary key on the right-side table.
71pub const TEMPORAL_JOIN_NO_PK: &str = "LDB-3003";
72/// Unsupported join type for streaming queries.
73pub const JOIN_TYPE_UNSUPPORTED: &str = "LDB-3004";
74
75// ── Serialization / State (LDB-4xxx) ──
76
77/// State serialization failed for an operator.
78pub const SERIALIZATION_FAILED: &str = "LDB-4001";
79/// State deserialization failed for an operator.
80pub const DESERIALIZATION_FAILED: &str = "LDB-4002";
81/// JSON parse error (connector config, CDC payload, etc.).
82pub const JSON_PARSE_ERROR: &str = "LDB-4003";
83/// Base64 decode error (inline checkpoint state).
84pub const BASE64_DECODE_ERROR: &str = "LDB-4004";
85/// State store key not found.
86pub const STATE_KEY_MISSING: &str = "LDB-4005";
87/// State corruption detected (checksum mismatch, invalid data).
88pub const STATE_CORRUPTION: &str = "LDB-4006";
89
90// ── Connector / I/O (LDB-5xxx) ──
91
92/// Connector failed to establish a connection.
93pub const CONNECTOR_CONNECTION_FAILED: &str = "LDB-5001";
94/// Connector authentication failed.
95pub const CONNECTOR_AUTH_FAILED: &str = "LDB-5002";
96/// Connector read error.
97pub const CONNECTOR_READ_ERROR: &str = "LDB-5003";
98/// Connector write error.
99pub const CONNECTOR_WRITE_ERROR: &str = "LDB-5004";
100/// Connector configuration error.
101pub const CONNECTOR_CONFIG_ERROR: &str = "LDB-5005";
102/// Source not found.
103pub const SOURCE_NOT_FOUND: &str = "LDB-5010";
104/// Sink not found.
105pub const SINK_NOT_FOUND: &str = "LDB-5011";
106/// Source already exists.
107pub const SOURCE_ALREADY_EXISTS: &str = "LDB-5012";
108/// Sink already exists.
109pub const SINK_ALREADY_EXISTS: &str = "LDB-5013";
110/// Connector serde (serialization/deserialization) error.
111pub const CONNECTOR_SERDE_ERROR: &str = "LDB-5020";
112/// Schema inference or compatibility error.
113pub const CONNECTOR_SCHEMA_ERROR: &str = "LDB-5021";
114/// Exactly-once requires all sources to support replay.
115pub const EXACTLY_ONCE_NON_REPLAYABLE: &str = "LDB-5030";
116/// Exactly-once requires all sinks to support exactly-once semantics.
117pub const EXACTLY_ONCE_SINK_UNSUPPORTED: &str = "LDB-5031";
118/// Exactly-once requires checkpointing to be enabled.
119pub const EXACTLY_ONCE_NO_CHECKPOINT: &str = "LDB-5032";
120/// Mixed delivery capabilities — some sources are non-replayable.
121pub const MIXED_DELIVERY_CAPABILITIES: &str = "LDB-5033";
122
123// ── Checkpoint / Recovery (LDB-6xxx) ──
124
125/// Checkpoint creation failed.
126pub const CHECKPOINT_FAILED: &str = "LDB-6001";
127/// Checkpoint not found.
128pub const CHECKPOINT_NOT_FOUND: &str = "LDB-6002";
129/// Checkpoint recovery failed.
130pub const RECOVERY_FAILED: &str = "LDB-6003";
131/// Sink rollback failed during checkpoint abort.
132pub const SINK_ROLLBACK_FAILED: &str = "LDB-6004";
133/// WAL (write-ahead log) error.
134pub const WAL_ERROR: &str = "LDB-6005";
135/// WAL entry has invalid length (possible corruption).
136pub const WAL_INVALID_LENGTH: &str = "LDB-6006";
137/// WAL checksum mismatch.
138pub const WAL_CHECKSUM_MISMATCH: &str = "LDB-6007";
139/// Checkpoint manifest persistence failed.
140pub const MANIFEST_PERSIST_FAILED: &str = "LDB-6008";
141/// Checkpoint prune (old checkpoint cleanup) failed.
142pub const CHECKPOINT_PRUNE_FAILED: &str = "LDB-6009";
143/// Sidecar state data missing or corrupted.
144pub const SIDECAR_CORRUPTION: &str = "LDB-6010";
145/// Source offset metadata missing during recovery.
146pub const OFFSET_METADATA_MISSING: &str = "LDB-6011";
147
148// ── DataFusion / Arrow Interop (LDB-7xxx) ──
149
150/// Query execution failed (`DataFusion` engine error).
151/// Note: the SQL layer uses `LDB-9001` for execution failures visible to users;
152/// `LDB-7001` is for internal `DataFusion` interop issues.
153pub const QUERY_EXECUTION_FAILED: &str = "LDB-7001";
154/// Arrow schema or record batch error.
155pub const ARROW_ERROR: &str = "LDB-7002";
156/// `DataFusion` plan optimization failed.
157pub const PLAN_OPTIMIZATION_FAILED: &str = "LDB-7003";
158
159// ── Internal / Should-Not-Happen (LDB-8xxx) ──
160
161/// Internal error — this is a bug.
162pub const INTERNAL: &str = "LDB-8001";
163/// Pipeline error (start/shutdown lifecycle).
164pub const PIPELINE_ERROR: &str = "LDB-8002";
165/// Materialized view error.
166pub const MATERIALIZED_VIEW_ERROR: &str = "LDB-8003";
167/// Query pipeline error (stream execution context).
168pub const QUERY_PIPELINE_ERROR: &str = "LDB-8004";
169/// No compiled projection or cached plan for pre-aggregation query.
170pub const NO_COMPILED_PROJECTION: &str = "LDB-8050";
171
172// ── Ring 0 Hot Path Errors ──
173
174/// Ring 0 error — no heap allocation, no formatting on construction.
175///
176/// Only formatted when actually displayed (which happens outside Ring 0).
177/// Uses `Copy` and `repr(u16)` for zero-cost error reporting via counters.
178#[derive(Debug, Clone, Copy, PartialEq, Eq)]
179#[repr(u16)]
180pub enum HotPathError {
181    /// Event arrived after watermark — dropped.
182    LateEvent = 0x0001,
183    /// State store key not found.
184    StateKeyMissing = 0x0002,
185    /// Downstream backpressure — event buffered.
186    Backpressure = 0x0003,
187    /// Serialization buffer overflow.
188    SerializationOverflow = 0x0004,
189    /// Record batch schema does not match expected.
190    SchemaMismatch = 0x0005,
191    /// Aggregate state corruption detected.
192    AggregateStateCorruption = 0x0006,
193    /// Queue is full — cannot push event.
194    QueueFull = 0x0007,
195    /// Channel is closed/disconnected.
196    ChannelClosed = 0x0008,
197}
198
199impl HotPathError {
200    /// Returns a static error message. Cost: one match. No allocation.
201    #[must_use]
202    pub const fn message(self) -> &'static str {
203        match self {
204            Self::LateEvent => "Event arrived after watermark; dropped",
205            Self::StateKeyMissing => "State key not found in store",
206            Self::Backpressure => "Downstream backpressure; event buffered",
207            Self::SerializationOverflow => "Serialization buffer capacity exceeded",
208            Self::SchemaMismatch => "Record batch schema does not match expected",
209            Self::AggregateStateCorruption => "Aggregate state checksum mismatch detected",
210            Self::QueueFull => "Queue is full; cannot push event",
211            Self::ChannelClosed => "Channel is closed or disconnected",
212        }
213    }
214
215    /// Numeric code for metrics counters. Zero-cost.
216    #[must_use]
217    pub const fn code(self) -> u16 {
218        self as u16
219    }
220
221    /// Returns the `LDB-NNNN` error code string for this hot path error.
222    #[must_use]
223    pub const fn ldb_code(self) -> &'static str {
224        match self {
225            Self::LateEvent => LATE_DATA_REJECTED,
226            Self::StateKeyMissing => STATE_KEY_MISSING,
227            Self::Backpressure => "LDB-8010",
228            Self::SerializationOverflow => SERIALIZATION_FAILED,
229            Self::SchemaMismatch => SCHEMA_MISMATCH,
230            Self::AggregateStateCorruption => STATE_CORRUPTION,
231            Self::QueueFull => "LDB-8011",
232            Self::ChannelClosed => "LDB-8012",
233        }
234    }
235}
236
237impl std::fmt::Display for HotPathError {
238    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
239        write!(f, "[{}] {}", self.ldb_code(), self.message())
240    }
241}
242
243impl std::error::Error for HotPathError {}
244
245#[cfg(test)]
246mod tests {
247    use super::*;
248
249    #[test]
250    fn hot_path_error_is_copy_and_small() {
251        let e = HotPathError::LateEvent;
252        let e2 = e; // Copy
253        assert_eq!(e, e2);
254        assert_eq!(std::mem::size_of::<HotPathError>(), 2);
255    }
256
257    #[test]
258    fn hot_path_error_codes_are_nonzero() {
259        let variants = [
260            HotPathError::LateEvent,
261            HotPathError::StateKeyMissing,
262            HotPathError::Backpressure,
263            HotPathError::SerializationOverflow,
264            HotPathError::SchemaMismatch,
265            HotPathError::AggregateStateCorruption,
266            HotPathError::QueueFull,
267            HotPathError::ChannelClosed,
268        ];
269        for v in &variants {
270            assert!(v.code() > 0, "{v:?} has zero code");
271            assert!(!v.message().is_empty(), "{v:?} has empty message");
272            assert!(
273                v.ldb_code().starts_with("LDB-"),
274                "{v:?} has bad ldb_code: {}",
275                v.ldb_code()
276            );
277        }
278    }
279
280    #[test]
281    fn hot_path_error_display() {
282        let e = HotPathError::LateEvent;
283        let s = e.to_string();
284        assert!(s.starts_with("[LDB-"));
285        assert!(s.contains("watermark"));
286    }
287
288    #[test]
289    fn error_codes_are_stable_strings() {
290        assert_eq!(INVALID_CONFIG, "LDB-0001");
291        assert_eq!(SERIALIZATION_FAILED, "LDB-4001");
292        assert_eq!(CHECKPOINT_FAILED, "LDB-6001");
293        assert_eq!(INTERNAL, "LDB-8001");
294    }
295}
296
297/// Severity level for warnings (schema inference, recovery, etc.).
298#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
299pub enum WarningSeverity {
300    /// Informational — operation succeeded but with caveats.
301    Info,
302    /// Warning — result may be inaccurate or degraded.
303    Warning,
304    /// Error — operation for this item failed; a fallback was used.
305    Error,
306}
laminar_core/error_codes.rs

laminar_core/
error_codes.rs
