1use std::borrow::Cow;
4use std::error::Error as StdError;
5use std::fmt;
6
7use thiserror::Error;
8
9use crate::blob::ContentRef;
10use crate::capability::StorageCapability;
11
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum WriterTaskRequestState {
21 NotStarted,
23 TransactionRolledBack,
28 SideEffectsUnknown,
32}
33
34#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
36#[serde(rename_all = "snake_case")]
37pub enum SqliteWriteStage {
38 #[serde(rename = "sqlite_begin_busy")]
39 Begin,
40 #[serde(rename = "sqlite_statement_failure")]
41 Statement,
42 #[serde(rename = "sqlite_commit_failure")]
43 Commit,
44}
45
46impl SqliteWriteStage {
47 pub const fn as_str(self) -> &'static str {
48 match self {
49 Self::Begin => "sqlite_begin_busy",
50 Self::Statement => "sqlite_statement_failure",
51 Self::Commit => "sqlite_commit_failure",
52 }
53 }
54}
55
56#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
58pub struct SqliteWriteFailure {
59 pub stage: SqliteWriteStage,
60 pub primary_code: i32,
61 pub extended_code: i32,
62 #[serde(default)]
64 pub settlement_unknown: bool,
65}
66
67impl fmt::Display for WriterTaskRequestState {
68 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69 f.write_str(match self {
70 Self::NotStarted => "not_started",
71 Self::TransactionRolledBack => "transaction_rolled_back",
72 Self::SideEffectsUnknown => "side_effects_unknown",
73 })
74 }
75}
76
77#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub enum CapacityUnavailablePhase {
80 Identity,
81 Lock,
82 LockContended,
83 Probe,
84}
85
86impl CapacityUnavailablePhase {
87 pub const fn as_str(self) -> &'static str {
88 match self {
89 Self::Identity => "identity",
90 Self::Lock => "lock",
91 Self::LockContended => "lock_contended",
92 Self::Probe => "probe",
93 }
94 }
95}
96
97impl fmt::Display for CapacityUnavailablePhase {
98 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99 f.write_str(self.as_str())
100 }
101}
102
103#[derive(Debug, Error)]
105pub enum StorageError {
106 #[error("{source}")]
107 SqliteWrite {
108 failure: SqliteWriteFailure,
109 #[source]
110 source: Box<StorageError>,
111 },
112 #[error("{capability:?} resource not found: {resource} ({key})")]
113 NotFound {
114 capability: StorageCapability,
115 resource: &'static str,
116 key: String,
117 },
118
119 #[error("{capability:?} resource already exists: {resource} ({key})")]
120 AlreadyExists {
121 capability: StorageCapability,
122 resource: &'static str,
123 key: String,
124 },
125
126 #[error("conflict in {capability:?} during {operation}: {message}")]
127 Conflict {
128 capability: StorageCapability,
129 operation: Cow<'static, str>,
130 message: String,
131 },
132
133 #[error("invalid input for {capability:?} during {operation}: {message}")]
134 InvalidInput {
135 capability: StorageCapability,
136 operation: Cow<'static, str>,
137 message: String,
138 },
139
140 #[error("write blocked: {matched}")]
143 SecretDetected {
144 capability: StorageCapability,
145 operation: Cow<'static, str>,
146 matched: Box<crate::secret_scan::SecretMatch>,
147 },
148
149 #[error("unsupported operation for {capability:?}: {operation} ({message})")]
150 Unsupported {
151 capability: StorageCapability,
152 operation: Cow<'static, str>,
153 message: String,
154 },
155
156 #[error(
161 "blob {content_ref} exceeds the {max_bytes}-byte read limit (observed at least {observed_at_least} bytes)"
162 )]
163 BlobTooLarge {
164 content_ref: ContentRef,
165 max_bytes: u64,
166 observed_at_least: u64,
167 },
168
169 #[error(
172 "blob {content_ref} metadata reports {metadata_bytes} bytes but the complete body contains {actual_bytes} bytes"
173 )]
174 BlobSizeMismatch {
175 content_ref: ContentRef,
176 metadata_bytes: u64,
177 actual_bytes: u64,
178 },
179
180 #[error("blob digest mismatch: expected {expected}, computed {actual}")]
183 BlobDigestMismatch {
184 expected: ContentRef,
185 actual: ContentRef,
186 },
187
188 #[error("pool failure during {operation}: {message}")]
189 Pool {
190 operation: Cow<'static, str>,
191 message: String,
192 },
193
194 #[error("timeout during {operation}")]
195 Timeout { operation: Cow<'static, str> },
196
197 #[error("admission timeout during {operation} after {timeout_ms}ms{pool}", pool = match .pool_identity {
203 Some(identity) => format!(" (pool: {identity})"),
204 None => String::new(),
205 })]
206 AdmissionTimeout {
207 operation: Cow<'static, str>,
208 timeout_ms: u64,
210 pool_identity: Option<String>,
212 },
213
214 #[error("sql transaction failure during {operation}: {message}")]
215 Transaction {
216 operation: Cow<'static, str>,
217 message: String,
218 },
219
220 #[error(
229 "cached read-only transaction exceeded the maximum read-transaction age \
230 ({max_age_secs}s) during {operation} and was rolled back; retry to open a fresh \
231 read snapshot"
232 )]
233 ReadTransactionAgeEvicted {
234 operation: Cow<'static, str>,
235 max_age_secs: u64,
236 },
237
238 #[error(
250 "cached read-only transaction exceeded the maximum read-transaction age \
251 ({max_age_secs}s) during {operation} but could not be cleanly rolled back \
252 ({message}); the connection was discarded, retry to open a fresh read snapshot"
253 )]
254 ReadTransactionAgeEvictionCleanupFailed {
255 operation: Cow<'static, str>,
256 max_age_secs: u64,
257 message: String,
258 },
259
260 #[error("serialization failure in {capability:?}: {message}")]
261 Serialization {
262 capability: StorageCapability,
263 message: String,
264 },
265
266 #[error("index maintenance failure in {capability:?}: {message}")]
267 IndexMaintenance {
268 capability: StorageCapability,
269 message: String,
270 },
271
272 #[error("backend driver error in {capability:?} during {operation}: {source}")]
273 Driver {
274 capability: StorageCapability,
275 operation: Cow<'static, str>,
276 #[source]
277 source: Box<dyn StdError + Send + Sync>,
278 },
279
280 #[error("write queue full: timed out after {timeout_ms}ms waiting for writer task capacity")]
285 WriteQueueFull { timeout_ms: u64 },
286
287 #[error(
292 "writer task could not begin within {timeout_ms}ms because SQLite remained busy; request was not executed"
293 )]
294 WriterTaskBusy { timeout_ms: u64 },
295
296 #[error("writer task request failed (request_state={request_state}): {source}")]
302 WriterTaskRequestFailed {
303 request_state: WriterTaskRequestState,
304 #[source]
305 source: Box<StorageError>,
306 },
307
308 #[error("writer task terminated (request_state={request_state})")]
315 WriterTaskTerminated {
316 request_state: WriterTaskRequestState,
317 sqlite_full_codes: Option<(i32, i32)>,
320 },
321
322 #[error("write outcome unknown after COMMIT: {source}")]
325 WriteOutcomeUnknown {
326 #[source]
327 source: Box<dyn StdError + Send + Sync>,
328 },
329
330 #[error("writer owner unavailable during {operation}: {source}")]
332 WriterOwnerUnavailable {
333 operation: Cow<'static, str>,
334 #[source]
335 source: Box<StorageError>,
336 },
337
338 #[error("strict writer routing refused a direct write during {operation}")]
340 WriterRouteViolation { operation: Cow<'static, str> },
341
342 #[error("internal storage error: {0}")]
345 Internal(String),
346
347 #[error(
352 "KHIVE_WRITE_QUEUE=1 but no Tokio runtime context is available to spawn the writer task"
353 )]
354 WriterTaskNoRuntime,
355
356 #[error(
360 "refusing write on {capability:?} at {volume}: {available_bytes} bytes available, \
361 the {floor_bytes}-byte free-space floor plus {required_headroom_bytes} bytes of \
362 operation headroom would be violated"
363 )]
364 CapacityFloor {
365 capability: StorageCapability,
366 volume: String,
367 available_bytes: u64,
368 floor_bytes: u64,
369 required_headroom_bytes: u64,
370 },
371
372 #[error("capacity admission unavailable for {capability:?} in {phase} phase: {message}")]
374 CapacityUnavailable {
375 capability: StorageCapability,
376 phase: CapacityUnavailablePhase,
377 message: String,
378 },
379}
380
381impl StorageError {
382 pub fn sqlite_write_failure(&self) -> Option<SqliteWriteFailure> {
384 match self {
385 Self::SqliteWrite { failure, .. } => Some(*failure),
386 Self::WriterTaskRequestFailed { source, .. }
387 | Self::WriterOwnerUnavailable { source, .. } => source.sqlite_write_failure(),
388 _ => None,
389 }
390 }
391
392 pub fn without_sqlite_write_stage(&self) -> &Self {
394 match self {
395 Self::SqliteWrite { source, .. } => source.without_sqlite_write_stage(),
396 _ => self,
397 }
398 }
399
400 pub fn writer_request_state(&self) -> Option<WriterTaskRequestState> {
402 match self.without_sqlite_write_stage() {
403 Self::WriterTaskRequestFailed { request_state, .. }
404 | Self::WriterTaskTerminated { request_state, .. } => Some(*request_state),
405 Self::WriteOutcomeUnknown { .. } => Some(WriterTaskRequestState::SideEffectsUnknown),
406 Self::WriterOwnerUnavailable { .. } | Self::WriterRouteViolation { .. } => {
407 Some(WriterTaskRequestState::NotStarted)
408 }
409 _ => None,
410 }
411 }
412
413 pub fn is_write_outcome_unknown(&self) -> bool {
415 matches!(
416 self.without_sqlite_write_stage(),
417 Self::WriteOutcomeUnknown { .. }
418 )
419 }
420
421 pub fn with_sqlite_write_failure(self, failure: SqliteWriteFailure) -> Self {
423 if self.sqlite_write_failure().is_some() {
424 self
425 } else {
426 Self::SqliteWrite {
427 failure,
428 source: Box::new(self),
429 }
430 }
431 }
432 pub fn writer_task_terminated(request_state: WriterTaskRequestState) -> Self {
436 Self::WriterTaskTerminated {
437 request_state,
438 sqlite_full_codes: None,
439 }
440 }
441
442 pub fn driver(
444 capability: StorageCapability,
445 operation: impl Into<Cow<'static, str>>,
446 source: impl StdError + Send + Sync + 'static,
447 ) -> Self {
448 Self::Driver {
449 capability,
450 operation: operation.into(),
451 source: Box::new(source),
452 }
453 }
454
455 pub fn capability(&self) -> Option<StorageCapability> {
457 match self {
458 Self::NotFound { capability, .. }
459 | Self::AlreadyExists { capability, .. }
460 | Self::Conflict { capability, .. }
461 | Self::InvalidInput { capability, .. }
462 | Self::SecretDetected { capability, .. }
463 | Self::Unsupported { capability, .. }
464 | Self::Serialization { capability, .. }
465 | Self::IndexMaintenance { capability, .. }
466 | Self::Driver { capability, .. }
467 | Self::CapacityFloor { capability, .. }
468 | Self::CapacityUnavailable { capability, .. } => Some(*capability),
469 Self::BlobTooLarge { .. }
470 | Self::BlobSizeMismatch { .. }
471 | Self::BlobDigestMismatch { .. } => Some(StorageCapability::Blob),
472 Self::WriterTaskRequestFailed { source, .. }
473 | Self::WriterOwnerUnavailable { source, .. }
474 | Self::SqliteWrite { source, .. } => source.capability(),
475 Self::Pool { .. }
476 | Self::Timeout { .. }
477 | Self::AdmissionTimeout { .. }
478 | Self::Transaction { .. }
479 | Self::ReadTransactionAgeEvicted { .. }
480 | Self::ReadTransactionAgeEvictionCleanupFailed { .. }
481 | Self::WriteQueueFull { .. }
482 | Self::WriterTaskBusy { .. }
483 | Self::WriterTaskTerminated { .. }
484 | Self::WriteOutcomeUnknown { .. }
485 | Self::WriterRouteViolation { .. }
486 | Self::Internal(..)
487 | Self::WriterTaskNoRuntime => None,
488 }
489 }
490
491 pub fn is_retryable(&self) -> bool {
493 if let Self::WriterTaskRequestFailed { source, .. }
494 | Self::WriterOwnerUnavailable { source, .. }
495 | Self::SqliteWrite { source, .. } = self
496 {
497 return source.is_retryable();
498 }
499 matches!(
500 self,
501 Self::Pool { .. }
502 | Self::Timeout { .. }
503 | Self::AdmissionTimeout { .. }
504 | Self::Transaction { .. }
505 | Self::ReadTransactionAgeEvicted { .. }
506 | Self::ReadTransactionAgeEvictionCleanupFailed { .. }
507 | Self::WriteQueueFull { .. }
508 | Self::WriterTaskBusy { .. }
509 | Self::CapacityUnavailable {
510 phase: CapacityUnavailablePhase::LockContended,
511 ..
512 }
513 )
514 }
515
516 pub fn is_fts5_syntax_error(&self) -> bool {
532 if let Self::WriterTaskRequestFailed { source, .. } | Self::SqliteWrite { source, .. } =
533 self
534 {
535 return source.is_fts5_syntax_error();
536 }
537 let Self::Driver {
538 capability,
539 operation,
540 source,
541 } = self
542 else {
543 return false;
544 };
545 if *capability != StorageCapability::Text || operation.as_ref() != "fts_search" {
546 return false;
547 }
548 let msg = source.to_string();
549 msg.contains("fts5: syntax error")
550 || msg.contains("fts5: parser stack overflow")
551 || msg.contains("fts5: column queries are not supported")
552 || msg.contains("fts5: phrase queries are not supported (detail")
553 || msg.contains("fts5: NEAR queries are not supported (detail")
554 }
555
556 pub fn is_unique_constraint_violation(&self) -> bool {
569 if let Self::WriterTaskRequestFailed { source, .. } | Self::SqliteWrite { source, .. } =
570 self
571 {
572 return source.is_unique_constraint_violation();
573 }
574 let Self::Driver {
575 capability,
576 operation,
577 source,
578 } = self
579 else {
580 return false;
581 };
582 if *capability != StorageCapability::Sql {
583 return false;
584 }
585 if !matches!(
586 operation.as_ref(),
587 "execute" | "pool_writer.execute" | "tx.execute"
588 ) {
589 return false;
590 }
591 source.to_string().contains("UNIQUE constraint failed")
592 }
593}
594
595#[cfg(test)]
596#[path = "error_tests.rs"]
597mod tests;