1use rusqlite::Connection;
51use std::collections::HashMap;
52use std::panic::{catch_unwind, AssertUnwindSafe};
53use std::path::{Path, PathBuf};
54use std::sync::atomic::{AtomicBool, Ordering};
55use std::sync::{Arc, Mutex, OnceLock};
56use std::time::{Duration, Instant};
57use tokio::sync::{mpsc, oneshot};
58
59use khive_storage::error::{StorageError, WriterTaskRequestState};
60
61use crate::error::SqliteError;
62use crate::pool::{ConnectionPool, WriterAcquisitionCounters};
63use crate::writer_admission_metrics::{
64 AdmissionObservation, Snapshot, Unavailable, WriterAdmissionMetrics,
65};
66
67#[path = "writer_task_labels.rs"]
68mod labels;
69
70pub(crate) use labels::{collect_statement_labels, MAX_WRITE_LABELS};
71use labels::{dedup_labels, SubmitLabels};
72
73const WRITER_BEGIN_RETRY_DELAYS: [Duration; 2] =
80 [Duration::from_millis(5), Duration::from_millis(10)];
81
82type WriteOp<R> = Box<dyn FnOnce(&Connection) -> Result<R, StorageError> + Send>;
92
93#[derive(Debug, Clone, PartialEq, Eq)]
98pub struct WriterStageObservation {
99 pub queue_wait_micros: u64,
100 pub transaction_acquire_micros: u64,
101 pub body_micros: u64,
102 pub commit_micros: u64,
103 pub total_micros: u64,
104 pub queue_depth_at_entry: u64,
105 pub observed_at_unix_ms: u64,
106 pub labels: Vec<String>,
113 pub labels_truncated: Option<u64>,
116}
117
118static WRITER_STAGE_OBSERVATIONS: OnceLock<
119 Mutex<HashMap<Option<PathBuf>, WriterStageObservation>>,
120> = OnceLock::new();
121
122fn writer_stage_observations() -> &'static Mutex<HashMap<Option<PathBuf>, WriterStageObservation>> {
123 WRITER_STAGE_OBSERVATIONS.get_or_init(|| Mutex::new(HashMap::new()))
124}
125
126fn writer_db_key_from_path(path: Option<&Path>) -> Option<PathBuf> {
127 path.map(Path::to_path_buf)
128}
129
130fn writer_db_key(pool: &ConnectionPool) -> Option<PathBuf> {
131 writer_db_key_from_path(pool.canonical_path())
132}
133
134fn duration_micros(duration: Duration) -> u64 {
135 duration.as_micros().min(u128::from(u64::MAX)) as u64
136}
137
138fn observed_at_unix_ms() -> u64 {
139 std::time::SystemTime::now()
140 .duration_since(std::time::UNIX_EPOCH)
141 .map(|duration| duration.as_millis() as u64)
142 .unwrap_or(0)
143}
144
145pub fn last_writer_stage_observation(pool: &ConnectionPool) -> Option<WriterStageObservation> {
148 writer_stage_observations()
149 .lock()
150 .unwrap_or_else(std::sync::PoisonError::into_inner)
151 .get(&writer_db_key(pool))
152 .cloned()
153}
154
155#[cfg(test)]
156trait TestWriterStageClock: Send + Sync {
157 fn now(&self) -> Instant;
158 fn at_commit(&self);
159}
160
161struct WriteTelemetry {
162 #[cfg(test)]
163 test_clock: Option<std::sync::Arc<dyn TestWriterStageClock>>,
164 backend_key: Option<PathBuf>,
165 db: String,
166 submitted_at: Instant,
167 queue_depth_at_entry: usize,
168 slow_write_threshold: Option<Duration>,
169 labels: SubmitLabels,
170 attempt_log: bool,
173 top_level: bool,
174 request_id: Option<u64>,
178}
179
180impl WriteTelemetry {
181 fn new(
182 backend_key: Option<PathBuf>,
183 db: String,
184 queue_depth_at_entry: usize,
185 slow_write_threshold: Option<Duration>,
186 labels: SubmitLabels,
187 attempt_log: bool,
188 top_level: bool,
189 ) -> Self {
190 Self {
191 #[cfg(test)]
192 test_clock: None,
193 backend_key,
194 db,
195 submitted_at: Instant::now(),
196 queue_depth_at_entry,
197 slow_write_threshold,
198 labels,
199 attempt_log,
200 top_level,
201 request_id: khive_storage::current_request_correlation(),
202 }
203 }
204
205 fn queue_wait(&self) -> Duration {
206 self.submitted_at.elapsed()
207 }
208
209 fn resolve_labels(&self) -> (Vec<String>, Option<u64>) {
214 match &self.labels {
215 SubmitLabels::None => (Vec::new(), None),
216 SubmitLabels::Site(site) => (vec![(*site).to_owned()], None),
217 SubmitLabels::Statements(labels) => {
218 if labels.len() <= MAX_WRITE_LABELS {
219 (labels.clone(), None)
220 } else {
221 let dropped = (labels.len() - MAX_WRITE_LABELS) as u64;
222 (labels[..MAX_WRITE_LABELS].to_vec(), Some(dropped))
223 }
224 }
225 }
226 }
227
228 #[allow(clippy::too_many_arguments)]
229 fn finish(
230 self,
231 queue_wait: Duration,
232 transaction_acquire: Duration,
233 body: Duration,
234 commit: Duration,
235 succeeded: bool,
236 rows_changed: u64,
237 ) {
238 let total = self.submitted_at.elapsed();
239 let slow = self
240 .slow_write_threshold
241 .is_some_and(|threshold| total >= threshold);
242 let (labels, labels_truncated) = if slow || self.attempt_log {
247 self.resolve_labels()
248 } else {
249 (Vec::new(), None)
250 };
251 let observation = WriterStageObservation {
252 queue_wait_micros: duration_micros(queue_wait),
253 transaction_acquire_micros: duration_micros(transaction_acquire),
254 body_micros: duration_micros(body),
255 commit_micros: duration_micros(commit),
256 total_micros: duration_micros(total),
257 queue_depth_at_entry: self.queue_depth_at_entry as u64,
258 observed_at_unix_ms: observed_at_unix_ms(),
259 labels,
260 labels_truncated,
261 };
262 writer_stage_observations()
263 .lock()
264 .unwrap_or_else(std::sync::PoisonError::into_inner)
265 .insert(self.backend_key, observation.clone());
266
267 if slow {
268 crate::timeout_sink::emit_slow_write(&self.db, &observation);
269 }
270 if self.attempt_log {
271 crate::timeout_sink::emit_writer_attempt(
272 &self.db,
273 &observation,
274 crate::timeout_sink::WriterAttempt {
275 request_id: self.request_id,
276 succeeded,
277 rows_changed,
278 top_level: self.top_level,
279 },
280 );
281 }
282 }
283}
284
285struct ReplyReceipt<R> {
286 commit_issued: AtomicBool,
287 completed: Mutex<Option<Result<R, StorageError>>>,
288}
289
290impl<R> Default for ReplyReceipt<R> {
291 fn default() -> Self {
292 Self {
293 commit_issued: AtomicBool::new(false),
294 completed: Mutex::new(None),
295 }
296 }
297}
298
299impl<R> ReplyReceipt<R> {
300 fn completed(&self) -> std::sync::MutexGuard<'_, Option<Result<R, StorageError>>> {
301 self.completed
302 .lock()
303 .unwrap_or_else(std::sync::PoisonError::into_inner)
304 }
305}
306
307struct PendingWrite<R> {
308 reply_rx: oneshot::Receiver<Result<R, StorageError>>,
309 receipt: Arc<ReplyReceipt<R>>,
310}
311
312impl<R> PendingWrite<R> {
313 async fn wait(self) -> Result<R, StorageError> {
314 match self.reply_rx.await {
315 Ok(result) => result,
316 Err(source) => {
317 if let Some(Err(error)) = self.receipt.completed().take() {
320 return Err(error);
321 }
322 if self.receipt.commit_issued.load(Ordering::Acquire) {
323 Err(StorageError::WriteOutcomeUnknown {
324 source: Box::new(source),
325 })
326 } else {
327 Err(writer_task_terminated(
328 WriterTaskRequestState::SideEffectsUnknown,
329 ))
330 }
331 }
332 }
333 }
334}
335
336#[cfg(test)]
338impl<R> std::future::Future for PendingWrite<R> {
339 type Output = Result<Result<R, StorageError>, oneshot::error::RecvError>;
340
341 fn poll(
342 self: std::pin::Pin<&mut Self>,
343 cx: &mut std::task::Context<'_>,
344 ) -> std::task::Poll<Self::Output> {
345 std::future::Future::poll(std::pin::Pin::new(&mut self.get_mut().reply_rx), cx)
346 }
347}
348
349pub struct WriteRequest<R: Send + 'static> {
364 op: WriteOp<R>,
365 reply: oneshot::Sender<Result<R, StorageError>>,
366 receipt: Arc<ReplyReceipt<R>>,
367 top_level: bool,
368 checkpoint_bypass: bool,
370 vacuum_copy_headroom: bool,
371 lease_class: crate::disk_guard::WriteClassContext,
374 telemetry: WriteTelemetry,
375 admission: Option<AdmissionObservation>,
376}
377
378mod sealed {
379 pub trait Sealed {
384 fn start_execution(&mut self);
385
386 fn execute_and_reply_reporting_terminal(
387 self: Box<Self>,
388 conn: &rusqlite::Connection,
389 tx_span: Option<khive_storage::tx_registry::TxHandle>,
390 queue_wait: std::time::Duration,
391 transaction_acquire: std::time::Duration,
392 ) -> Option<khive_storage::error::WriterTaskRequestState>;
393
394 fn execute_and_reply_top_level_reporting_terminal(
395 self: Box<Self>,
396 conn: &rusqlite::Connection,
397 queue_wait: std::time::Duration,
398 ) -> Option<khive_storage::error::WriterTaskRequestState>;
399
400 fn reply_error_after_begin(
401 self: Box<Self>,
402 err: khive_storage::error::StorageError,
403 queue_wait: std::time::Duration,
404 transaction_acquire: std::time::Duration,
405 );
406 }
407}
408
409pub trait AnyWriteRequest: sealed::Sealed + Send {
415 fn execute_and_reply(self: Box<Self>, conn: &Connection);
428
429 fn execute_and_reply_top_level(self: Box<Self>, conn: &Connection);
439
440 fn reply_error(self: Box<Self>, err: StorageError);
452
453 fn is_top_level(&self) -> bool;
457
458 fn is_checkpoint_bypass(&self) -> bool;
459
460 fn needs_vacuum_headroom(&self) -> bool;
461
462 fn lease_class(&self) -> crate::disk_guard::WriteClassContext;
464
465 fn queue_wait(&self) -> Duration;
468}
469
470#[derive(Debug, Clone, Copy, PartialEq, Eq)]
471enum RollbackDisposition {
472 RolledBack,
473 SideEffectsUnknown,
474}
475
476fn rollback_after_failure(conn: &Connection, failure_context: &'static str) -> RollbackDisposition {
479 match conn.execute_batch("ROLLBACK") {
480 Ok(()) if conn.is_autocommit() => RollbackDisposition::RolledBack,
481 Ok(()) => {
482 tracing::error!(
483 failure_context,
484 "writer transaction: ROLLBACK returned success but the connection is still in a \
485 transaction; request side effects are unknown"
486 );
487 RollbackDisposition::SideEffectsUnknown
488 }
489 Err(rollback_error) => {
490 tracing::error!(
491 error = %rollback_error,
492 failure_context,
493 "writer transaction: rollback after request failure failed; request side effects are \
494 unknown"
495 );
496 RollbackDisposition::SideEffectsUnknown
497 }
498 }
499}
500
501pub(crate) fn execute_wrapped_transaction<R, F>(
508 conn: &Connection,
509 commit_operation: &'static str,
510 operation: F,
511) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
512where
513 F: FnOnce(&Connection) -> Result<R, StorageError>,
514{
515 let profiled = execute_wrapped_transaction_profiled(
516 conn,
517 commit_operation,
518 None,
519 false,
520 None,
521 operation,
522 #[cfg(test)]
523 None,
524 );
525 (profiled.result, profiled.terminal_state)
526}
527
528pub(crate) fn execute_wrapped_sql_bridge_transaction<R, F>(
531 conn: &Connection,
532 commit_operation: &'static str,
533 db: &str,
534 operation: F,
535) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
536where
537 F: FnOnce(&Connection) -> Result<R, StorageError>,
538{
539 let profiled = execute_wrapped_transaction_profiled(
540 conn,
541 commit_operation,
542 Some(db),
543 true,
544 None,
545 operation,
546 #[cfg(test)]
547 None,
548 );
549 (profiled.result, profiled.terminal_state)
550}
551
552struct ProfiledWrappedTransaction<R> {
553 result: Result<R, StorageError>,
554 terminal_state: Option<WriterTaskRequestState>,
555 body: Duration,
556 commit: Duration,
557}
558
559fn execute_wrapped_transaction_profiled<R, F>(
560 conn: &Connection,
561 commit_operation: &'static str,
562 db: Option<&str>,
563 direct_sql_bridge: bool,
564 commit_issued: Option<&AtomicBool>,
565 operation: F,
566 #[cfg(test)] test_clock: Option<&dyn TestWriterStageClock>,
567) -> ProfiledWrappedTransaction<R>
568where
569 F: FnOnce(&Connection) -> Result<R, StorageError>,
570{
571 let body_started = Instant::now();
572 #[cfg(test)]
573 let body_started = test_clock.map_or(body_started, TestWriterStageClock::now);
574 let operation_outcome = catch_unwind(AssertUnwindSafe(|| {
577 operation(conn).map_err(crate::error::statement_failure)
578 }));
579 #[cfg(not(test))]
580 let body = body_started.elapsed();
581 #[cfg(test)]
582 let body = test_clock.map_or_else(
583 || body_started.elapsed(),
584 |clock| clock.now().duration_since(body_started),
585 );
586
587 match operation_outcome {
588 Ok(Ok(value)) => {
589 let commit_started = Instant::now();
590 #[cfg(test)]
591 let commit_started = test_clock.map_or(commit_started, TestWriterStageClock::now);
592 #[cfg(test)]
593 if let Some(clock) = test_clock {
594 clock.at_commit();
595 }
596 if let Some(issued) = commit_issued {
597 issued.store(true, Ordering::Release);
598 }
599 #[cfg(any(test, feature = "test-support"))]
600 crate::test_hooks::commit_reply_issued(conn);
601 let commit_outcome = conn.execute_batch("COMMIT");
602 #[cfg(any(test, feature = "test-support"))]
603 crate::test_hooks::commit_reply_completed(
604 conn,
605 commit_outcome.is_ok(),
606 conn.is_autocommit(),
607 );
608 #[cfg(not(test))]
609 let commit = commit_started.elapsed();
610 #[cfg(test)]
611 let commit = test_clock.map_or_else(
612 || commit_started.elapsed(),
613 |clock| clock.now().duration_since(commit_started),
614 );
615 match commit_outcome {
616 Ok(()) if conn.is_autocommit() => ProfiledWrappedTransaction {
617 result: Ok(value),
618 terminal_state: None,
619 body,
620 commit,
621 },
622 Ok(()) => {
623 tracing::error!(
624 "writer transaction: COMMIT returned success but the connection is still in \
625 a transaction; request side effects are unknown"
626 );
627 let request_state = WriterTaskRequestState::SideEffectsUnknown;
628 ProfiledWrappedTransaction {
629 result: Err(writer_task_terminated(request_state)),
630 terminal_state: Some(request_state),
631 body,
632 commit,
633 }
634 }
635 Err(commit_error) => {
636 if let Some(db) = db {
637 if direct_sql_bridge {
638 crate::timeout_sink::maybe_emit_busy(
639 db,
640 crate::timeout_sink::Site::StandaloneSqlBridge,
641 &commit_error,
642 );
643 } else {
644 crate::timeout_sink::maybe_emit_sqlite_full(db, &commit_error);
645 }
646 }
647 match rollback_after_failure(conn, "commit failure") {
648 RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
649 result: Err(StorageError::WriterTaskRequestFailed {
650 request_state: WriterTaskRequestState::TransactionRolledBack,
651 source: Box::new({
652 let failure = crate::error::native_write_failure(
653 &commit_error,
654 khive_storage::error::SqliteWriteStage::Commit,
655 );
656 let error = if direct_sql_bridge {
657 StorageError::driver(
658 khive_storage::StorageCapability::Sql,
659 commit_operation,
660 commit_error,
661 )
662 } else {
663 StorageError::Pool {
664 operation: commit_operation.into(),
665 message: commit_error.to_string(),
666 }
667 };
668 match failure {
669 Some(failure) => error.with_sqlite_write_failure(failure),
670 None => error,
671 }
672 }),
673 }),
674 terminal_state: None,
675 body,
676 commit,
677 },
678 RollbackDisposition::SideEffectsUnknown => {
679 let request_state = WriterTaskRequestState::SideEffectsUnknown;
680 ProfiledWrappedTransaction {
681 result: Err(writer_task_terminated_with_cause(
682 request_state,
683 &commit_error,
684 khive_storage::error::SqliteWriteStage::Commit,
685 )),
686 terminal_state: Some(request_state),
687 body,
688 commit,
689 }
690 }
691 }
692 }
693 }
694 }
695 Ok(Err(operation_error)) => {
696 match rollback_after_failure(conn, "request operation failure") {
697 RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
698 result: Err(StorageError::WriterTaskRequestFailed {
699 request_state: WriterTaskRequestState::TransactionRolledBack,
700 source: Box::new(operation_error),
701 }),
702 terminal_state: None,
703 body,
704 commit: Duration::ZERO,
705 },
706 RollbackDisposition::SideEffectsUnknown => {
707 if let Some(db) = db {
711 crate::timeout_sink::maybe_emit_sqlite_full(db, &operation_error);
712 }
713 let request_state = WriterTaskRequestState::SideEffectsUnknown;
714 ProfiledWrappedTransaction {
715 result: Err(writer_task_terminated_with_cause(
716 request_state,
717 &operation_error,
718 khive_storage::error::SqliteWriteStage::Statement,
719 )),
720 terminal_state: Some(request_state),
721 body,
722 commit: Duration::ZERO,
723 }
724 }
725 }
726 }
727 Err(_panic_payload) => {
728 let request_state = match rollback_after_failure(conn, "request panic") {
729 RollbackDisposition::RolledBack => WriterTaskRequestState::TransactionRolledBack,
730 RollbackDisposition::SideEffectsUnknown => {
731 WriterTaskRequestState::SideEffectsUnknown
732 }
733 };
734 ProfiledWrappedTransaction {
735 result: Err(writer_task_terminated(request_state)),
736 terminal_state: Some(request_state),
737 body,
738 commit: Duration::ZERO,
739 }
740 }
741 }
742}
743
744fn reply_with_admission<R>(
745 reply: oneshot::Sender<Result<R, StorageError>>,
746 mut admission: Option<AdmissionObservation>,
747 receipt: &ReplyReceipt<R>,
748 suppress: bool,
749) {
750 if let Some(observation) = admission.as_mut() {
751 observation.reply_attempt();
752 }
753 if suppress {
754 drop(reply);
755 return;
756 }
757 let result = receipt.completed().take().expect("completed writer result");
758 let _ = reply.send(result);
759}
760
761impl<R: Send + 'static> sealed::Sealed for WriteRequest<R> {
762 fn start_execution(&mut self) {
763 if let Some(observation) = self.admission.as_mut() {
764 observation.start_execution();
765 }
766 }
767
768 fn execute_and_reply_reporting_terminal(
769 self: Box<Self>,
770 conn: &Connection,
771 tx_span: Option<khive_storage::tx_registry::TxHandle>,
772 queue_wait: Duration,
773 transaction_acquire: Duration,
774 ) -> Option<WriterTaskRequestState> {
775 let WriteRequest {
779 op,
780 reply,
781 receipt,
782 telemetry,
783 admission,
784 ..
785 } = *self;
786 #[cfg(any(test, feature = "test-support"))]
787 let reply_probe = crate::test_hooks::begin_commit_reply_request(conn);
788 let changes_before = conn.total_changes();
789 let profiled = execute_wrapped_transaction_profiled(
790 conn,
791 "writer_task_commit",
792 Some(&telemetry.db),
793 false,
794 Some(&receipt.commit_issued),
795 op,
796 #[cfg(test)]
797 telemetry.test_clock.as_deref(),
798 );
799 let rows_changed = conn.total_changes().saturating_sub(changes_before);
800 let succeeded = profiled.result.is_ok();
801 *receipt.completed() = Some(profiled.result);
802 if let Some(Err(error)) = receipt.completed().as_ref() {
803 crate::timeout_sink::maybe_emit_sqlite_full(&telemetry.db, error);
804 }
805 drop(tx_span);
810 telemetry.finish(
811 queue_wait,
812 transaction_acquire,
813 profiled.body,
814 profiled.commit,
815 succeeded,
816 rows_changed,
817 );
818 #[cfg(not(any(test, feature = "test-support")))]
821 let suppress = false;
822 #[cfg(any(test, feature = "test-support"))]
823 let suppress = reply_probe
824 .as_ref()
825 .is_some_and(|probe| probe.suppress_successful_reply());
826 reply_with_admission(reply, admission, &receipt, suppress);
827 profiled.terminal_state
828 }
829
830 fn execute_and_reply_top_level_reporting_terminal(
831 self: Box<Self>,
832 conn: &Connection,
833 queue_wait: Duration,
834 ) -> Option<WriterTaskRequestState> {
835 let WriteRequest {
836 op,
837 reply,
838 receipt,
839 telemetry,
840 admission,
841 ..
842 } = *self;
843 let changes_before = conn.total_changes();
844 let body_started = Instant::now();
845 let outcome = catch_unwind(AssertUnwindSafe(|| {
846 op(conn).map_err(crate::error::statement_failure)
847 }));
848 let body = body_started.elapsed();
849 let rows_changed = conn.total_changes().saturating_sub(changes_before);
850 let (result, terminal_state, open_transaction) = match outcome {
851 Ok(outcome) if conn.is_autocommit() => (outcome, None, false),
852 Ok(outcome) => {
853 let request_state = WriterTaskRequestState::SideEffectsUnknown;
854 let error = match outcome {
855 Err(error) => writer_task_terminated_with_cause(
856 request_state,
857 &error,
858 khive_storage::error::SqliteWriteStage::Statement,
859 ),
860 Ok(_) => writer_task_terminated(request_state),
861 };
862 (Err(error), Some(request_state), true)
863 }
864 Err(_panic_payload) => {
865 let state = WriterTaskRequestState::SideEffectsUnknown;
866 (Err(writer_task_terminated(state)), Some(state), false)
867 }
868 };
869 let succeeded = result.is_ok();
870 *receipt.completed() = Some(result);
871 let telemetry_db = telemetry.db.clone();
872 telemetry.finish(
873 queue_wait,
874 Duration::ZERO,
875 body,
876 Duration::ZERO,
877 succeeded,
878 rows_changed,
879 );
880 if open_transaction {
881 tracing::error!(
882 "writer task: top-level request returned with an open transaction; request \
883 side effects are unknown"
884 );
885 } else if terminal_state.is_none() {
886 if let Some(Err(error)) = receipt.completed().as_ref() {
887 crate::timeout_sink::maybe_emit_sqlite_full(&telemetry_db, error);
888 }
889 }
890 reply_with_admission(reply, admission, &receipt, false);
891 terminal_state
892 }
893
894 fn reply_error_after_begin(
895 self: Box<Self>,
896 err: StorageError,
897 queue_wait: Duration,
898 transaction_acquire: Duration,
899 ) {
900 let WriteRequest {
901 reply,
902 receipt,
903 telemetry,
904 admission,
905 ..
906 } = *self;
907 *receipt.completed() = Some(Err(err));
908 telemetry.finish(
909 queue_wait,
910 transaction_acquire,
911 Duration::ZERO,
912 Duration::ZERO,
913 false,
914 0,
915 );
916 reply_with_admission(reply, admission, &receipt, false);
917 }
918}
919
920impl<R: Send + 'static> AnyWriteRequest for WriteRequest<R> {
921 fn execute_and_reply(mut self: Box<Self>, conn: &Connection) {
922 let queue_wait = self.queue_wait();
923 sealed::Sealed::start_execution(self.as_mut());
924 let _ = sealed::Sealed::execute_and_reply_reporting_terminal(
925 self,
926 conn,
927 None,
928 queue_wait,
929 Duration::ZERO,
930 );
931 }
932
933 fn execute_and_reply_top_level(mut self: Box<Self>, conn: &Connection) {
934 let queue_wait = self.queue_wait();
935 sealed::Sealed::start_execution(self.as_mut());
936 let _ =
937 sealed::Sealed::execute_and_reply_top_level_reporting_terminal(self, conn, queue_wait);
938 }
939
940 fn reply_error(self: Box<Self>, err: StorageError) {
941 let queue_wait = self.queue_wait();
942 sealed::Sealed::reply_error_after_begin(self, err, queue_wait, Duration::ZERO);
943 }
944
945 fn is_top_level(&self) -> bool {
946 self.top_level
947 }
948
949 fn is_checkpoint_bypass(&self) -> bool {
950 self.checkpoint_bypass
951 }
952
953 fn needs_vacuum_headroom(&self) -> bool {
954 self.vacuum_copy_headroom
955 }
956
957 fn lease_class(&self) -> crate::disk_guard::WriteClassContext {
958 self.lease_class
959 }
960
961 fn queue_wait(&self) -> Duration {
962 self.telemetry.queue_wait()
963 }
964}
965
966fn writer_task_terminated(request_state: WriterTaskRequestState) -> StorageError {
967 StorageError::writer_task_terminated(request_state)
968}
969
970fn writer_task_terminated_with_cause(
971 request_state: WriterTaskRequestState,
972 error: &(dyn std::error::Error + 'static),
973 stage: khive_storage::error::SqliteWriteStage,
974) -> StorageError {
975 let mut source = Some(error);
976 let mut sqlite_full_codes = None;
977 while let Some(current) = source {
978 if let Some(rusqlite::Error::SqliteFailure(code, _)) =
979 current.downcast_ref::<rusqlite::Error>()
980 {
981 if code.code == rusqlite::ErrorCode::DiskFull {
982 sqlite_full_codes = Some((code.extended_code & 0xff, code.extended_code));
983 break;
984 }
985 }
986 source = current.source();
987 }
988 let terminal = StorageError::WriterTaskTerminated {
991 request_state,
992 sqlite_full_codes,
993 };
994 match crate::error::native_write_failure(error, stage) {
995 Some(mut failure) => {
996 failure.settlement_unknown =
997 request_state == WriterTaskRequestState::SideEffectsUnknown;
998 terminal.with_sqlite_write_failure(failure)
999 }
1000 None => terminal,
1001 }
1002}
1003
1004fn writer_task_begin_error(error: rusqlite::Error, busy_timeout: Duration) -> StorageError {
1005 let failure =
1006 crate::error::native_write_failure(&error, khive_storage::error::SqliteWriteStage::Begin);
1007 let mapped = if crate::timeout_sink::is_busy_or_locked(&error) {
1008 StorageError::WriterTaskBusy {
1009 timeout_ms: u64::try_from(busy_timeout.as_millis()).unwrap_or(u64::MAX),
1010 }
1011 } else {
1012 StorageError::Pool {
1013 operation: "writer_task_begin".into(),
1014 message: error.to_string(),
1015 }
1016 };
1017 match failure {
1018 Some(failure) => mapped.with_sqlite_write_failure(failure),
1019 None => mapped,
1020 }
1021}
1022
1023#[derive(Clone, Debug)]
1027pub struct WriterTaskHandle {
1028 tx: mpsc::Sender<Box<dyn AnyWriteRequest + Send>>,
1029 backend_key: Option<PathBuf>,
1032 db: String,
1037 slow_write_threshold: Option<std::time::Duration>,
1043 attempt_log: bool,
1046 enqueue_timeout: std::time::Duration,
1067 admission_metrics: Arc<WriterAdmissionMetrics>,
1068 strict_routing: bool,
1069}
1070
1071impl WriterTaskHandle {
1072 pub(crate) fn is_closed(&self) -> bool {
1073 self.tx.is_closed()
1074 }
1075
1076 fn unavailable_before_acceptance(&self) -> StorageError {
1077 if self.strict_routing {
1078 StorageError::WriterOwnerUnavailable {
1079 operation: "writer_task_enqueue".into(),
1080 source: Box::new(StorageError::Pool {
1081 operation: "writer_task_enqueue".into(),
1082 message: "writer owner is stopped".into(),
1083 }),
1084 }
1085 } else {
1086 writer_task_terminated(WriterTaskRequestState::NotStarted)
1087 }
1088 }
1089
1090 async fn enqueue<R, F>(&self, op: F) -> Result<PendingWrite<R>, StorageError>
1104 where
1105 R: Send + 'static,
1106 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1107 {
1108 self.enqueue_inner(op, false, false, false, SubmitLabels::None)
1109 .await
1110 }
1111
1112 async fn enqueue_inner<R, F>(
1118 &self,
1119 op: F,
1120 top_level: bool,
1121 checkpoint_bypass: bool,
1122 vacuum_copy_headroom: bool,
1123 labels: SubmitLabels,
1124 ) -> Result<PendingWrite<R>, StorageError>
1125 where
1126 R: Send + 'static,
1127 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1128 {
1129 let (reply_tx, reply_rx) = oneshot::channel();
1130 let receipt = Arc::new(ReplyReceipt::default());
1131 let labels = match labels {
1136 SubmitLabels::Statements(labels) => {
1137 SubmitLabels::Statements(dedup_labels(labels.iter().map(String::as_str)))
1138 }
1139 other => other,
1140 };
1141 let telemetry = WriteTelemetry::new(
1142 self.backend_key.clone(),
1143 self.db.clone(),
1144 self.queue_depth(),
1145 self.slow_write_threshold,
1146 labels,
1147 self.attempt_log,
1148 top_level,
1149 );
1150 let mut request = Box::new(WriteRequest {
1151 op: Box::new(op),
1152 reply: reply_tx,
1153 receipt: Arc::clone(&receipt),
1154 top_level,
1155 checkpoint_bypass,
1156 vacuum_copy_headroom,
1157 lease_class: crate::disk_guard::WriteClassContext::capture(),
1158 telemetry,
1159 admission: None,
1160 });
1161 request.admission = Some(self.admission_metrics.offer());
1162 let permit = self
1163 .tx
1164 .reserve()
1165 .await
1166 .map_err(|_| self.unavailable_before_acceptance())?;
1167 if let Some(observation) = request.admission.as_mut() {
1168 observation.accepted();
1169 }
1170 permit.send(request);
1171
1172 Ok(PendingWrite { reply_rx, receipt })
1173 }
1174
1175 pub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
1182 where
1183 R: Send + 'static,
1184 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1185 {
1186 let reply_rx = self.enqueue(op).await?;
1187 reply_rx.wait().await
1188 }
1189
1190 pub async fn send_with_timeout<R, F>(
1205 &self,
1206 op: F,
1207 timeout: std::time::Duration,
1208 ) -> Result<R, StorageError>
1209 where
1210 R: Send + 'static,
1211 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1212 {
1213 self.send_with_timeout_labelled(op, timeout, SubmitLabels::None)
1214 .await
1215 }
1216
1217 async fn send_with_timeout_labelled<R, F>(
1221 &self,
1222 op: F,
1223 timeout: std::time::Duration,
1224 labels: SubmitLabels,
1225 ) -> Result<R, StorageError>
1226 where
1227 R: Send + 'static,
1228 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1229 {
1230 let reply_rx = match tokio::time::timeout(
1231 timeout,
1232 self.enqueue_inner(op, false, false, false, labels),
1233 )
1234 .await
1235 {
1236 Ok(Ok(reply_rx)) => reply_rx,
1237 Ok(Err(e)) => return Err(e),
1238 Err(_elapsed) => {
1239 let timeout_ms = timeout.as_millis() as u64;
1240 self.admission_metrics.record_capacity_deadline();
1241 crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1242 return Err(StorageError::WriteQueueFull { timeout_ms });
1243 }
1244 };
1245
1246 reply_rx.wait().await
1247 }
1248
1249 pub async fn send_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1260 where
1261 R: Send + 'static,
1262 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1263 {
1264 self.send_with_timeout(op, self.enqueue_timeout).await
1265 }
1266
1267 pub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
1279 where
1280 R: Send + 'static,
1281 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1282 {
1283 let reply_rx = self
1284 .enqueue_inner(op, true, false, false, SubmitLabels::None)
1285 .await?;
1286 reply_rx.wait().await
1287 }
1288
1289 pub async fn send_top_level_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1294 where
1295 R: Send + 'static,
1296 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1297 {
1298 self.send_top_level_bounded_inner(op, false, false, SubmitLabels::None)
1299 .await
1300 }
1301
1302 pub(crate) async fn send_checkpoint_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1305 where
1306 R: Send + 'static,
1307 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1308 {
1309 self.send_top_level_bounded_inner(op, true, false, SubmitLabels::Site("wal_checkpoint"))
1310 .await
1311 }
1312
1313 pub(crate) async fn send_vacuum_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1315 where
1316 R: Send + 'static,
1317 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1318 {
1319 self.send_top_level_bounded_inner(op, false, true, SubmitLabels::Site("vacuum"))
1320 .await
1321 }
1322
1323 async fn send_top_level_bounded_inner<R, F>(
1324 &self,
1325 op: F,
1326 checkpoint_bypass: bool,
1327 vacuum_copy_headroom: bool,
1328 labels: SubmitLabels,
1329 ) -> Result<R, StorageError>
1330 where
1331 R: Send + 'static,
1332 F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1333 {
1334 let reply_rx = match tokio::time::timeout(
1335 self.enqueue_timeout,
1336 self.enqueue_inner(op, true, checkpoint_bypass, vacuum_copy_headroom, labels),
1337 )
1338 .await
1339 {
1340 Ok(Ok(reply_rx)) => reply_rx,
1341 Ok(Err(e)) => return Err(e),
1342 Err(_elapsed) => {
1343 let timeout_ms = self.enqueue_timeout.as_millis() as u64;
1344 self.admission_metrics.record_capacity_deadline();
1345 crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1346 return Err(StorageError::WriteQueueFull { timeout_ms });
1347 }
1348 };
1349
1350 reply_rx.wait().await
1351 }
1352
1353 pub fn queue_depth(&self) -> usize {
1362 self.tx.max_capacity() - self.tx.capacity()
1363 }
1364
1365 pub fn capacity(&self) -> usize {
1368 self.tx.max_capacity()
1369 }
1370
1371 pub(crate) fn admission_snapshot(&self) -> Result<Snapshot, Unavailable> {
1372 self.admission_metrics.snapshot()
1373 }
1374}
1375
1376pub fn spawn(pool: &ConnectionPool, capacity: usize) -> Result<WriterTaskHandle, SqliteError> {
1406 pool.spawn_writer_task(capacity)
1407}
1408
1409pub(crate) fn spawn_with_connection(
1412 pool: &ConnectionPool,
1413 conn: Connection,
1414 capacity: usize,
1415) -> Result<WriterTaskHandle, SqliteError> {
1416 let acquisition_counters = pool.writer_acquisition_counters();
1420 let write_admission = pool.write_admission();
1421 let busy_timeout = pool.config().busy_timeout;
1422 let origin = pool.origin();
1423 let backend_key = writer_db_key(pool);
1424 let db = crate::timeout_sink::db_label(pool);
1425 let (tx, rx) = mpsc::channel(capacity.max(1));
1426 let join = tokio::spawn(run_writer_task(
1427 (conn, pool.timeout_sink_writer_lease()),
1428 rx,
1429 origin,
1430 db.clone(),
1431 acquisition_counters,
1432 write_admission,
1433 busy_timeout,
1434 ));
1435 pool.set_writer_task_join(join);
1439 Ok(WriterTaskHandle {
1440 tx,
1441 backend_key,
1442 db,
1443 slow_write_threshold: crate::timeout_sink::slow_write_threshold(),
1444 attempt_log: crate::timeout_sink::writer_attempt_log_enabled(),
1445 enqueue_timeout: std::time::Duration::from_millis(
1446 pool.config().write_admission_deadline_ms,
1447 ),
1448 admission_metrics: WriterAdmissionMetrics::new(),
1449 strict_routing: pool.config().write_routing_strict,
1450 })
1451}
1452
1453async fn close_and_fail_queued_requests(rx: &mut mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>) {
1461 rx.close();
1462 while let Some(request) = rx.recv().await {
1463 request.reply_error(writer_task_terminated(WriterTaskRequestState::NotStarted));
1464 }
1465}
1466
1467fn begin_immediate_with_retry(
1471 conn: &Connection,
1472 acquisition_counters: &WriterAcquisitionCounters,
1473 busy_timeout: Duration,
1474 mut set_busy_timeout: impl FnMut(&Connection, Duration) -> rusqlite::Result<()>,
1475) -> (rusqlite::Result<()>, Duration, u32) {
1476 let transaction_acquire_started = Instant::now();
1477 let mut begin_attempt = 1_u32;
1478 let mut retry_delays = WRITER_BEGIN_RETRY_DELAYS.into_iter();
1479 let mut busy_timeout_lowered = false;
1480 let begin_outcome = loop {
1481 match conn.execute_batch("BEGIN IMMEDIATE") {
1482 Ok(()) => break Ok(()),
1483 Err(error) if crate::timeout_sink::is_busy_or_locked(&error) => {
1484 acquisition_counters.record_writer_task_begin_busy();
1490 let Some(delay) = retry_delays.next() else {
1491 break Err(error);
1492 };
1493 let remaining_budget =
1501 busy_timeout.saturating_sub(transaction_acquire_started.elapsed());
1502 if remaining_budget.is_zero() {
1503 break Err(error);
1504 }
1505 if let Err(set_err) = set_busy_timeout(conn, remaining_budget) {
1506 tracing::warn!(
1507 error = %set_err,
1508 "writer task: failed to lower busy_timeout for BEGIN \
1509 retry; surfacing the original busy refusal"
1510 );
1511 break Err(error);
1513 }
1514 busy_timeout_lowered = true;
1515 acquisition_counters.record_writer_task_begin_busy_absorbed();
1518 tracing::debug!(
1519 attempt = begin_attempt,
1520 backoff_ms = delay.as_millis() as u64,
1521 budget_remaining_ms = remaining_budget.as_millis() as u64,
1522 "writer task: BEGIN IMMEDIATE refused busy; retrying before \
1523 request execution"
1524 );
1525 std::thread::sleep(delay);
1526 begin_attempt = begin_attempt.saturating_add(1);
1527 }
1528 Err(error) => break Err(error),
1529 }
1530 };
1531 let transaction_acquire = transaction_acquire_started.elapsed();
1532 if busy_timeout_lowered {
1538 if let Err(restore_err) = set_busy_timeout(conn, busy_timeout) {
1539 tracing::warn!(
1540 error = %restore_err,
1541 "writer task: failed to restore busy_timeout after a BEGIN retry \
1542 sequence"
1543 );
1544 }
1545 }
1546 (begin_outcome, transaction_acquire, begin_attempt)
1547}
1548
1549struct BlockingWriterConnection {
1550 conn: Option<Connection>,
1551 admission: Arc<crate::pool::WriteAdmission>,
1552 volume_lease: Option<crate::disk_guard::VolumeLease>,
1553}
1554
1555impl BlockingWriterConnection {
1556 fn new(conn: Connection, admission: Arc<crate::pool::WriteAdmission>) -> Self {
1557 Self {
1558 conn: Some(conn),
1559 admission,
1560 volume_lease: None,
1561 }
1562 }
1563
1564 fn finish(
1565 mut self,
1566 state: Option<WriterTaskRequestState>,
1567 ) -> (Option<Connection>, Option<WriterTaskRequestState>) {
1568 if state.is_some() {
1569 self.retire();
1570 (None, state)
1571 } else {
1572 (self.conn.take(), None)
1573 }
1574 }
1575
1576 fn retire(&mut self) {
1577 if let Some(conn) = self.conn.take() {
1578 let _ = self.admission.close_retired_connection(conn);
1581 }
1582 }
1583}
1584
1585impl Drop for BlockingWriterConnection {
1586 fn drop(&mut self) {
1587 self.retire();
1588 }
1589}
1590
1591impl std::ops::Deref for BlockingWriterConnection {
1592 type Target = Connection;
1593
1594 fn deref(&self) -> &Connection {
1595 self.conn
1596 .as_ref()
1597 .expect("blocking writer owns its connection until settlement")
1598 }
1599}
1600
1601async fn run_writer_task(
1615 mut owner: (Connection, Option<crate::timeout_sink::WriterLease>),
1616 mut rx: mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>,
1617 origin: khive_storage::tx_registry::TxOrigin,
1618 db: String,
1619 acquisition_counters: Arc<WriterAcquisitionCounters>,
1620 write_admission: Arc<crate::pool::WriteAdmission>,
1621 busy_timeout: Duration,
1622) {
1623 #[cfg(any(test, feature = "test-support"))]
1624 if let Err(error) = crate::test_hooks::adopt(&mut owner.0) {
1625 tracing::error!(%error, "writer task: test hook registration failed");
1626 }
1627 while let Some(mut request) = rx.recv().await {
1628 let queue_wait = request.queue_wait();
1632 sealed::Sealed::start_execution(request.as_mut());
1633 let origin = origin.clone();
1634 let blocking_counters = Arc::clone(&acquisition_counters);
1635 let blocking_admission = Arc::clone(&write_admission);
1636 let blocking_db = db.clone();
1637 let conn = owner.0;
1640 let blocking_sink_lease = owner.1.clone();
1641 let outcome = tokio::task::spawn_blocking(move || {
1642 let _lease_class = request.lease_class().enter();
1645 let outcome = (|| {
1646 let mut conn = BlockingWriterConnection::new(conn, Arc::clone(&blocking_admission));
1647 let acquisition_counters = blocking_counters;
1648 if !conn.is_autocommit() {
1653 tracing::error!(
1654 "writer task: connection is not in autocommit mode before request dispatch; \
1655 retiring the poisoned writer without running the request"
1656 );
1657 let request_state = WriterTaskRequestState::NotStarted;
1658 request.reply_error(writer_task_terminated(request_state));
1659 return conn.finish(Some(request_state));
1660 }
1661
1662 conn.volume_lease = if request.is_checkpoint_bypass() {
1666 None
1667 } else {
1668 let class = if request.needs_vacuum_headroom() {
1669 crate::disk_guard::LeaseClass::Maintenance
1670 } else {
1671 crate::disk_guard::LeaseClass::WriterTask
1672 };
1673 match blocking_admission.acquire(class) {
1674 Ok(lease) => lease,
1675 Err(error) => {
1676 request.reply_error(error.into_storage_error(
1677 khive_storage::StorageCapability::Sql,
1678 "writer_task_admission",
1679 ));
1680 return conn.finish(None);
1681 }
1682 }
1683 };
1684
1685 let terminal_state = if request.is_top_level() {
1686 if !request.is_checkpoint_bypass() {
1687 let admission = if request.needs_vacuum_headroom() {
1688 blocking_admission.check_for_vacuum()
1689 } else {
1690 blocking_admission.check()
1691 };
1692 if let Err(error) = admission {
1693 request.reply_error(error.into_storage_error(
1694 khive_storage::StorageCapability::Sql,
1695 "writer_task_admission",
1696 ));
1697 return conn.finish(None);
1698 }
1699 }
1700 acquisition_counters.record_writer_task_acquisition();
1708 sealed::Sealed::execute_and_reply_top_level_reporting_terminal(
1709 request, &conn, queue_wait,
1710 )
1711 } else {
1712 let tx_span = khive_storage::tx_registry::register_scoped(
1713 Some("writer_task_tx".to_string()),
1714 origin,
1715 );
1716 let (begin_outcome, transaction_acquire, begin_attempt) =
1717 begin_immediate_with_retry(
1718 &conn,
1719 &acquisition_counters,
1720 busy_timeout,
1721 Connection::busy_timeout,
1722 );
1723 match begin_outcome {
1724 Ok(()) => {
1725 if let Err(error) = blocking_admission.check() {
1726 let request_state =
1727 match rollback_after_failure(&conn, "capacity admission") {
1728 RollbackDisposition::RolledBack => None,
1729 RollbackDisposition::SideEffectsUnknown => {
1730 Some(WriterTaskRequestState::SideEffectsUnknown)
1731 }
1732 };
1733 drop(tx_span);
1734 let error = if let Some(state) = request_state {
1735 writer_task_terminated(state)
1736 } else {
1737 error.into_storage_error(
1738 khive_storage::StorageCapability::Sql,
1739 "writer_task_admission",
1740 )
1741 };
1742 sealed::Sealed::reply_error_after_begin(
1743 request,
1744 error,
1745 queue_wait,
1746 transaction_acquire,
1747 );
1748 return conn.finish(request_state);
1749 }
1750 acquisition_counters.record_writer_task_acquisition();
1751 sealed::Sealed::execute_and_reply_reporting_terminal(
1752 request,
1753 &conn,
1754 Some(tx_span),
1755 queue_wait,
1756 transaction_acquire,
1757 )
1758 }
1759 Err(e) => {
1760 crate::timeout_sink::maybe_emit_sqlite_full(&blocking_db, &e);
1766 tracing::warn!(
1767 error = %e,
1768 attempts = begin_attempt,
1769 "writer task: BEGIN IMMEDIATE failed; replying an \
1770 error without running the request's operation"
1771 );
1772 drop(tx_span);
1777 let begin_error = writer_task_begin_error(e, busy_timeout);
1784 if !matches!(
1785 begin_error.without_sqlite_write_stage(),
1786 StorageError::WriterTaskBusy { .. }
1787 ) {
1788 acquisition_counters.record_writer_task_begin_error();
1789 }
1790 sealed::Sealed::reply_error_after_begin(
1791 request,
1792 begin_error,
1793 queue_wait,
1794 transaction_acquire,
1795 );
1796 None
1797 }
1798 }
1799 };
1800 conn.finish(terminal_state)
1801 })();
1802 (outcome, blocking_sink_lease)
1803 })
1804 .await;
1805
1806 match outcome {
1807 Ok(((Some(returned_conn), None), _sink_lease)) => owner.0 = returned_conn,
1808 Ok(((_returned_conn, Some(request_state)), _sink_lease)) => {
1809 acquisition_counters.record_writer_task_request_failure();
1810 if request_state == WriterTaskRequestState::SideEffectsUnknown {
1811 acquisition_counters.record_writer_task_side_effects_unknown();
1812 }
1813 tracing::error!(
1814 request_state = %request_state,
1815 "writer task reached a terminal request or connection state; closing and \
1816 failing the queue without restarting"
1817 );
1818 crate::timeout_sink::emit_writer_task_retirement(
1819 &db,
1820 &format!("terminal request state: {request_state}"),
1821 );
1822 close_and_fail_queued_requests(&mut rx).await;
1823 return;
1824 }
1825 Ok(((None, None), _sink_lease)) => {
1826 unreachable!("a reusable writer returns its connection")
1827 }
1828 Err(join_err) => {
1829 acquisition_counters.record_writer_task_request_failure();
1830 tracing::error!(
1831 error = %join_err,
1832 "writer task blocking closure failed outside the request \
1833 panic boundary; closing and failing the queue without restarting"
1834 );
1835 crate::timeout_sink::emit_writer_task_retirement(
1836 &db,
1837 &format!("blocking closure join failure: {join_err}"),
1838 );
1839 close_and_fail_queued_requests(&mut rx).await;
1840 return;
1841 }
1842 }
1843 }
1844}
1845
1846#[cfg(test)]
1847#[path = "writer_task_tests.rs"]
1848mod tests;
1849
1850#[cfg(test)]
1851#[path = "writer_task_lease_close_tests.rs"]
1852mod volume_lease_close_tests;
1853
1854#[cfg(test)]
1855#[path = "writer_task_slow_write_label_tests.rs"]
1856mod slow_write_label_tests;
1857
1858#[cfg(all(test, any(unix, windows)))]
1859#[path = "writer_task_identity_tests.rs"]
1860mod identity_tests;
1861
1862#[cfg(test)]
1863#[path = "writer_routing_outcome_tests.rs"]
1864mod writer_routing_outcome_tests;
1865
1866#[cfg(test)]
1867mod reply_evidence_tests {
1868 use super::*;
1869 use crate::test_hooks::TestHooks;
1870 use rusqlite::hooks::{AuthAction, AuthContext, Authorization, TransactionOperation};
1871
1872 #[tokio::test]
1873 async fn lost_delivery_retains_real_statement_and_commit_failures() {
1874 for fail_commit in [false, true] {
1875 let conn = crate::test_hooks::registered(Connection::open_in_memory().unwrap());
1876 conn.execute_batch("CREATE TABLE receipt_probe(id INTEGER PRIMARY KEY); INSERT INTO receipt_probe VALUES(1); BEGIN IMMEDIATE").unwrap();
1877 if fail_commit {
1878 conn.test_authorizer(Some(|context: AuthContext<'_>| match context.action {
1879 AuthAction::Transaction {
1880 operation: TransactionOperation::Unknown,
1881 } => Authorization::Deny,
1882 _ => Authorization::Allow,
1883 }))
1884 .unwrap();
1885 }
1886 let receipt = Arc::new(ReplyReceipt::default());
1887 let profiled = execute_wrapped_transaction_profiled(
1888 &conn,
1889 "receipt_commit",
1890 None,
1891 false,
1892 Some(&receipt.commit_issued),
1893 |conn| {
1894 conn.execute(
1895 "INSERT INTO receipt_probe VALUES(?1)",
1896 [if fail_commit { 2 } else { 1 }],
1897 )
1898 .map_err(|error| {
1899 StorageError::driver(
1900 khive_storage::StorageCapability::Sql,
1901 "receipt_statement",
1902 error,
1903 )
1904 })
1905 },
1906 None,
1907 );
1908 assert!(
1909 conn.is_autocommit(),
1910 "both real failures must prove rollback before lost delivery"
1911 );
1912 assert_eq!(receipt.commit_issued.load(Ordering::Acquire), fail_commit);
1913 *receipt.completed() = Some(profiled.result);
1914 let (reply, reply_rx) = oneshot::channel();
1915 drop(reply);
1916 let error = PendingWrite { reply_rx, receipt }
1917 .wait()
1918 .await
1919 .expect_err("retained failure");
1920 let failure = crate::error::native_write_failure(
1921 &error,
1922 khive_storage::error::SqliteWriteStage::Statement,
1923 );
1924 let expected_code = if fail_commit {
1925 rusqlite::ffi::SQLITE_AUTH
1926 } else {
1927 rusqlite::ffi::SQLITE_CONSTRAINT
1928 };
1929 assert!(
1930 failure
1931 .is_some_and(|failure| failure.primary_code == expected_code
1932 && !failure.settlement_unknown),
1933 "lost delivery must retain the real native code and known rollback: {error:?}"
1934 );
1935 assert!(!error.is_write_outcome_unknown());
1936 let count: i64 = conn
1937 .query_row("SELECT count(*) FROM receipt_probe", [], |row| row.get(0))
1938 .unwrap();
1939 assert_eq!(count, 1, "real rollback preserves the original stored row");
1940 }
1941 }
1942}