qail_core/
error.rs

1//! Error types for QAIL.
2
3/// Error types for QAIL operations.
4#[derive(Debug)]
5pub enum QailError {
6    /// Failed to parse the QAIL query string.
7    Parse {
8        /// Byte offset of the error.
9        position: usize,
10        /// Human-readable error message.
11        message: String,
12    },
13
14    /// Invalid action (must be get, set, del, or add).
15    InvalidAction(String),
16
17    /// Required syntax symbol is missing.
18    MissingSymbol {
19        /// The missing symbol.
20        symbol: &'static str,
21        /// Description of the expected symbol.
22        description: &'static str,
23    },
24
25    /// Invalid operator in expression.
26    InvalidOperator(String),
27
28    /// Invalid value in expression.
29    InvalidValue(String),
30
31    /// Database-layer error.
32    Database(String),
33
34    /// Connection-layer error.
35    Connection(String),
36
37    /// Execution-layer error.
38    Execution(String),
39
40    /// Validation error.
41    Validation(String),
42
43    /// Configuration error.
44    Config(String),
45
46    /// I/O error.
47    Io(std::io::Error),
48}
49
50impl QailError {
51    /// Create a parse error at the given position.
52    pub fn parse(position: usize, message: impl Into<String>) -> Self {
53        Self::Parse {
54            position,
55            message: message.into(),
56        }
57    }
58
59    /// Create a missing symbol error.
60    pub fn missing(symbol: &'static str, description: &'static str) -> Self {
61        Self::MissingSymbol {
62            symbol,
63            description,
64        }
65    }
66}
67
68impl std::fmt::Display for QailError {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        match self {
71            Self::Parse { position, message } => {
72                write!(f, "Parse error at position {position}: {message}")
73            }
74            Self::InvalidAction(action) => {
75                write!(
76                    f,
77                    "Invalid action: '{action}'. Expected: get, set, del, or add"
78                )
79            }
80            Self::MissingSymbol {
81                symbol,
82                description,
83            } => {
84                write!(f, "Missing required symbol: {symbol} ({description})")
85            }
86            Self::InvalidOperator(op) => write!(f, "Invalid operator: '{op}'"),
87            Self::InvalidValue(value) => write!(f, "Invalid value: {value}"),
88            Self::Database(msg) => write!(f, "Database error: {msg}"),
89            Self::Connection(msg) => write!(f, "Connection error: {msg}"),
90            Self::Execution(msg) => write!(f, "Execution error: {msg}"),
91            Self::Validation(msg) => write!(f, "Validation error: {msg}"),
92            Self::Config(msg) => write!(f, "Configuration error: {msg}"),
93            Self::Io(err) => write!(f, "IO error: {err}"),
94        }
95    }
96}
97
98impl std::error::Error for QailError {
99    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
100        match self {
101            Self::Io(err) => Some(err),
102            _ => None,
103        }
104    }
105}
106
107impl From<std::io::Error> for QailError {
108    fn from(value: std::io::Error) -> Self {
109        Self::Io(value)
110    }
111}
112
113/// Result type alias for QAIL operations.
114pub type QailResult<T> = Result<T, QailError>;
115
116/// Error type for query-builder operations.
117#[derive(Debug, Clone, PartialEq, Eq)]
118pub enum QailBuildError {
119    /// RLS insertion cannot safely align positional values without columns.
120    RlsInsertRequiresExplicitColumns {
121        /// Target table being scoped.
122        table: String,
123        /// Tenant column that would be injected.
124        tenant_column: String,
125    },
126
127    /// RLS-protected updates cannot rewrite the tenant column.
128    RlsTenantColumnMutationDenied {
129        /// Target table being scoped.
130        table: String,
131        /// Tenant column that was assigned.
132        tenant_column: String,
133    },
134
135    /// RLS-protected MERGE query sources need a tenant projection for safe row classification.
136    RlsMergeSourceTenantProjectionRequired {
137        /// Target table being scoped.
138        table: String,
139        /// Tenant column that must be projected by the source query.
140        tenant_column: String,
141    },
142
143    /// `with_rls` was called before the process declared its scope registries.
144    ///
145    /// Call `qail_core::rls::init_scope_registries(&schema)` (AST injection
146    /// from schema metadata) or `declare_policy_only_isolation(reason)` (DB
147    /// policies only) at application startup.
148    RlsRegistryUninitialized {
149        /// Table the query targeted.
150        table: String,
151    },
152
153    /// A scope registry could not be read (poisoned lock) while scoping.
154    ///
155    /// Fail-closed: "cannot read the registry" must never be interpreted as
156    /// "table is unregistered", or a late poison would disable every
157    /// tenant/owner predicate in the process at once.
158    RlsRegistryUnavailable {
159        /// Table whose registration was being looked up.
160        table: String,
161        /// Underlying registry error.
162        reason: String,
163    },
164
165    /// A registered RLS table was scoped with a context lacking the scope it requires.
166    ///
167    /// Fail-closed: a tenant-registered table needs a tenant (or global)
168    /// context; an owner-registered table needs an authenticated user.
169    RlsScopeMissing {
170        /// Target table being scoped.
171        table: String,
172        /// The scope that is required (`"tenant"` or `"user"`).
173        scope: &'static str,
174        /// The column the scope would have been injected on.
175        column: String,
176    },
177
178    /// A joined RLS relation cannot be scoped through this join kind.
179    ///
180    /// RIGHT/FULL joins reintroduce rows the ON predicate rejects, so a scope
181    /// predicate on the joined side does not isolate.
182    RlsJoinKindUnsupported {
183        /// Joined relation that required scoping.
184        table: String,
185        /// The join kind in use.
186        join_kind: String,
187    },
188
189    /// Owner-scoped MERGE is not supported by AST injection.
190    RlsOwnerMergeUnsupported {
191        /// Target table being scoped.
192        table: String,
193        /// Owner column registered for the table.
194        owner_column: String,
195    },
196
197    /// Runtime relation registry lock failed.
198    RelationRegistryLock(String),
199
200    /// Relation metadata has more than one possible join edge.
201    AmbiguousRelation {
202        /// Source table.
203        from_table: String,
204        /// Related table.
205        to_table: String,
206        /// Number of registered foreign-key candidates.
207        foreign_key_count: usize,
208    },
209
210    /// No schema relation could be found for an implicit join.
211    RelationNotFound {
212        /// Current table.
213        from_table: String,
214        /// Requested related table.
215        to_table: String,
216    },
217}
218
219impl std::fmt::Display for QailBuildError {
220    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
221        match self {
222            Self::RlsInsertRequiresExplicitColumns {
223                table,
224                tenant_column,
225            } => write!(
226                f,
227                "with_rls requires explicit columns for positional INSERT payloads on table '{table}' (tenant column '{tenant_column}')"
228            ),
229            Self::RlsTenantColumnMutationDenied {
230                table,
231                tenant_column,
232            } => write!(
233                f,
234                "with_rls rejects tenant column mutation on table '{table}' (tenant column '{tenant_column}')"
235            ),
236            Self::RlsRegistryUninitialized { table } => write!(
237                f,
238                "with_rls on table '{table}' before scope registries were declared — call qail_core::rls::init_scope_registries(&schema) or declare_policy_only_isolation(reason) at startup"
239            ),
240            Self::RlsRegistryUnavailable { table, reason } => write!(
241                f,
242                "with_rls on table '{table}' cannot read the scope registry ({reason}) — refusing to run unscoped"
243            ),
244            Self::RlsScopeMissing {
245                table,
246                scope,
247                column,
248            } => write!(
249                f,
250                "with_rls on table '{table}' requires a {scope} scope (column '{column}') but the context carries none — refusing to run unscoped"
251            ),
252            Self::RlsJoinKindUnsupported { table, join_kind } => write!(
253                f,
254                "with_rls cannot isolate RLS table '{table}' joined via {join_kind}; use INNER/LEFT/LATERAL or a CTE"
255            ),
256            Self::RlsOwnerMergeUnsupported {
257                table,
258                owner_column,
259            } => write!(
260                f,
261                "with_rls cannot owner-scope MERGE on table '{table}' (owner column '{owner_column}'); use with_rls_policy and a DB policy"
262            ),
263            Self::RlsMergeSourceTenantProjectionRequired {
264                table,
265                tenant_column,
266            } => write!(
267                f,
268                "with_rls requires MERGE query sources for table '{table}' to project tenant column '{tenant_column}'"
269            ),
270            Self::RelationRegistryLock(msg) => write!(f, "Relation registry lock error: {msg}"),
271            Self::AmbiguousRelation {
272                from_table,
273                to_table,
274                foreign_key_count,
275            } => write!(
276                f,
277                "Ambiguous relation between '{from_table}' and '{to_table}': {foreign_key_count} foreign keys registered. Use an explicit join condition."
278            ),
279            Self::RelationNotFound {
280                from_table,
281                to_table,
282            } => write!(
283                f,
284                "No relation found between '{from_table}' and '{to_table}'. Define a ref: in schema.qail or use load_schema_relations() first."
285            ),
286        }
287    }
288}
289
290impl std::error::Error for QailBuildError {}
291
292/// Result type alias for query-builder operations.
293pub type QailBuildResult<T> = Result<T, QailBuildError>;
294
295#[cfg(test)]
296mod tests {
297    use super::*;
298
299    #[test]
300    fn test_error_display() {
301        let err = QailError::parse(5, "unexpected character");
302        assert_eq!(
303            err.to_string(),
304            "Parse error at position 5: unexpected character"
305        );
306    }
307}
qail_core/error.rs

qail_core/
error.rs
